[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Texi2html-cvs] texi2html/test/tar_manual res/tar/tar.2 res/tar...
|
From: |
Patrice Dumas |
|
Subject: |
[Texi2html-cvs] texi2html/test/tar_manual res/tar/tar.2 res/tar... |
|
Date: |
Sun, 02 Aug 2009 13:46:18 +0000 |
CVSROOT: /cvsroot/texi2html
Module name: texi2html
Changes by: Patrice Dumas <pertusus> 09/08/02 13:46:16
Modified files:
test/tar_manual/res/tar: tar.2 tar.html
test/tar_manual/res/texi_tar: tar.2 tar.passfirst tar.passtexi
tar.texi
test/tar_manual/res_all/tar: tar.2
test/tar_manual/res_all/texi_tar: tar.2 tar.passfirst
tar.passtexi tar.texi
test/tar_manual/res_info/tar: tar.2
test/tar_manual/res_info/texi_tar: tar.2 tar.passfirst
tar.passtexi tar.texi
Added files:
test/tar_manual/res/texi_tar: tar.texi.first
test/tar_manual/res_all/texi_tar: tar.texi.first
test/tar_manual/res_info/texi_tar: tar.texi.first
Log message:
* texi2html.pl, texi2html.init: treat @alias like a normal misc
commmand.
Keep @macros definitions in output, treat them as raw
environments
that can be nested.
Warn for deprecated commands.
* texi2html.init: @syncodeindex and @finalout swallow end of
line.
* formats/html.init: Don't double in title when the @top and
@settitle are the same.
* texi2html.pl: add 0x7F as a comment character.
Still provide the default output with --macro-expand.
warning if macro with an argument number different than 1
is called without a {}.
Read TEXINFO_OUTPUT_FORMAT in env to determine the output
format,
if not overridden by a command line option.
More error and warning messages, especially for info.
Warn for superfluous @node arguments.
Remove whitespaces after formats, even in last pass.
* Makefile.am, documentlanguages.pl,
regenerate_documentlanguages.pl:
Gather language codes and regions from the iana registery file.
* formats/info.init: remove last end of line in @image file.txt
Warn if there is a float or anchor before first node.
* tests/*: run only once to generate the the texi_* output.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res/tar/tar.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res/tar/tar.html?cvsroot=texi2html&r1=1.17&r2=1.18
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res/texi_tar/tar.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res/texi_tar/tar.passfirst?cvsroot=texi2html&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res/texi_tar/tar.passtexi?cvsroot=texi2html&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res/texi_tar/tar.texi?cvsroot=texi2html&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res/texi_tar/tar.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_all/tar/tar.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_all/texi_tar/tar.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_all/texi_tar/tar.passfirst?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_all/texi_tar/tar.passtexi?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_all/texi_tar/tar.texi?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_all/texi_tar/tar.texi.first?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_info/tar/tar.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_info/texi_tar/tar.2?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_info/texi_tar/tar.passfirst?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_info/texi_tar/tar.passtexi?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_info/texi_tar/tar.texi?cvsroot=texi2html&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/texi2html/test/tar_manual/res_info/texi_tar/tar.texi.first?cvsroot=texi2html&rev=1.1
Patches:
Index: res/tar/tar.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/tar_manual/res/tar/tar.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res/tar/tar.2 18 Aug 2008 18:09:36 -0000 1.1
+++ res/tar/tar.2 2 Aug 2009 13:46:12 -0000 1.2
@@ -0,0 +1,142 @@
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1050)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1526)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1777)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 2083)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3757)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3808)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3884)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3997)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4168)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4223)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4378)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4399)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4476)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4927)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5073)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5144)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5231)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6014)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6039)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6414)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7208)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7304)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7385)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7421)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7532)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8062)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8904)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9016)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9060)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9280)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9408)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9432)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9785)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9826)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10183)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10245)
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
.././tar_manual/intern.texi l. 16)
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
.././tar_manual/intern.texi l. 271)
+** @allow-recursion is obsolete; please use @macro instead. (l. 455 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 455 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 606 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 606 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 609 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 609 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 643 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 643 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 689 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 689 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 711 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 711 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 753 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 753 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1242 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1242 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1750 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1750 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1767 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1767 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1773 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1773 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1956 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1956 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 2224 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 2224 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3744 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3744 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3864 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3864 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4014 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4014 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4094 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4094 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4215 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4215 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4436 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4436 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4478 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4478 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4917 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4917 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5077 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5077 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5079 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5079 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5133 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5133 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5209 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5209 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6410 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6410 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6549 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6549 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6585 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6585 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7310 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7310 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7424 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7424 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7591 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7591 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7593 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7593 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7602 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7602 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8038 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8038 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8197 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8197 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8218 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8218 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8548 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8548 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8906 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8906 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9459 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9459 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9640 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9640 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9690 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9690 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9829 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9829 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9837 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9837 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9849 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9849 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9874 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9874 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10238 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10238 in
@FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in
.././tar_manual/intern.texi l. 40 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in
.././tar_manual/intern.texi l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in
.././tar_manual/intern.texi l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in
.././tar_manual/intern.texi l. 115 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in
.././tar_manual/genfile.texi l. 179 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in
.././tar_manual/genfile.texi l. 179 in @FIXME)
Index: res/tar/tar.html
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/tar_manual/res/tar/tar.html,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -b -r1.17 -r1.18
--- res/tar/tar.html 31 Jul 2009 10:18:30 -0000 1.17
+++ res/tar/tar.html 2 Aug 2009 13:46:12 -0000 1.18
@@ -15955,7 +15955,7 @@
<h2 class="appendixsec">F.1 GNU Free Documentation License</h2>
<a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
-<p align="center"> Version 1.2, November 2002
+<p align="center">Version 1.2, November 2002
</p>
<table><tr><td> </td><td><pre class="display">Copyright ©
2000,2001,2002 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
Index: res/texi_tar/tar.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/tar_manual/res/texi_tar/tar.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res/texi_tar/tar.2 18 Aug 2008 18:09:37 -0000 1.1
+++ res/texi_tar/tar.2 2 Aug 2009 13:46:13 -0000 1.2
@@ -32,10 +32,12 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1050)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1526)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -48,10 +50,12 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1777)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 2083)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -64,10 +68,14 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3757)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3808)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3884)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3997)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -76,14 +84,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4168)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4223)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4378)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4399)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4476)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -92,6 +105,8 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4927)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5073)
# Popped `strong' in ifset/ifclear
# Popped `command' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
@@ -106,6 +121,7 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5144)
# Popped `strong' in ifset/ifclear
# Popped `acronym' in ifset/ifclear
# Popped `command' in ifset/ifclear
@@ -120,10 +136,14 @@
# Popped `var' in ifset/ifclear
# Popped `option' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5231)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6014)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6039)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6414)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -136,14 +156,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7208)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7304)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7385)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7421)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7532)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -174,6 +199,7 @@
# Popped `emph' in ifset/ifclear
# Popped `code' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8062)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -188,10 +214,16 @@
# Popped `strong' in ifset/ifclear
# Popped `acronym' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8904)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9016)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9060)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9280)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9408)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9432)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -204,6 +236,8 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9785)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9826)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -220,16 +254,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10183)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10245)
# Popped `strong' in ifset/ifclear
# Popped `anchor' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `anchor' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
.././tar_manual/intern.texi l. 16)
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -240,9 +277,114 @@
# Popped `option' in ifset/ifclear
# Popped `option' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
.././tar_manual/intern.texi l. 271)
# Popped `strong' in ifset/ifclear
# Popped `samp' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `samp' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @allow-recursion is obsolete; please use @macro instead. (l. 455 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 455 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 606 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 606 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 609 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 609 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 643 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 643 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 689 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 689 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 711 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 711 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 753 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 753 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1242 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1242 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1750 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1750 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1767 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1767 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1773 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1773 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1956 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1956 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 2224 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 2224 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3744 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3744 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3864 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3864 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4014 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4014 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4094 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4094 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4215 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4215 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4436 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4436 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4478 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4478 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4917 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4917 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5077 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5077 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5079 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5079 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5133 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5133 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5209 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5209 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6410 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6410 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6549 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6549 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6585 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6585 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7310 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7310 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7424 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7424 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7591 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7591 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7593 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7593 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7602 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7602 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8038 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8038 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8197 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8197 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8218 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8218 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8548 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8548 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8906 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8906 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9459 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9459 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9640 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9640 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9690 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9690 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9829 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9829 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9837 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9837 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9849 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9849 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9874 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9874 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10238 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10238 in
@FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in
.././tar_manual/intern.texi l. 40 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in
.././tar_manual/intern.texi l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in
.././tar_manual/intern.texi l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in
.././tar_manual/intern.texi l. 115 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in
.././tar_manual/genfile.texi l. 179 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in
.././tar_manual/genfile.texi l. 179 in @FIXME)
Index: res/texi_tar/tar.passfirst
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/tar_manual/res/texi_tar/tar.passfirst,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- res/texi_tar/tar.passfirst 2 May 2009 11:31:19 -0000 1.4
+++ res/texi_tar/tar.passfirst 2 Aug 2009 13:46:13 -0000 1.5
@@ -51,12 +51,53 @@
rendition.texi(,44)
rendition.texi(,45) @c Output marks for nodes needing revision, but not in
PUBLISH rendition.
rendition.texi(,46)
+rendition.texi(,47) @macro UNREVISED
+rendition.texi(,48) @ifclear PUBLISH
+rendition.texi(,49) @quotation
+rendition.texi(,50) @emph{(This message will disappear, once this node
revised.)}
+rendition.texi(,51) @end quotation
+rendition.texi(,52) @end ifclear
+rendition.texi(,53) @end macro
rendition.texi(,54)
rendition.texi(,55) @c Output various FIXME information only in PROOF
rendition.
rendition.texi(,56)
+rendition.texi(,57) @macro FIXME{string}
+rendition.texi(,58) @allow-recursion
+rendition.texi(,59) @quote-arg
+rendition.texi(,60) @ifset PROOF
+rendition.texi(,61) @ifset PROOF_FOOTNOTED
+rendition.texi(,62) @address@hidden:} \string\}
+rendition.texi(,63) @end ifset
+rendition.texi(,64) @ifclear PROOF_FOOTNOTED
+rendition.texi(,65) @cartouche
+rendition.texi(,66) @strong{<FIXME>} \string\ @strong{</>}
+rendition.texi(,67) @end cartouche
+rendition.texi(,68) @end ifclear
+rendition.texi(,69) @end ifset
+rendition.texi(,70)
+rendition.texi(,71) @end macro
rendition.texi(,72)
+rendition.texi(,73) @macro FIXME-ref{string}
+rendition.texi(,74) @quote-arg
+rendition.texi(,75) @ifset PROOF
+rendition.texi(,76) @strong{<REF>} \string\ @strong{</>}
+rendition.texi(,77) @end ifset
+rendition.texi(,78) @end macro
rendition.texi(,79)
+rendition.texi(,80) @macro FIXME-pxref{string}
+rendition.texi(,81) @quote-arg
+rendition.texi(,82) @ifset PROOF
+rendition.texi(,83) @strong{<PXREF>} \string\ @strong{</>}
+rendition.texi(,84) @end ifset
+rendition.texi(,85)
+rendition.texi(,86) @end macro
rendition.texi(,87)
+rendition.texi(,88) @macro FIXME-xref{string}
+rendition.texi(,89) @quote-arg
+rendition.texi(,90) @ifset PROOF
+rendition.texi(,91) @strong{<XREF>} \string\ @strong{</>}
+rendition.texi(,92) @end ifset
+rendition.texi(,93) @end macro
rendition.texi(,94)
rendition.texi(,95) @c End of rendition.texi
value.texi(,1) @c This is part of GNU tar manual.
@@ -64,8 +105,21 @@
value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
value.texi(,4) @c See file tar.texi for copying conditions.
value.texi(,5)
+value.texi(,6) @macro GNUTAR
+value.texi(,7) @acronym{GNU} @command{tar}
+value.texi(,8) @end macro
value.texi(,9)
+value.texi(,10) @macro xopindex{option,text}
+value.texi(,11) @opindex address@hidden, \text\}
+value.texi(,12) @end macro
value.texi(,13)
+value.texi(,14) @macro opsummary{option}
+value.texi(,15) @ifclear ANCHOR--\option\
+value.texi(,16) @set ANCHOR--\option\ 1
+value.texi(,17) @anchor{--\option\}
+value.texi(,18) @end ifclear
+value.texi(,19) @xopindex{\option\, summary}
+value.texi(,20) @end macro
value.texi(,21)
value.texi(,22)
tar.texi(,22)
Index: res/texi_tar/tar.passtexi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/tar_manual/res/texi_tar/tar.passtexi,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- res/texi_tar/tar.passtexi 2 May 2009 11:31:19 -0000 1.4
+++ res/texi_tar/tar.passtexi 2 Aug 2009 13:46:13 -0000 1.5
@@ -51,12 +51,53 @@
rendition.texi(,44)
rendition.texi(,45) @c Output marks for nodes needing revision, but not in
PUBLISH rendition.
rendition.texi(,46)
+rendition.texi(,47) @macro UNREVISED
+rendition.texi(,48) @ifclear PUBLISH
+rendition.texi(,49) @quotation
+rendition.texi(,50) @emph{(This message will disappear, once this node
revised.)}
+rendition.texi(,51) @end quotation
+rendition.texi(,52) @end ifclear
+rendition.texi(,53) @end macro
rendition.texi(,54)
rendition.texi(,55) @c Output various FIXME information only in PROOF
rendition.
rendition.texi(,56)
+rendition.texi(,57) @macro FIXME{string}
+rendition.texi(,58) @allow-recursion
+rendition.texi(,59) @quote-arg
+rendition.texi(,60) @ifset PROOF
+rendition.texi(,61) @ifset PROOF_FOOTNOTED
+rendition.texi(,62) @address@hidden:} \string\}
+rendition.texi(,63) @end ifset
+rendition.texi(,64) @ifclear PROOF_FOOTNOTED
+rendition.texi(,65) @cartouche
+rendition.texi(,66) @strong{<FIXME>} \string\ @strong{</>}
+rendition.texi(,67) @end cartouche
+rendition.texi(,68) @end ifclear
+rendition.texi(,69) @end ifset
+rendition.texi(,70)
+rendition.texi(,71) @end macro
rendition.texi(,72)
+rendition.texi(,73) @macro FIXME-ref{string}
+rendition.texi(,74) @quote-arg
+rendition.texi(,75) @ifset PROOF
+rendition.texi(,76) @strong{<REF>} \string\ @strong{</>}
+rendition.texi(,77) @end ifset
+rendition.texi(,78) @end macro
rendition.texi(,79)
+rendition.texi(,80) @macro FIXME-pxref{string}
+rendition.texi(,81) @quote-arg
+rendition.texi(,82) @ifset PROOF
+rendition.texi(,83) @strong{<PXREF>} \string\ @strong{</>}
+rendition.texi(,84) @end ifset
+rendition.texi(,85)
+rendition.texi(,86) @end macro
rendition.texi(,87)
+rendition.texi(,88) @macro FIXME-xref{string}
+rendition.texi(,89) @quote-arg
+rendition.texi(,90) @ifset PROOF
+rendition.texi(,91) @strong{<XREF>} \string\ @strong{</>}
+rendition.texi(,92) @end ifset
+rendition.texi(,93) @end macro
rendition.texi(,94)
rendition.texi(,95) @c End of rendition.texi
value.texi(,1) @c This is part of GNU tar manual.
@@ -64,8 +105,21 @@
value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
value.texi(,4) @c See file tar.texi for copying conditions.
value.texi(,5)
+value.texi(,6) @macro GNUTAR
+value.texi(,7) @acronym{GNU} @command{tar}
+value.texi(,8) @end macro
value.texi(,9)
+value.texi(,10) @macro xopindex{option,text}
+value.texi(,11) @opindex address@hidden, \text\}
+value.texi(,12) @end macro
value.texi(,13)
+value.texi(,14) @macro opsummary{option}
+value.texi(,15) @ifclear ANCHOR--\option\
+value.texi(,16) @set ANCHOR--\option\ 1
+value.texi(,17) @anchor{--\option\}
+value.texi(,18) @end ifclear
+value.texi(,19) @xopindex{\option\, summary}
+value.texi(,20) @end macro
value.texi(,21)
value.texi(,22)
tar.texi(,22)
Index: res/texi_tar/tar.texi
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/tar_manual/res/texi_tar/tar.texi,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- res/texi_tar/tar.texi 2 May 2009 11:31:19 -0000 1.4
+++ res/texi_tar/tar.texi 2 Aug 2009 13:46:13 -0000 1.5
@@ -52,12 +52,53 @@
@c Output marks for nodes needing revision, but not in PUBLISH rendition.
address@hidden UNREVISED
address@hidden PUBLISH
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden ifclear
address@hidden macro
@c Output various FIXME information only in PROOF rendition.
address@hidden FIXME{string}
address@hidden
address@hidden
address@hidden PROOF
address@hidden PROOF_FOOTNOTED
address@hidden@strong{FIXME:} \string\}
address@hidden ifset
address@hidden PROOF_FOOTNOTED
address@hidden
address@hidden<FIXME>} \string\ @strong{</>}
address@hidden cartouche
address@hidden ifclear
address@hidden ifset
+
address@hidden macro
address@hidden FIXME-ref{string}
address@hidden
address@hidden PROOF
address@hidden<REF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden FIXME-pxref{string}
address@hidden
address@hidden PROOF
address@hidden<PXREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
address@hidden FIXME-xref{string}
address@hidden
address@hidden PROOF
address@hidden<XREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
@c End of rendition.texi
@c This is part of GNU tar manual.
@@ -65,8 +106,21 @@
@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file tar.texi for copying conditions.
-
-
address@hidden GNUTAR
address@hidden @command{tar}
address@hidden macro
+
address@hidden xopindex{option,text}
address@hidden address@hidden, \text\}
address@hidden macro
+
address@hidden opsummary{option}
address@hidden ANCHOR--\option\
address@hidden ANCHOR--\option\ 1
address@hidden
address@hidden ifclear
address@hidden, summary}
address@hidden macro
Index: res_all/tar/tar.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/tar_manual/res_all/tar/tar.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/tar/tar.2 31 Jul 2009 10:18:31 -0000 1.1
+++ res_all/tar/tar.2 2 Aug 2009 13:46:14 -0000 1.2
@@ -0,0 +1,142 @@
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1050)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1526)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1777)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 2083)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3757)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3808)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3884)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3997)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4168)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4223)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4378)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4399)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4476)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4927)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5073)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5144)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5231)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6014)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6039)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6414)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7208)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7304)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7385)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7421)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7532)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8062)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8904)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9016)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9060)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9280)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9408)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9432)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9785)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9826)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10183)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10245)
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
./intern.texi l. 16)
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
./intern.texi l. 271)
+** @allow-recursion is obsolete; please use @macro instead. (l. 455 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 455 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 606 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 606 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 609 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 609 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 643 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 643 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 689 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 689 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 711 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 711 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 753 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 753 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1242 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1242 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1750 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1750 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1767 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1767 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1773 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1773 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1956 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1956 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 2224 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 2224 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3744 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3744 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3864 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3864 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4014 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4014 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4094 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4094 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4215 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4215 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4436 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4436 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4478 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4478 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4917 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4917 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5077 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5077 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5079 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5079 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5133 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5133 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5209 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5209 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6410 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6410 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6549 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6549 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6585 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6585 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7310 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7310 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7424 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7424 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7591 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7591 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7593 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7593 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7602 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7602 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8038 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8038 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8197 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8197 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8218 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8218 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8548 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8548 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8906 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8906 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9459 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9459 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9640 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9640 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9690 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9690 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9829 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9829 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9837 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9837 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9849 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9849 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9874 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9874 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10238 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10238 in
@FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 40 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in ./intern.texi
l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 115 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in ./genfile.texi
l. 179 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./genfile.texi
l. 179 in @FIXME)
Index: res_all/texi_tar/tar.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/tar_manual/res_all/texi_tar/tar.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_tar/tar.2 28 Jul 2009 18:42:53 -0000 1.1
+++ res_all/texi_tar/tar.2 2 Aug 2009 13:46:14 -0000 1.2
@@ -32,10 +32,12 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1050)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1526)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -48,10 +50,12 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1777)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 2083)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -64,10 +68,14 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3757)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3808)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3884)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3997)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -76,14 +84,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4168)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4223)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4378)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4399)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4476)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -92,6 +105,8 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4927)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5073)
# Popped `strong' in ifset/ifclear
# Popped `command' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
@@ -106,6 +121,7 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5144)
# Popped `strong' in ifset/ifclear
# Popped `acronym' in ifset/ifclear
# Popped `command' in ifset/ifclear
@@ -120,10 +136,14 @@
# Popped `var' in ifset/ifclear
# Popped `option' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5231)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6014)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6039)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6414)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -136,14 +156,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7208)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7304)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7385)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7421)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7532)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -174,6 +199,7 @@
# Popped `emph' in ifset/ifclear
# Popped `code' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8062)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -188,10 +214,16 @@
# Popped `strong' in ifset/ifclear
# Popped `acronym' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8904)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9016)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9060)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9280)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9408)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9432)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -204,6 +236,8 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9785)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9826)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -220,16 +254,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10183)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10245)
# Popped `strong' in ifset/ifclear
# Popped `anchor' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `anchor' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
./intern.texi l. 16)
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -240,9 +277,114 @@
# Popped `option' in ifset/ifclear
# Popped `option' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
./intern.texi l. 271)
# Popped `strong' in ifset/ifclear
# Popped `samp' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `samp' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @allow-recursion is obsolete; please use @macro instead. (l. 455 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 455 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 606 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 606 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 609 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 609 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 643 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 643 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 689 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 689 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 711 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 711 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 753 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 753 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1242 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1242 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1750 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1750 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1767 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1767 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1773 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1773 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1956 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1956 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 2224 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 2224 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3744 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3744 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3864 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3864 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4014 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4014 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4094 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4094 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4215 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4215 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4436 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4436 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4478 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4478 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4917 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4917 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5077 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5077 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5079 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5079 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5133 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5133 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5209 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5209 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6410 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6410 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6549 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6549 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6585 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6585 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7310 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7310 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7424 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7424 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7591 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7591 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7593 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7593 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7602 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7602 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8038 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8038 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8197 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8197 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8218 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8218 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8548 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8548 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8906 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8906 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9459 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9459 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9640 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9640 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9690 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9690 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9829 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9829 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9837 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9837 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9849 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9849 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9874 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9874 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10238 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10238 in
@FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 40 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in ./intern.texi
l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 115 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in ./genfile.texi
l. 179 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./genfile.texi
l. 179 in @FIXME)
Index: res_all/texi_tar/tar.passfirst
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/tar_manual/res_all/texi_tar/tar.passfirst,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_tar/tar.passfirst 28 Jul 2009 18:42:53 -0000 1.1
+++ res_all/texi_tar/tar.passfirst 2 Aug 2009 13:46:14 -0000 1.2
@@ -51,12 +51,53 @@
rendition.texi(,44)
rendition.texi(,45) @c Output marks for nodes needing revision, but not in
PUBLISH rendition.
rendition.texi(,46)
+rendition.texi(,47) @macro UNREVISED
+rendition.texi(,48) @ifclear PUBLISH
+rendition.texi(,49) @quotation
+rendition.texi(,50) @emph{(This message will disappear, once this node
revised.)}
+rendition.texi(,51) @end quotation
+rendition.texi(,52) @end ifclear
+rendition.texi(,53) @end macro
rendition.texi(,54)
rendition.texi(,55) @c Output various FIXME information only in PROOF
rendition.
rendition.texi(,56)
+rendition.texi(,57) @macro FIXME{string}
+rendition.texi(,58) @allow-recursion
+rendition.texi(,59) @quote-arg
+rendition.texi(,60) @ifset PROOF
+rendition.texi(,61) @ifset PROOF_FOOTNOTED
+rendition.texi(,62) @address@hidden:} \string\}
+rendition.texi(,63) @end ifset
+rendition.texi(,64) @ifclear PROOF_FOOTNOTED
+rendition.texi(,65) @cartouche
+rendition.texi(,66) @strong{<FIXME>} \string\ @strong{</>}
+rendition.texi(,67) @end cartouche
+rendition.texi(,68) @end ifclear
+rendition.texi(,69) @end ifset
+rendition.texi(,70)
+rendition.texi(,71) @end macro
rendition.texi(,72)
+rendition.texi(,73) @macro FIXME-ref{string}
+rendition.texi(,74) @quote-arg
+rendition.texi(,75) @ifset PROOF
+rendition.texi(,76) @strong{<REF>} \string\ @strong{</>}
+rendition.texi(,77) @end ifset
+rendition.texi(,78) @end macro
rendition.texi(,79)
+rendition.texi(,80) @macro FIXME-pxref{string}
+rendition.texi(,81) @quote-arg
+rendition.texi(,82) @ifset PROOF
+rendition.texi(,83) @strong{<PXREF>} \string\ @strong{</>}
+rendition.texi(,84) @end ifset
+rendition.texi(,85)
+rendition.texi(,86) @end macro
rendition.texi(,87)
+rendition.texi(,88) @macro FIXME-xref{string}
+rendition.texi(,89) @quote-arg
+rendition.texi(,90) @ifset PROOF
+rendition.texi(,91) @strong{<XREF>} \string\ @strong{</>}
+rendition.texi(,92) @end ifset
+rendition.texi(,93) @end macro
rendition.texi(,94)
rendition.texi(,95) @c End of rendition.texi
value.texi(,1) @c This is part of GNU tar manual.
@@ -64,8 +105,21 @@
value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
value.texi(,4) @c See file tar.texi for copying conditions.
value.texi(,5)
+value.texi(,6) @macro GNUTAR
+value.texi(,7) @acronym{GNU} @command{tar}
+value.texi(,8) @end macro
value.texi(,9)
+value.texi(,10) @macro xopindex{option,text}
+value.texi(,11) @opindex address@hidden, \text\}
+value.texi(,12) @end macro
value.texi(,13)
+value.texi(,14) @macro opsummary{option}
+value.texi(,15) @ifclear ANCHOR--\option\
+value.texi(,16) @set ANCHOR--\option\ 1
+value.texi(,17) @anchor{--\option\}
+value.texi(,18) @end ifclear
+value.texi(,19) @xopindex{\option\, summary}
+value.texi(,20) @end macro
value.texi(,21)
value.texi(,22)
tar.texi(,22)
Index: res_all/texi_tar/tar.passtexi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/tar_manual/res_all/texi_tar/tar.passtexi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_tar/tar.passtexi 28 Jul 2009 18:42:54 -0000 1.1
+++ res_all/texi_tar/tar.passtexi 2 Aug 2009 13:46:14 -0000 1.2
@@ -51,12 +51,53 @@
rendition.texi(,44)
rendition.texi(,45) @c Output marks for nodes needing revision, but not in
PUBLISH rendition.
rendition.texi(,46)
+rendition.texi(,47) @macro UNREVISED
+rendition.texi(,48) @ifclear PUBLISH
+rendition.texi(,49) @quotation
+rendition.texi(,50) @emph{(This message will disappear, once this node
revised.)}
+rendition.texi(,51) @end quotation
+rendition.texi(,52) @end ifclear
+rendition.texi(,53) @end macro
rendition.texi(,54)
rendition.texi(,55) @c Output various FIXME information only in PROOF
rendition.
rendition.texi(,56)
+rendition.texi(,57) @macro FIXME{string}
+rendition.texi(,58) @allow-recursion
+rendition.texi(,59) @quote-arg
+rendition.texi(,60) @ifset PROOF
+rendition.texi(,61) @ifset PROOF_FOOTNOTED
+rendition.texi(,62) @address@hidden:} \string\}
+rendition.texi(,63) @end ifset
+rendition.texi(,64) @ifclear PROOF_FOOTNOTED
+rendition.texi(,65) @cartouche
+rendition.texi(,66) @strong{<FIXME>} \string\ @strong{</>}
+rendition.texi(,67) @end cartouche
+rendition.texi(,68) @end ifclear
+rendition.texi(,69) @end ifset
+rendition.texi(,70)
+rendition.texi(,71) @end macro
rendition.texi(,72)
+rendition.texi(,73) @macro FIXME-ref{string}
+rendition.texi(,74) @quote-arg
+rendition.texi(,75) @ifset PROOF
+rendition.texi(,76) @strong{<REF>} \string\ @strong{</>}
+rendition.texi(,77) @end ifset
+rendition.texi(,78) @end macro
rendition.texi(,79)
+rendition.texi(,80) @macro FIXME-pxref{string}
+rendition.texi(,81) @quote-arg
+rendition.texi(,82) @ifset PROOF
+rendition.texi(,83) @strong{<PXREF>} \string\ @strong{</>}
+rendition.texi(,84) @end ifset
+rendition.texi(,85)
+rendition.texi(,86) @end macro
rendition.texi(,87)
+rendition.texi(,88) @macro FIXME-xref{string}
+rendition.texi(,89) @quote-arg
+rendition.texi(,90) @ifset PROOF
+rendition.texi(,91) @strong{<XREF>} \string\ @strong{</>}
+rendition.texi(,92) @end ifset
+rendition.texi(,93) @end macro
rendition.texi(,94)
rendition.texi(,95) @c End of rendition.texi
value.texi(,1) @c This is part of GNU tar manual.
@@ -64,8 +105,21 @@
value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
value.texi(,4) @c See file tar.texi for copying conditions.
value.texi(,5)
+value.texi(,6) @macro GNUTAR
+value.texi(,7) @acronym{GNU} @command{tar}
+value.texi(,8) @end macro
value.texi(,9)
+value.texi(,10) @macro xopindex{option,text}
+value.texi(,11) @opindex address@hidden, \text\}
+value.texi(,12) @end macro
value.texi(,13)
+value.texi(,14) @macro opsummary{option}
+value.texi(,15) @ifclear ANCHOR--\option\
+value.texi(,16) @set ANCHOR--\option\ 1
+value.texi(,17) @anchor{--\option\}
+value.texi(,18) @end ifclear
+value.texi(,19) @xopindex{\option\, summary}
+value.texi(,20) @end macro
value.texi(,21)
value.texi(,22)
tar.texi(,22)
Index: res_all/texi_tar/tar.texi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/tar_manual/res_all/texi_tar/tar.texi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_all/texi_tar/tar.texi 28 Jul 2009 18:42:54 -0000 1.1
+++ res_all/texi_tar/tar.texi 2 Aug 2009 13:46:14 -0000 1.2
@@ -52,12 +52,53 @@
@c Output marks for nodes needing revision, but not in PUBLISH rendition.
address@hidden UNREVISED
address@hidden PUBLISH
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden ifclear
address@hidden macro
@c Output various FIXME information only in PROOF rendition.
address@hidden FIXME{string}
address@hidden
address@hidden
address@hidden PROOF
address@hidden PROOF_FOOTNOTED
address@hidden@strong{FIXME:} \string\}
address@hidden ifset
address@hidden PROOF_FOOTNOTED
address@hidden
address@hidden<FIXME>} \string\ @strong{</>}
address@hidden cartouche
address@hidden ifclear
address@hidden ifset
+
address@hidden macro
address@hidden FIXME-ref{string}
address@hidden
address@hidden PROOF
address@hidden<REF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden FIXME-pxref{string}
address@hidden
address@hidden PROOF
address@hidden<PXREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
address@hidden FIXME-xref{string}
address@hidden
address@hidden PROOF
address@hidden<XREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
@c End of rendition.texi
@c This is part of GNU tar manual.
@@ -65,8 +106,21 @@
@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file tar.texi for copying conditions.
-
-
address@hidden GNUTAR
address@hidden @command{tar}
address@hidden macro
+
address@hidden xopindex{option,text}
address@hidden address@hidden, \text\}
address@hidden macro
+
address@hidden opsummary{option}
address@hidden ANCHOR--\option\
address@hidden ANCHOR--\option\ 1
address@hidden
address@hidden ifclear
address@hidden, summary}
address@hidden macro
Index: res_info/tar/tar.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/tar_manual/res_info/tar/tar.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/tar/tar.2 31 Jul 2009 10:18:31 -0000 1.1
+++ res_info/tar/tar.2 2 Aug 2009 13:46:15 -0000 1.2
@@ -0,0 +1,142 @@
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1050)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1526)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1777)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 2083)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3757)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3808)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3884)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3997)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4168)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4223)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4378)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4399)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4476)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4927)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5073)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5144)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5231)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6014)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6039)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6414)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7208)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7304)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7385)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7421)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7532)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8062)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8904)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9016)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9060)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9280)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9408)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9432)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9785)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9826)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10183)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10245)
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
./intern.texi l. 16)
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
./intern.texi l. 271)
+** @allow-recursion is obsolete; please use @macro instead. (l. 455 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 455 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 606 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 606 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 609 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 609 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 643 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 643 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 689 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 689 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 711 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 711 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 753 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 753 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1242 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1242 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1750 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1750 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1767 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1767 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1773 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1773 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1956 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1956 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 2224 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 2224 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3744 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3744 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3864 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3864 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4014 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4014 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4094 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4094 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4215 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4215 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4436 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4436 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4478 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4478 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4917 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4917 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5077 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5077 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5079 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5079 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5133 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5133 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5209 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5209 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6410 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6410 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6549 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6549 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6585 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6585 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7310 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7310 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7424 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7424 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7591 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7591 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7593 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7593 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7602 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7602 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8038 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8038 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8197 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8197 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8218 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8218 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8548 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8548 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8906 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8906 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9459 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9459 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9640 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9640 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9690 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9690 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9829 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9829 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9837 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9837 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9849 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9849 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9874 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9874 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10238 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10238 in
@FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 40 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in ./intern.texi
l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 115 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in ./genfile.texi
l. 179 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./genfile.texi
l. 179 in @FIXME)
Index: res_info/texi_tar/tar.2
===================================================================
RCS file: /cvsroot/texi2html/texi2html/test/tar_manual/res_info/texi_tar/tar.2,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texi_tar/tar.2 28 Jul 2009 18:42:54 -0000 1.1
+++ res_info/texi_tar/tar.2 2 Aug 2009 13:46:15 -0000 1.2
@@ -32,10 +32,12 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1050)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1526)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -48,10 +50,12 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 1777)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 2083)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -64,10 +68,14 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3757)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3808)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3884)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 3997)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -76,14 +84,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4168)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4223)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4378)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4399)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4476)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -92,6 +105,8 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 4927)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5073)
# Popped `strong' in ifset/ifclear
# Popped `command' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
@@ -106,6 +121,7 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5144)
# Popped `strong' in ifset/ifclear
# Popped `acronym' in ifset/ifclear
# Popped `command' in ifset/ifclear
@@ -120,10 +136,14 @@
# Popped `var' in ifset/ifclear
# Popped `option' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 5231)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6014)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6039)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 6414)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -136,14 +156,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7208)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7304)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7385)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7421)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 7532)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -174,6 +199,7 @@
# Popped `emph' in ifset/ifclear
# Popped `code' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8062)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -188,10 +214,16 @@
# Popped `strong' in ifset/ifclear
# Popped `acronym' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 8904)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9016)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9060)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9280)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9408)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9432)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -204,6 +236,8 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9785)
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 9826)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -220,16 +254,19 @@
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10183)
# Popped `strong' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (l. 10245)
# Popped `strong' in ifset/ifclear
# Popped `anchor' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `anchor' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
./intern.texi l. 16)
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `strong' in ifset/ifclear
@@ -240,9 +277,114 @@
# Popped `option' in ifset/ifclear
# Popped `option' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @UNREVISED defined with 0 arguments should be invoked with {} (in
./intern.texi l. 271)
# Popped `strong' in ifset/ifclear
# Popped `samp' in ifset/ifclear
# Popped `footnote' in ifset/ifclear
# Popped `strong' in ifset/ifclear
# Popped `samp' in ifset/ifclear
# Popped `strong' in ifset/ifclear
+** @allow-recursion is obsolete; please use @macro instead. (l. 455 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 455 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 606 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 606 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 609 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 609 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 643 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 643 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 689 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 689 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 711 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 711 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 753 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 753 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1242 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1242 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1750 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1750 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1767 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1767 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1773 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1773 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 1956 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 1956 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 2224 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 2224 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3744 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3744 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 3864 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 3864 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4014 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4014 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4094 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4094 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4215 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4215 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4436 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4436 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4478 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4478 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 4917 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 4917 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5077 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5077 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5079 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5079 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5133 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5133 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 5209 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 5209 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6410 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6410 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6529 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6529 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6549 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6549 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 6585 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 6585 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7310 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7310 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7424 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7424 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7591 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7591 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7593 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7593 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 7602 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 7602 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8038 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8038 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8197 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8197 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8218 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8218 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8548 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8548 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 8906 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 8906 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9459 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9459 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9640 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9640 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9690 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9690 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9829 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9829 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9837 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9837 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9849 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9849 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 9874 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 9874 in @FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10238 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10238 in
@FIXME)
+** @allow-recursion is obsolete; please use @macro instead. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (l. 10534 in
@FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 40 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in ./intern.texi
l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 96 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./intern.texi
l. 115 in @FIXME-xref)
+** @allow-recursion is obsolete; please use @macro instead. (in ./genfile.texi
l. 179 in @FIXME)
+** @quote-arg is obsolete; arguments are quoted by default. (in ./genfile.texi
l. 179 in @FIXME)
Index: res_info/texi_tar/tar.passfirst
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/tar_manual/res_info/texi_tar/tar.passfirst,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texi_tar/tar.passfirst 28 Jul 2009 18:42:54 -0000 1.1
+++ res_info/texi_tar/tar.passfirst 2 Aug 2009 13:46:15 -0000 1.2
@@ -51,12 +51,53 @@
rendition.texi(,44)
rendition.texi(,45) @c Output marks for nodes needing revision, but not in
PUBLISH rendition.
rendition.texi(,46)
+rendition.texi(,47) @macro UNREVISED
+rendition.texi(,48) @ifclear PUBLISH
+rendition.texi(,49) @quotation
+rendition.texi(,50) @emph{(This message will disappear, once this node
revised.)}
+rendition.texi(,51) @end quotation
+rendition.texi(,52) @end ifclear
+rendition.texi(,53) @end macro
rendition.texi(,54)
rendition.texi(,55) @c Output various FIXME information only in PROOF
rendition.
rendition.texi(,56)
+rendition.texi(,57) @macro FIXME{string}
+rendition.texi(,58) @allow-recursion
+rendition.texi(,59) @quote-arg
+rendition.texi(,60) @ifset PROOF
+rendition.texi(,61) @ifset PROOF_FOOTNOTED
+rendition.texi(,62) @address@hidden:} \string\}
+rendition.texi(,63) @end ifset
+rendition.texi(,64) @ifclear PROOF_FOOTNOTED
+rendition.texi(,65) @cartouche
+rendition.texi(,66) @strong{<FIXME>} \string\ @strong{</>}
+rendition.texi(,67) @end cartouche
+rendition.texi(,68) @end ifclear
+rendition.texi(,69) @end ifset
+rendition.texi(,70)
+rendition.texi(,71) @end macro
rendition.texi(,72)
+rendition.texi(,73) @macro FIXME-ref{string}
+rendition.texi(,74) @quote-arg
+rendition.texi(,75) @ifset PROOF
+rendition.texi(,76) @strong{<REF>} \string\ @strong{</>}
+rendition.texi(,77) @end ifset
+rendition.texi(,78) @end macro
rendition.texi(,79)
+rendition.texi(,80) @macro FIXME-pxref{string}
+rendition.texi(,81) @quote-arg
+rendition.texi(,82) @ifset PROOF
+rendition.texi(,83) @strong{<PXREF>} \string\ @strong{</>}
+rendition.texi(,84) @end ifset
+rendition.texi(,85)
+rendition.texi(,86) @end macro
rendition.texi(,87)
+rendition.texi(,88) @macro FIXME-xref{string}
+rendition.texi(,89) @quote-arg
+rendition.texi(,90) @ifset PROOF
+rendition.texi(,91) @strong{<XREF>} \string\ @strong{</>}
+rendition.texi(,92) @end ifset
+rendition.texi(,93) @end macro
rendition.texi(,94)
rendition.texi(,95) @c End of rendition.texi
value.texi(,1) @c This is part of GNU tar manual.
@@ -64,8 +105,21 @@
value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
value.texi(,4) @c See file tar.texi for copying conditions.
value.texi(,5)
+value.texi(,6) @macro GNUTAR
+value.texi(,7) @acronym{GNU} @command{tar}
+value.texi(,8) @end macro
value.texi(,9)
+value.texi(,10) @macro xopindex{option,text}
+value.texi(,11) @opindex address@hidden, \text\}
+value.texi(,12) @end macro
value.texi(,13)
+value.texi(,14) @macro opsummary{option}
+value.texi(,15) @ifclear ANCHOR--\option\
+value.texi(,16) @set ANCHOR--\option\ 1
+value.texi(,17) @anchor{--\option\}
+value.texi(,18) @end ifclear
+value.texi(,19) @xopindex{\option\, summary}
+value.texi(,20) @end macro
value.texi(,21)
value.texi(,22)
tar.texi(,22)
Index: res_info/texi_tar/tar.passtexi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/tar_manual/res_info/texi_tar/tar.passtexi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texi_tar/tar.passtexi 28 Jul 2009 18:42:54 -0000 1.1
+++ res_info/texi_tar/tar.passtexi 2 Aug 2009 13:46:15 -0000 1.2
@@ -51,12 +51,53 @@
rendition.texi(,44)
rendition.texi(,45) @c Output marks for nodes needing revision, but not in
PUBLISH rendition.
rendition.texi(,46)
+rendition.texi(,47) @macro UNREVISED
+rendition.texi(,48) @ifclear PUBLISH
+rendition.texi(,49) @quotation
+rendition.texi(,50) @emph{(This message will disappear, once this node
revised.)}
+rendition.texi(,51) @end quotation
+rendition.texi(,52) @end ifclear
+rendition.texi(,53) @end macro
rendition.texi(,54)
rendition.texi(,55) @c Output various FIXME information only in PROOF
rendition.
rendition.texi(,56)
+rendition.texi(,57) @macro FIXME{string}
+rendition.texi(,58) @allow-recursion
+rendition.texi(,59) @quote-arg
+rendition.texi(,60) @ifset PROOF
+rendition.texi(,61) @ifset PROOF_FOOTNOTED
+rendition.texi(,62) @address@hidden:} \string\}
+rendition.texi(,63) @end ifset
+rendition.texi(,64) @ifclear PROOF_FOOTNOTED
+rendition.texi(,65) @cartouche
+rendition.texi(,66) @strong{<FIXME>} \string\ @strong{</>}
+rendition.texi(,67) @end cartouche
+rendition.texi(,68) @end ifclear
+rendition.texi(,69) @end ifset
+rendition.texi(,70)
+rendition.texi(,71) @end macro
rendition.texi(,72)
+rendition.texi(,73) @macro FIXME-ref{string}
+rendition.texi(,74) @quote-arg
+rendition.texi(,75) @ifset PROOF
+rendition.texi(,76) @strong{<REF>} \string\ @strong{</>}
+rendition.texi(,77) @end ifset
+rendition.texi(,78) @end macro
rendition.texi(,79)
+rendition.texi(,80) @macro FIXME-pxref{string}
+rendition.texi(,81) @quote-arg
+rendition.texi(,82) @ifset PROOF
+rendition.texi(,83) @strong{<PXREF>} \string\ @strong{</>}
+rendition.texi(,84) @end ifset
+rendition.texi(,85)
+rendition.texi(,86) @end macro
rendition.texi(,87)
+rendition.texi(,88) @macro FIXME-xref{string}
+rendition.texi(,89) @quote-arg
+rendition.texi(,90) @ifset PROOF
+rendition.texi(,91) @strong{<XREF>} \string\ @strong{</>}
+rendition.texi(,92) @end ifset
+rendition.texi(,93) @end macro
rendition.texi(,94)
rendition.texi(,95) @c End of rendition.texi
value.texi(,1) @c This is part of GNU tar manual.
@@ -64,8 +105,21 @@
value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
value.texi(,4) @c See file tar.texi for copying conditions.
value.texi(,5)
+value.texi(,6) @macro GNUTAR
+value.texi(,7) @acronym{GNU} @command{tar}
+value.texi(,8) @end macro
value.texi(,9)
+value.texi(,10) @macro xopindex{option,text}
+value.texi(,11) @opindex address@hidden, \text\}
+value.texi(,12) @end macro
value.texi(,13)
+value.texi(,14) @macro opsummary{option}
+value.texi(,15) @ifclear ANCHOR--\option\
+value.texi(,16) @set ANCHOR--\option\ 1
+value.texi(,17) @anchor{--\option\}
+value.texi(,18) @end ifclear
+value.texi(,19) @xopindex{\option\, summary}
+value.texi(,20) @end macro
value.texi(,21)
value.texi(,22)
tar.texi(,22)
Index: res_info/texi_tar/tar.texi
===================================================================
RCS file:
/cvsroot/texi2html/texi2html/test/tar_manual/res_info/texi_tar/tar.texi,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- res_info/texi_tar/tar.texi 28 Jul 2009 18:42:55 -0000 1.1
+++ res_info/texi_tar/tar.texi 2 Aug 2009 13:46:15 -0000 1.2
@@ -52,12 +52,53 @@
@c Output marks for nodes needing revision, but not in PUBLISH rendition.
address@hidden UNREVISED
address@hidden PUBLISH
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden ifclear
address@hidden macro
@c Output various FIXME information only in PROOF rendition.
address@hidden FIXME{string}
address@hidden
address@hidden
address@hidden PROOF
address@hidden PROOF_FOOTNOTED
address@hidden@strong{FIXME:} \string\}
address@hidden ifset
address@hidden PROOF_FOOTNOTED
address@hidden
address@hidden<FIXME>} \string\ @strong{</>}
address@hidden cartouche
address@hidden ifclear
address@hidden ifset
+
address@hidden macro
address@hidden FIXME-ref{string}
address@hidden
address@hidden PROOF
address@hidden<REF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden FIXME-pxref{string}
address@hidden
address@hidden PROOF
address@hidden<PXREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
address@hidden FIXME-xref{string}
address@hidden
address@hidden PROOF
address@hidden<XREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
@c End of rendition.texi
@c This is part of GNU tar manual.
@@ -65,8 +106,21 @@
@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file tar.texi for copying conditions.
-
-
address@hidden GNUTAR
address@hidden @command{tar}
address@hidden macro
+
address@hidden xopindex{option,text}
address@hidden address@hidden, \text\}
address@hidden macro
+
address@hidden opsummary{option}
address@hidden ANCHOR--\option\
address@hidden ANCHOR--\option\ 1
address@hidden
address@hidden ifclear
address@hidden, summary}
address@hidden macro
Index: res/texi_tar/tar.texi.first
===================================================================
RCS file: res/texi_tar/tar.texi.first
diff -N res/texi_tar/tar.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res/texi_tar/tar.texi.first 2 Aug 2009 13:46:14 -0000 1.1
@@ -0,0 +1,13572 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden tar.info
address@hidden UPDATED 26 June 2006
address@hidden UPDATED-MONTH June 2006
address@hidden EDITION 1.15.92
address@hidden VERSION 1.15.92
address@hidden GNU tar 1.15.92
address@hidden odd
+
address@hidden
+
address@hidden
address@hidden %**end of header
+
address@hidden Maintenance notes:
address@hidden 1. Pay attention to @FIXME{}s and @UNREVISED{}s
address@hidden 2. Before creating final variant:
address@hidden 2.1. Run `make check-options' to make sure all options are
properly
address@hidden documented;
address@hidden 2.2. Run `make master-menu' (see comment before the master
menu).
+
address@hidden This is part of GNU tar manual.
address@hidden Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
address@hidden 2003, 2004, 2006 Free Software Foundation, Inc.
address@hidden See file tar.texi for copying conditions.
+
address@hidden This file contains support for 'renditions' by Fran@,{c}ois
Pinard
address@hidden I extended it by adding a FIXME_FOOTNOTE variable, which controls
address@hidden whether FIXME information should be placed in footnotes or
address@hidden inlined. --gray
+
address@hidden
======================================================================
address@hidden This document has three levels of rendition: PUBLISH, DISTRIB or
PROOF,
address@hidden as decided by @set symbols. The PUBLISH rendition does not show
address@hidden notes or marks asking for revision. Most users will prefer
having more
address@hidden information, even if this information is not fully revised for
adequacy,
address@hidden so DISTRIB is the default for distributions. The PROOF rendition
address@hidden show all marks to the point of ugliness, but is nevertheless
useful to
address@hidden those working on the manual itself.
address@hidden
======================================================================
+
address@hidden Set this symbol if you wish FIXMEs to appear in footnotes,
instead
address@hidden of being inserted into the text.
address@hidden @set PROOF_FOOTNOTED
+
address@hidden DISTRIB
+
+
address@hidden RENDITION FTP release, version
+
+
address@hidden Output marks for nodes needing revision, but not in PUBLISH
rendition.
+
address@hidden UNREVISED
address@hidden PUBLISH
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden ifclear
address@hidden macro
+
address@hidden Output various FIXME information only in PROOF rendition.
+
address@hidden FIXME{string}
address@hidden
address@hidden
address@hidden PROOF
address@hidden PROOF_FOOTNOTED
address@hidden@strong{FIXME:} \string\}
address@hidden ifset
address@hidden PROOF_FOOTNOTED
address@hidden
address@hidden<FIXME>} \string\ @strong{</>}
address@hidden cartouche
address@hidden ifclear
address@hidden ifset
+
address@hidden macro
+
address@hidden FIXME-ref{string}
address@hidden
address@hidden PROOF
address@hidden<REF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden FIXME-pxref{string}
address@hidden
address@hidden PROOF
address@hidden<PXREF>} \string\ @strong{</>}
address@hidden ifset
+
address@hidden macro
+
address@hidden FIXME-xref{string}
address@hidden
address@hidden PROOF
address@hidden<XREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden End of rendition.texi
address@hidden This is part of GNU tar manual.
address@hidden Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
address@hidden 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
address@hidden See file tar.texi for copying conditions.
+
address@hidden GNUTAR
address@hidden @command{tar}
address@hidden macro
+
address@hidden xopindex{option,text}
address@hidden address@hidden, \text\}
address@hidden macro
+
address@hidden opsummary{option}
address@hidden ANCHOR--\option\
address@hidden ANCHOR--\option\ 1
address@hidden
address@hidden ifclear
address@hidden, summary}
address@hidden macro
+
+
+
address@hidden op
+
address@hidden Put everything in one index (arbitrarily chosen to be the
concept index).
address@hidden fn cp
address@hidden ky cp
address@hidden pg cp
address@hidden vr cp
+
+
address@hidden Archiving
address@hidden
+* Tar: (tar). Making tape (or disk) archives.
address@hidden direntry
+
address@hidden Individual utilities
address@hidden
+* tar: (tar)tar invocation. Invoking @acronym{GNU}
@command{tar}.
address@hidden direntry
+
address@hidden @acronym{GNU} @command{tar}
+
+
address@hidden Top
address@hidden @acronym{GNU} tar: an archiver tool
+
address@hidden
+
address@hidden file archival
address@hidden archiving files
+
+The first part of this master menu lists the major nodes in this Info
+document. The rest of the menu lists all the lower level nodes.
+
address@hidden The master menu goes here.
address@hidden
address@hidden NOTE: To update it from within Emacs, make sure mastermenu.el is
address@hidden loaded and run texinfo-master-menu.
address@hidden To update it from the command line, run
address@hidden
address@hidden make master-menu
+
address@hidden
+* Introduction::
+* Tutorial::
+* tar invocation::
+* operations::
+* Backups::
+* Choosing::
+* Date input formats::
+* Formats::
+* Media::
+
+Appendices
+
+* Changes::
+* Configuring Help Summary::
+* Tar Internals::
+* Genfile::
+* Free Software Needs Free Documentation::
+* Copying This Manual::
+* Index of Command Line Options::
+* Index::
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @acronym{GNU} @command{tar} Authors
+* Reports:: Reporting bugs or suggestions
+
+Tutorial Introduction to @command{tar}
+
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
+
+Two Frequently Used Options
+
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
+
+How to Create Archives
+
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+
+How to List Archives
+
+* list dir::
+
+How to Extract Members from an Archive
+
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
+
+Invoking @acronym{GNU} @command{tar}
+
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
+
+The Three Option Styles
+
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
+
+All @command{tar} Options
+
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+
address@hidden @command{tar} Operations
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+Advanced @acronym{GNU} @command{tar} Operations
+
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+
+How to Add Files to Existing Archives: @option{--append}
+
+* appending files:: Appending Files to an Archive
+* multiple::
+
+Updating an Archive
+
+* how to update::
+
+Options Used by @option{--create}
+
+* override:: Overriding File Metadata.
+* Ignore Failed Read::
+
+Options Used by @option{--extract}
+
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+
+Options to Help Read Archives
+
+* read full records::
+* Ignore Zeros::
+
+Changing How @command{tar} Writes Files
+
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+
+Coping with Scarce Resources
+
+* Starting File::
+* Same Order::
+
+Performing Backups and Restoring Files
+
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental
Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+
+Setting Parameters for Backups and Restoration
+
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+
+Choosing Files and Names for @command{tar}
+
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+
+Reading Names from a File
+
+* nul::
+
+Excluding Some Files
+
+* problems with exclude::
+
+Wildcards Patterns and Matching
+
+* controlling pattern-matching::
+
+Crossing File System Boundaries
+
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+
+Date input formats
+
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
+
+Controlling the Archive Format
+
+* Portability:: Making @command{tar} Archives More Portable
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* cpio:: Comparison of @command{tar} and @command{cpio}
+
+Making @command{tar} Archives More Portable
+
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
+
address@hidden @command{tar} and @acronym{POSIX} @command{tar}
+
+* PAX keywords:: Controlling Extended Header Keywords.
+
+How to Extract GNU-Specific Data Using Other @command{tar} Implementations
+
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
+
+Using Less Space through Compression
+
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+
+Tapes and Other Archive Media
+
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+
+Blocking
+
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+
+Many Archives on One Tape
+
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
+
+Using Multiple Tapes
+
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
+
+Tar Internals
+
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
+
+Storing Sparse Files
+
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
+
+Genfile
+
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
address@hidden detailmenu
address@hidden menu
+
address@hidden Introduction
address@hidden Introduction
+
address@hidden @command{tar} creates
+and manipulates @dfn{archives} which are actually collections of
+many other files; the program provides users with an organized and
+systematic method for controlling a large amount of data.
+The name ``tar'' originally came from the phrase ``Tape ARchive'', but
+archives need not (and these days, typically do not) reside on tapes.
+
address@hidden
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @acronym{GNU} @command{tar} Authors
+* Reports:: Reporting bugs or suggestions
address@hidden menu
+
address@hidden Book Contents
address@hidden What this Book Contains
+
+The first part of this chapter introduces you to various terms that will
+recur throughout the book. It also tells you who has worked on @acronym{GNU}
@command{tar}
+and its documentation, and where you should send bug reports
+or comments.
+
+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
+chapters to make sense. It moves from topic to topic in a logical,
+progressive order, building on information already explained.
+
+Although the tutorial is paced and structured to allow beginners to
+learn how to use @command{tar}, it is not intended solely for beginners.
+The tutorial explains how to use the three most frequently used
+operations (@samp{create}, @samp{list}, and @samp{extract}) as well as
+two frequently used options (@samp{file} and @samp{verbose}). The other
+chapters do not refer to the tutorial frequently; however, if a section
+discusses something which is a complex variant of a basic concept, there
+may be a cross reference to that basic concept. (The entire book,
+including the tutorial, assumes that the reader understands some basic
+concepts of using a Unix-type operating system; @pxref{Tutorial}.)
+
+The third chapter presents the remaining five operations, and
+information about using @command{tar} options and option syntax.
+
address@hidden
address@hidden
+ The other chapters are meant to be used as a
+reference. Each chapter presents everything that needs to be said
+about a specific topic.
+
+One of the chapters (@pxref{Date input formats}) exists in its
+entirety in other @acronym{GNU} manuals, and is mostly self-contained.
+In addition, one section of this manual (@pxref{Standard}) contains a
+big quote which is taken directly from @command{tar} sources.
+
+In general, we give both long and short (abbreviated) option names
+at least once in each section where the relevant option is covered, so
+that novice readers will become familiar with both styles. (A few
+options have no short versions, and the relevant sections will
+indicate this.)
+
address@hidden Definitions
address@hidden Some Definitions
+
address@hidden archive
address@hidden tar archive
+The @command{tar} program is used to create and manipulate @command{tar}
+archives. An @dfn{archive} is a single file which contains the contents
+of many files, while still identifying the names of the files, their
+owner(s), and so forth. (In addition, archives record access
+permissions, user and group, size in bytes, and data modification time.
+Some archives also record the file names in each archived directory, as
+well as other file and directory information.) You can use @command{tar}
+to @dfn{create} a new archive in a specified directory.
+
address@hidden member
address@hidden archive member
address@hidden file name
address@hidden member name
+The files inside an archive are called @dfn{members}. Within this
+manual, we use the term @dfn{file} to refer only to files accessible in
+the normal ways (by @command{ls}, @command{cat}, and so forth), and the term
address@hidden to refer only to the members of an archive. Similarly, a
address@hidden name} is the name of a file, as it resides in the file system,
+and a @dfn{member name} is the name of an archive member within the
+archive.
+
address@hidden extraction
address@hidden unpacking
+The term @dfn{extraction} refers to the process of copying an archive
+member (or multiple members) into a file in the file system. Extracting
+all the members of an archive is often called @dfn{extracting the
+archive}. The term @dfn{unpack} can also be used to refer to the
+extraction of many or all the members of an archive. Extracting an
+archive does not destroy the archive's structure, just as creating an
+archive does not destroy the copies of the files that exist outside of
+the archive. You may also @dfn{list} the members in a given archive
+(this is often thought of as ``printing'' them to the standard output,
+or the command line), or @dfn{append} members to a pre-existing archive.
+All of these operations can be performed using @command{tar}.
+
address@hidden What tar Does
address@hidden What @command{tar} Does
+
address@hidden tar
+The @command{tar} program provides the ability to create @command{tar}
+archives, as well as various other kinds of manipulation. For example,
+you can use @command{tar} on previously created archives to extract files,
+to store additional files, or to update or list files which were already
+stored.
+
+Initially, @command{tar} archives were used to store files conveniently on
+magnetic tape. The name @command{tar} comes from this use; it stands for
address@hidden @code{ar}chiver. Despite the utility's name, @command{tar} can
+direct its output to available devices, files, or other programs (using
+pipes). @command{tar} may even access remote devices or files (as archives).
+
+You can use @command{tar} archives in many ways. We want to stress a few
+of them: storage, backup, and transportation.
+
address@hidden
address@hidden
+
address@hidden @asis
address@hidden Storage
+Often, @command{tar} archives are used to store related files for
+convenient file transfer over a network. For example, the
address@hidden Project distributes its software bundled into
address@hidden archives, so that all the files relating to a particular
+program (or set of related programs) can be transferred as a single
+unit.
+
+A magnetic tape can store several files in sequence. However, the tape
+has no names for these files; it only knows their relative position on
+the tape. One way to store several files on one tape and retain their
+names is by creating a @command{tar} archive. Even when the basic transfer
+mechanism can keep track of names, as FTP can, the nuisance of handling
+multiple files, directories, and multiple links makes @command{tar}
+archives useful.
+
+Archive files are also used for long-term storage. You can think of
+this as transportation from the present into the future. (It is a
+science-fiction idiom that you can move through time as well as in
+space; the idea here is that @command{tar} can be used to move archives in
+all dimensions, even time!)
+
address@hidden Backup
+Because the archive created by @command{tar} is capable of preserving
+file information and directory structure, @command{tar} is commonly
+used for performing full and incremental backups of disks. A backup
+puts a collection of files (possibly pertaining to many users and
+projects) together on a disk or a tape. This guards against
+accidental destruction of the information in those files.
address@hidden @command{tar} has special features that allow it to be
+used to make incremental and full dumps of all the files in a
+file system.
+
address@hidden Transportation
+You can create an archive on one system, transfer it to another system,
+and extract the contents there. This allows you to transport a group of
+files from one system to another.
address@hidden table
+
address@hidden Naming tar Archives
address@hidden How @command{tar} Archives are Named
+
+Conventionally, @command{tar} archives are given names ending with
address@hidden This is not necessary for @command{tar} to operate properly,
+but this manual follows that convention in order to accustom readers to
+it and to make examples more clear.
+
address@hidden tar file
address@hidden entry
address@hidden tar entry
+Often, people refer to @command{tar} archives as address@hidden files,'' and
+archive members as ``files'' or ``entries''. For people familiar with
+the operation of @command{tar}, this causes no difficulty. However, in
+this manual, we consistently refer to ``archives'' and ``archive
+members'' to make learning to use @command{tar} easier for novice users.
+
address@hidden Authors
address@hidden @acronym{GNU} @command{tar} Authors
+
address@hidden @command{tar} was originally written by John Gilmore,
+and modified by many people. The @acronym{GNU} enhancements were
+written by Jay Fenlason, then Joy Kendall, and the whole package has
+been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois
+Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
+numerous and kind users.
+
+We wish to stress that @command{tar} is a collective work, and owes much to
+all those people who reported problems, offered solutions and other
+insights, or shared their thoughts and suggestions. An impressive, yet
+partial list of those contributors can be found in the @file{THANKS}
+file from the @acronym{GNU} @command{tar} distribution.
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
+Jay Fenlason put together a draft of a @acronym{GNU} @command{tar}
+manual, borrowing notes from the original man page from John Gilmore.
+This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy
+Gorin worked on a tutorial and manual for @acronym{GNU} @command{tar}.
+Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
+taking information from all these sources and merging them. Melissa
+Weisshaus finally edited and redesigned the book to create version
+1.12. The book for versions from 1.14 up to 1.15.92 were edited
+by the current maintainer, Sergey Poznyakoff.
+
+For version 1.12, Daniel Hagerty contributed a great deal of technical
+consulting. In particular, he is the primary author of @ref{Backups}.
+
+In July, 2003 @acronym{GNU} @command{tar} was put on CVS at savannah.gnu.org
+(see @url{http://savannah.gnu.org/projects/tar}), and
+active development and maintenance work has started
+again. Currently @acronym{GNU} @command{tar} is being maintained by Paul
Eggert, Sergey
+Poznyakoff and Jeff Bailey.
+
+Support for @acronym{POSIX} archives was added by Sergey Poznyakoff.
+
address@hidden Reports
address@hidden Reporting bugs or suggestions
+
address@hidden bug reports
address@hidden reporting bugs
+If you find problems or have suggestions about this program or manual,
+please report them to @file{bug-tar@@gnu.org}.
+
+When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it. @allow-recursion
address@hidden
+.
+
address@hidden Tutorial
address@hidden Tutorial Introduction to @command{tar}
+
+This chapter guides you through some basic examples of three @command{tar}
+operations: @option{--create}, @option{--list}, and @option{--extract}. If
+you already know how to use some other version of @command{tar}, then you
+may not need to read this chapter. This chapter omits most complicated
+details about how @command{tar} works.
+
address@hidden
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
address@hidden menu
+
address@hidden assumptions
address@hidden Assumptions this Tutorial Makes
+
+This chapter is paced to allow beginners to learn about @command{tar}
+slowly. At the same time, we will try to cover all the basic aspects of
+these three operations. In order to accomplish both of these tasks, we
+have made certain assumptions about your knowledge before reading this
+manual, and the hardware you will be using:
+
address@hidden @bullet
address@hidden
+Before you start to work through this tutorial, you should understand
+what the terms ``archive'' and ``archive member'' mean
+(@pxref{Definitions}). In addition, you should understand something
+about how Unix-type operating systems work, and you should know how to
+use some basic utilities. For example, you should know how to create,
+list, copy, rename, edit, and delete files and directories; how to
+change between directories; and how to figure out where you are in the
+file system. You should have some basic understanding of directory
+structure and how files are named according to which directory they are
+in. You should understand concepts such as standard output and standard
+input, what various definitions of the term ``argument'' mean, and the
+differences between relative and absolute path names. @allow-recursion
address@hidden
+
+
address@hidden
+This manual assumes that you are working from your own home directory
+(unless we state otherwise). In this tutorial, you will create a
+directory to practice @command{tar} commands in. When we show path names,
+we will assume that those paths are relative to your home directory.
+For example, my home directory path is @file{/home/fsf/melissa}. All of
+my examples are in a subdirectory of the directory named by that path
+name; the subdirectory is called @file{practice}.
+
address@hidden
+In general, we show examples of archives which exist on (or can be
+written to, or worked with from) a directory on a hard disk. In most
+cases, you could write those archives to, or work with them on any other
+device, such as a tape drive. However, some of the later examples in
+the tutorial and next chapter will not work on tape drives.
+Additionally, working with tapes is much more complicated than working
+with hard disks. For these reasons, the tutorial does not cover working
+with tape drives. @xref{Media}, for complete information on using
address@hidden archives with tape drives.
+
address@hidden
address@hidden
+
address@hidden itemize
+
address@hidden stylistic conventions
address@hidden Stylistic Conventions
+
+In the examples, @samp{$} represents a typical shell prompt. It
+precedes lines you should type; to make this more clear, those lines are
+shown in @kbd{this font}, as opposed to lines which represent the
+computer's response; those lines are shown in @code{this font}, or
+sometimes @samp{like this}.
+
address@hidden When we have lines which are too long to be
address@hidden displayed in any other way, we will show them like this:
+
address@hidden basic tar options
address@hidden Basic @command{tar} Operations and Options
+
address@hidden can take a wide variety of arguments which specify and define
+the actions it will have on the particular set of files or the archive.
+The main types of arguments to @command{tar} fall into one of two classes:
+operations, and options.
+
+Some arguments fall into a class called @dfn{operations}; exactly one of
+these is both allowed and required for any instance of using @command{tar};
+you may @emph{not} specify more than one. People sometimes speak of
address@hidden modes}. You are in a particular operating mode when you
+have specified the operation which specifies it; there are eight
+operations in total, and thus there are eight operating modes.
+
+The other arguments fall into the class known as @dfn{options}. You are
+not required to specify any options, and you are allowed to specify more
+than one at a time (depending on the way you are using @command{tar} at
+that time). Some options are used so frequently, and are so useful for
+helping you type commands more carefully that they are effectively
+``required''. We will discuss them in this chapter.
+
+You can write most of the @command{tar} operations and options in any
+of three forms: long (mnemonic) form, short form, and old style. Some
+of the operations and options have no short or ``old'' forms; however,
+the operations and options which we will cover in this tutorial have
+corresponding abbreviations. @allow-recursion
address@hidden
+We will indicate those abbreviations appropriately to get
+you used to seeing them. (Note that the ``old style'' option forms
+exist in @acronym{GNU} @command{tar} for compatibility with Unix
address@hidden In this book we present a full discussion of this way
+of writing options and operations (@pxref{Old Options}), and we discuss
+the other two styles of writing options (@xref{Long Options}, and
address@hidden Options}).
+
+In the examples and in the text of this tutorial, we usually use the
+long forms of operations and options; but the ``short'' forms produce
+the same result and can make typing long @command{tar} commands easier.
+For example, instead of typing
+
address@hidden
address@hidden --create --verbose --file=afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+you can type
address@hidden
address@hidden -c -v -f afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+or even
address@hidden
address@hidden -cvf afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+For more information on option syntax, see @ref{Advanced tar}. In
+discussions in the text, when we name an option by its long form, we
+also give the corresponding short option in parentheses.
+
+The term, ``option'', can be confusing at times, since ``operations''
+are often lumped in with the actual, @emph{optional} ``options'' in certain
+general class statements. For example, we just talked about ``short and
+long forms of options and operations''. However, experienced @command{tar}
+users often refer to these by shorthand terms such as, ``short and long
+options''. This term assumes that the ``operations'' are included, also.
+Context will help you determine which definition of ``options'' to use.
+
+Similarly, the term ``command'' can be confusing, as it is often used in
+two different ways. People sometimes refer to @command{tar} ``commands''.
+A @command{tar} @dfn{command} is the entire command line of user input
+which tells @command{tar} what to do --- including the operation, options,
+and any arguments (file names, pipes, other commands, etc). However,
+you will also sometimes hear the term ``the @command{tar} command''. When
+the word ``command'' is used specifically like this, a person is usually
+referring to the @command{tar} @emph{operation}, not the whole line.
+Again, use context to figure out which of the meanings the speaker
+intends.
+
address@hidden frequent operations
address@hidden The Three Most Frequently Used Operations
+
+Here are the three most frequently used operations (both short and long
+forms), as well as a brief description of their meanings. The rest of
+this chapter will cover how to use these operations in detail. We will
+present the rest of the operations in the next chapter.
+
address@hidden @option
address@hidden --create
address@hidden -c
+Create a new @command{tar} archive.
address@hidden --list
address@hidden -t
+List the contents of an archive.
address@hidden --extract
address@hidden -x
+Extract one or more members from an archive.
address@hidden table
+
address@hidden Two Frequent Options
address@hidden Two Frequently Used Options
+
+To understand how to run @command{tar} in the three operating modes listed
+previously, you also need to understand how to use two of the options to
address@hidden: @option{--file} (which takes an archive file as an argument)
+and @option{--verbose}. (You are usually not @emph{required} to specify
+either of these options when you run @command{tar}, but they can be very
+useful in making things more clear and helping you avoid errors.)
+
address@hidden
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
address@hidden menu
+
address@hidden file tutorial
address@hidden The @option{--file} Option
+
address@hidden @option
address@hidden address@hidden, tutorial}
address@hidden address@hidden
address@hidden -f @var{archive-name}
+Specify the name of an archive file.
address@hidden table
+
+You can specify an argument for the @address@hidden (@option{-f
@var{archive-name}}) option whenever you
+use @command{tar}; this option determines the name of the archive file
+that @command{tar} will work on.
+
address@hidden TAPE
+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
+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
+attached, or the default is not meaningful, then @command{tar} will
+print an error message. The error message might look roughly like one
+of the following:
+
address@hidden
+tar: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
address@hidden smallexample
+
address@hidden
+To avoid confusion, we recommend that you always specify an archive file
+name by using @address@hidden (@option{-f @var{archive-name}}) when writing
your @command{tar} commands.
+For more information on using the @address@hidden (@option{-f
@var{archive-name}}) option, see
address@hidden
+
address@hidden verbose tutorial
address@hidden The @option{--verbose} Option
+
address@hidden @option
address@hidden address@hidden, introduced}
address@hidden --verbose
address@hidden -v
+Show the files being worked on as @command{tar} is running.
address@hidden table
+
address@hidden (@option{-v}) shows details about the results of running
address@hidden This can be especially useful when the results might not be
+obvious. For example, if you want to see the progress of @command{tar} as
+it writes files into the archive, you can use the @option{--verbose}
+option. In the beginning, you may find it useful to use
address@hidden at all times; when you are more accustomed to
address@hidden, you will likely want to use it at certain times but not at
+others. We will use @option{--verbose} at times to help make something
+clear, and we will give many examples both using and not using
address@hidden to show the differences.
+
+Each instance of @option{--verbose} on the command line increases the
+verbosity level by one, so if you need more details on the output,
+specify it twice.
+
+When reading archives (@option{--list}, @option{--extract},
address@hidden), @command{tar} by default prints only the names of
+the members being extracted. Using @option{--verbose} will show a full,
address@hidden style member listing.
+
+In contrast, when writing archives (@option{--create}, @option{--append},
address@hidden), @command{tar} does not print file names by
+default. So, a single @option{--verbose} option shows the file names
+being added to the archive, while two @option{--verbose} options
+enable the full listing.
+
+For example, to create an archive in verbose mode:
+
address@hidden
+$ @kbd{tar -cvf afiles.tar apple angst aspic}
+apple
+angst
+aspic
address@hidden smallexample
+
address@hidden
+Creating the same archive with the verbosity level 2 could give:
+
address@hidden
+$ @kbd{tar -cvvf afiles.tar apple angst aspic}
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
+-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
address@hidden smallexample
+
address@hidden
+This works equally well using short or long forms of options. Using
+long forms, you would simply write out the mnemonic form of the option
+twice, like this:
+
address@hidden
+$ @kbd{tar --create --verbose --verbose @dots{}}
address@hidden smallexample
+
address@hidden
+Note that you must double the hyphens properly each time.
+
+Later in the tutorial, we will give examples using @address@hidden
+--verbose}}.
+
address@hidden member listing}
+The full output consists of six fields:
+
address@hidden @bullet
address@hidden File type and permissions in symbolic form.
+These are displayed in the same format as the first column of
address@hidden -l} output (@pxref{What information is listed,
+format=verbose, Verbose listing, fileutils, GNU file utilities}).
+
address@hidden Owner name and group separated by a slash character.
+If these data are not available (for example, when listing a @samp{v7} format
+archive), numeric ID values are printed instead.
+
address@hidden Size of the file, in bytes.
+
address@hidden File modification date in ISO 8601 format.
+
address@hidden File modification time.
+
address@hidden File name.
+If the name contains any special characters (white space, newlines,
+etc.) these are displayed in an unambiguous form using so called
address@hidden style}. For the detailed discussion of available styles
+and on how to use them, see @ref{quoting styles}.
+
+Depending on the file type, the name can be followed by some
+additional information, described in the following table:
+
address@hidden @samp
address@hidden -> @var{link-name}
+The file or archive member is a @dfn{symbolic link} and
address@hidden is the name of file it links to.
+
address@hidden link to @var{link-name}
+The file or archive member is a @dfn{hard link} and @var{link-name} is
+the name of file it links to.
+
address@hidden --Long Link--
+The archive member is an old GNU format long link. You will normally
+not encounter this.
+
address@hidden --Long Name--
+The archive member is an old GNU format long name. You will normally
+not encounter this.
+
address@hidden --Volume Header--
+The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}).
+
address@hidden --Continued at byte @var{n}--
+Encountered only at the beginning of a multy-volume archive
+(@pxref{Using Multiple Tapes}). This archive member is a continuation
+from the previous volume. The number @var{n} gives the offset where
+the original file was split.
+
address@hidden --Mangled file names--
+This archive member contains @dfn{mangled file names} declarations,
+a special member type that was used by early versions of @acronym{GNU}
@command{tar}.
+You probably will never encounter this, unless you are reading a very
+old archive.
+
address@hidden unknown file type @var{c}
+An archive member of unknown type. @var{c} is the type character from
+the archive header. If you encounter such a message, it means that
+either your archive contains proprietary member types @acronym{GNU}
@command{tar} is not
+able to handle, or the archive is corrupted.
address@hidden table
+
address@hidden itemize
+
+For example, here is an archive listing containing most of the special
+suffixes explained above:
+
address@hidden
address@hidden
+V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
+byte 32456--
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden smallexample
+
address@hidden help tutorial
address@hidden Getting Help: Using the @option{--help} Option
+
address@hidden @option
address@hidden help
address@hidden --help
+
+The @option{--help} option to @command{tar} prints out a very brief list of
+all operations and option available for the current version of
address@hidden available on your system.
address@hidden table
+
address@hidden create
address@hidden How to Create Archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Creation of the archive
address@hidden Archive, creation of
+One of the basic operations of @command{tar} is @option{--create}
(@option{-c}), which
+you use to create a @command{tar} archive. We will explain
address@hidden first because, in order to learn about the other
+operations, you will find it useful to have an archive available to
+practice on.
+
+To make this easier, in this section you will first create a directory
+containing three files. Then, we will show you how to create an
address@hidden (inside the new directory). Both the directory, and
+the archive are specifically for you to practice on. The rest of this
+chapter and the next chapter will show many examples using this
+directory and the files you will create: some of those files may be
+other directories and other archives.
+
+The three files you will archive in this example are called
address@hidden, @file{folk}, and @file{jazz}. The archive is called
address@hidden
+
+This section will proceed slowly, detailing how to use @option{--create}
+in @code{verbose} mode, and showing examples using both short and long
+forms. In the rest of the tutorial, and in the examples in the next
+chapter, we will proceed at a slightly quicker pace. This section
+moves more slowly to allow beginning users to understand how
address@hidden works.
+
address@hidden
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
address@hidden menu
+
address@hidden prepare for examples
address@hidden Preparing a Practice Directory for Examples
+
+To follow along with this and future examples, create a new directory
+called @file{practice} containing files called @file{blues}, @file{folk}
+and @file{jazz}. The files can contain any information you like:
+ideally, they should contain information which relates to their names,
+and be of different lengths. Our examples assume that @file{practice}
+is a subdirectory of your home directory.
+
+Now @command{cd} to the directory named @file{practice}; @file{practice}
+is now your @dfn{working directory}. (@emph{Please note}: Although
+the full path name of this directory is
address@hidden/@var{homedir}/practice}, in our examples we will refer to
+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}.
+Because you just created the directory and the files and have changed to
+that directory, you probably don't need to do that this time.
+
+It is very important to make sure there isn't already a file in the
+working directory with the archive name you intend to use (in this case,
address@hidden), or that you don't care about its contents.
+Whenever you use @samp{create}, @command{tar} will erase the current
+contents of the file named by @address@hidden (@option{-f @var{archive-name}})
if it exists. @command{tar}
+will not tell you if you are about to overwrite an archive unless you
+specify an option which does this (@pxref{backup}, for the
+information on how to do so). To add files to an existing archive,
+you need to use a different option, such as @option{--append} (@option{-r});
see
address@hidden for information on how to do this.
+
address@hidden Creating the archive
address@hidden Creating the Archive
+
address@hidden address@hidden, introduced}
+To place the files @file{blues}, @file{folk}, and @file{jazz} into an
+archive named @file{collection.tar}, use the following command:
+
address@hidden
+$ @kbd{tar --create --file=collection.tar blues folk jazz}
address@hidden smallexample
+
+The order of the arguments is not very important, @emph{when using long
+option forms}. You could also say:
+
address@hidden
+$ @kbd{tar blues --create folk --file=collection.tar jazz}
address@hidden smallexample
+
address@hidden
+However, you can see that this order is harder to understand; this is
+why we will list the arguments in the order that makes the commands
+easiest to understand (and we encourage you to do the same when you use
address@hidden, to avoid errors).
+
+Note that the sequence
address@hidden@-collection.tar} is considered to be @emph{one} argument.
+If you substituted any other string of characters for
address@hidden, then that string would become the name of the
+archive file you create.
+
+The order of the options becomes more important when you begin to use
+short forms. With short forms, if you type commands in the wrong order
+(even if you type them correctly in all other ways), you may end up with
+results you don't expect. For this reason, it is a good idea to get
+into the habit of typing options in the order that makes inherent sense.
address@hidden create}, for more information on this.
+
+In this example, you type the command as shown above: @option{--create}
+is the operation which creates the new archive
+(@file{collection.tar}), and @option{--file} is the option which lets
+you give it the name you chose. The files, @file{blues}, @file{folk},
+and @file{jazz}, are now members of the archive, @file{collection.tar}
+(they are @dfn{file name arguments} to the @option{--create} operation.
address@hidden, for the detailed discussion on these.) Now that they are
+in the archive, they are called @emph{archive members}, not files.
+(@pxref{Definitions,members}).
+
+When you create an archive, you @emph{must} specify which files you
+want placed in the archive. If you do not specify any archive
+members, @acronym{GNU} @command{tar} will complain.
+
+If you now list the contents of the working directory (@command{ls}), you will
+find the archive file listed as well as the files you saw previously:
+
address@hidden
+blues folk jazz collection.tar
address@hidden smallexample
+
address@hidden
+Creating the archive @samp{collection.tar} did not destroy the copies of
+the files in the directory.
+
+Keep in mind that if you don't indicate an operation, @command{tar} will not
+run and will prompt you for one. If you don't name any files, @command{tar}
+will complain. You must have write access to the working directory,
+or else you will not be able to create an archive in that directory.
+
address@hidden: Do not attempt to use @option{--create} (@option{-c}) to add
files to
+an existing archive; it will delete the archive and write a new one.
+Use @option{--append} (@option{-r}) instead. @xref{append}.
+
address@hidden create verbose
address@hidden Running @option{--create} with @option{--verbose}
+
address@hidden address@hidden, using with @option{--verbose}}
address@hidden address@hidden, using with @option{--create}}
+If you include the @option{--verbose} (@option{-v}) option on the command line,
address@hidden will list the files it is acting on as it is working. In
+verbose mode, the @code{create} example above would appear as:
+
address@hidden
+$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
+blues
+folk
+jazz
address@hidden smallexample
+
+This example is just like the example we showed which did not use
address@hidden, except that @command{tar} generated the remaining lines
+
+In the rest of the examples in this chapter, we will frequently use
address@hidden mode so we can show actions or @command{tar} responses that
+you would otherwise not see, and which are important for you to
+understand.
+
address@hidden short create
address@hidden Short Forms with @samp{create}
+
+As we said before, the @option{--create} (@option{-c}) operation is one of the
most
+basic uses of @command{tar}, and you will use it countless times.
+Eventually, you will probably want to use abbreviated (or ``short'')
+forms of options. A full discussion of the three different forms that
+options can take appears in @ref{Styles}; for now, here is what the
+previous example (including the @option{--verbose} (@option{-v}) option) looks
like
+using short option forms:
+
address@hidden
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+blues
+folk
+jazz
address@hidden smallexample
+
address@hidden
+As you can see, the system responds the same no matter whether you use
+long or short option forms.
+
address@hidden
address@hidden
+ One difference between using
+short and long option forms is that, although the exact placement of
+arguments following options is no more specific when using short forms,
+it is easier to become confused and make a mistake when using short
+forms. For example, suppose you attempted the above example in the
+following way:
+
address@hidden
+$ @kbd{tar -cfv collection.tar blues folk jazz}
address@hidden smallexample
+
address@hidden
+In this case, @command{tar} will make an archive file called @file{v},
+containing the files @file{blues}, @file{folk}, and @file{jazz}, because
+the @samp{v} is the closest ``file name'' to the @option{-f} option, and
+is thus taken to be the chosen archive file name. @command{tar} will try
+to add a file called @file{collection.tar} to the @file{v} archive file;
+if the file @file{collection.tar} did not already exist, @command{tar} will
+report an error indicating that this file does not exist. If the file
address@hidden does already exist (e.g., from a previous command
+you may have run), then @command{tar} will add this file to the archive.
+Because the @option{-v} option did not get registered, @command{tar} will not
+run under @samp{verbose} mode, and will not report its progress.
+
+The end result is that you may be quite confused about what happened,
+and possibly overwrite a file. To illustrate this further, we will show
+you how an example we showed previously would look using short forms.
+
+This example,
+
address@hidden
+$ @kbd{tar blues --create folk --file=collection.tar jazz}
address@hidden smallexample
+
address@hidden
+is confusing as it is. When shown using short forms, however, it
+becomes much more so:
+
address@hidden
+$ @kbd{tar blues -c folk -f collection.tar jazz}
address@hidden smallexample
+
address@hidden
+It would be very easy to put the wrong string of characters
+immediately following the @option{-f}, but doing that could sacrifice
+valuable data.
+
+For this reason, we recommend that you pay very careful attention to
+the order of options and placement of file and archive names,
+especially when using short option forms. Not having the option name
+written out mnemonically can affect how well you remember which option
+does what, and therefore where different names have to be placed.
+
address@hidden create dir
address@hidden Archiving Directories
+
address@hidden Archiving Directories
address@hidden Directories, Archiving
+You can archive a directory by specifying its directory name as a
+file name argument to @command{tar}. The files in the directory will be
+archived relative to the working directory, and the directory will be
+re-created along with its contents when the archive is extracted.
+
+To archive a directory, first move to its superior directory. If you
+have followed the previous instructions in this tutorial, you should
+type:
+
address@hidden
+$ @kbd{cd ..}
+$
address@hidden smallexample
+
address@hidden
+This will put you into the directory which contains @file{practice},
+i.e., your home directory. Once in the superior directory, you can
+specify the subdirectory, @file{practice}, as a file name argument. To
+store @file{practice} in the new archive file @file{music.tar}, type:
+
address@hidden
+$ @kbd{tar --create --verbose --file=music.tar practice}
address@hidden smallexample
+
address@hidden
address@hidden should output:
+
address@hidden
+practice/
+practice/blues
+practice/folk
+practice/jazz
+practice/collection.tar
address@hidden smallexample
+
+Note that the archive thus created is not in the subdirectory
address@hidden, but rather in the current working directory---the
+directory from which @command{tar} was invoked. Before trying to archive a
+directory from its superior directory, you should make sure you have
+write access to the superior directory itself, not only the directory
+you are trying archive with @command{tar}. For example, you will probably
+not be able to store your home directory in an archive by invoking
address@hidden from the root directory; @xref{absolute}. (Note
+also that @file{collection.tar}, the original archive file, has itself
+been archived. @command{tar} will accept any file as a file to be
+archived, regardless of its content. When @file{music.tar} is
+extracted, the archive file @file{collection.tar} will be re-written
+into the file system).
+
+If you give @command{tar} a command such as
+
address@hidden
+$ @kbd{tar --create --file=foo.tar .}
address@hidden smallexample
+
address@hidden
address@hidden will report @samp{tar: ./foo.tar is the archive; not
+dumped}. This happens because @command{tar} creates the archive
address@hidden in the current directory before putting any files into
+it. Then, when @command{tar} attempts to add all the files in the
+directory @file{.} to the archive, it notices that the file
address@hidden/foo.tar} is the same as the archive @file{foo.tar}, and skips
+it. (It makes no sense to put an archive into itself.) @acronym{GNU}
@command{tar}
+will continue in this case, and create the archive
+normally, except for the exclusion of that one file. (@emph{Please
+note:} Other implementations of @command{tar} may not be so clever;
+they will enter an infinite loop when this happens, so you should not
+depend on this behavior unless you are certain you are running
address@hidden @command{tar}. In general, it is wise to always place the
archive outside
+of the directory being dumped.
+
address@hidden list
address@hidden How to List Archives
+
address@hidden list
+Frequently, you will find yourself wanting to determine exactly what a
+particular archive contains. You can use the @option{--list}
+(@option{-t}) operation to get the member names as they currently
+appear in the archive, as well as various attributes of the files at
+the time they were archived. For example, you can examine the archive
address@hidden that you created in the last section with the
+command,
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
address@hidden smallexample
+
address@hidden
+The output of @command{tar} would then be:
+
address@hidden
+blues
+folk
+jazz
address@hidden smallexample
+
address@hidden
+The archive @file{bfiles.tar} would list as follows:
+
address@hidden
+./birds
+baboon
+./box
address@hidden smallexample
+
address@hidden
+Be sure to use a @address@hidden (@option{-f
address@hidden) option just as with @option{--create}
+(@option{-c}) to specify the name of the archive.
+
address@hidden address@hidden, using with @option{--verbose}}
address@hidden address@hidden, using with @option{--list}}
+If you use the @option{--verbose} (@option{-v}) option with
address@hidden, then @command{tar} will print out a listing
+reminiscent of @address@hidden -l}}, showing owner, file size, and so
+forth. This output is described in detail in @ref{verbose member listing}.
+
+If you had used @option{--verbose} (@option{-v}) mode, the example
+above would look like:
+
address@hidden
+$ @kbd{tar --list --verbose --file=collection.tar folk}
+-rw-r--r-- myself user 62 1990-05-23 10:55 folk
address@hidden smallexample
+
address@hidden listing member and file names
address@hidden member and file names}
+It is important to notice that the output of @kbd{tar --list
+--verbose} does not necessarily match that produced by @kbd{tar
+--create --verbose} while creating the archive. It is because
address@hidden @command{tar}, unless told explicitly not to do so, removes some
directory
+prefixes from file names before storing them in the archive
+(@xref{absolute}, for more information). In other
+words, in verbose mode @acronym{GNU} @command{tar} shows @dfn{file names} when
creating
+an archive and @dfn{member names} when listing it. Consider this
+example:
+
address@hidden
address@hidden
+$ @kbd{tar cfv archive /etc/mail}
+tar: Removing leading `/' from member names
+/etc/mail/
+/etc/mail/sendmail.cf
+/etc/mail/aliases
+$ @kbd{tar tf archive}
+etc/mail/
+etc/mail/sendmail.cf
+etc/mail/aliases
address@hidden group
address@hidden smallexample
+
address@hidden show-stored-names
+ This default behavior can sometimes be inconvenient. You can force
address@hidden @command{tar} show member names when creating archive by
supplying
address@hidden option.
+
address@hidden @option
address@hidden --show-stored-names
+Print member (as opposed to @emph{file}) names when creating the archive.
address@hidden table
+
address@hidden File name arguments, using @option{--list} with
address@hidden address@hidden, using with file name arguments}
+You can specify one or more individual member names as arguments when
+using @samp{list}. In this case, @command{tar} will only list the
+names of members you identify. For example, @address@hidden --list
+--file=afiles.tar apple}} would only print @file{apple}.
+
+Because @command{tar} preserves paths, file names must be specified as
+they appear in the archive (i.e., relative to the directory from which
+the archive was created). Therefore, it is essential when specifying
+member names to @command{tar} that you give the exact member names.
+For example, @address@hidden --list --file=bfiles.tar birds}} would produce an
+error message something like @samp{tar: birds: Not found in archive},
+because there is no member named @file{birds}, only one named
address@hidden/birds}. While the names @file{birds} and @file{./birds} name
+the same file, @emph{member} names by default are compared verbatim.
+
+However, @address@hidden --list --file=bfiles.tar baboon}} would respond
+with @file{baboon}, because this exact member name is in the archive file
address@hidden If you are not sure of the exact file name,
+use @dfn{globbing patterns}, for example:
+
address@hidden
+$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'}
address@hidden smallexample
+
address@hidden
+will list all members whose name contains @samp{b}. @xref{wildcards},
+for a detailed discussion of globbing patterns and related
address@hidden command line options.
+
address@hidden
+* list dir::
address@hidden menu
+
address@hidden list dir
address@hidden Listing the Contents of a Stored Directory
+
+To get information about the contents of an archived directory,
+use the directory name as a file name argument in conjunction with
address@hidden (@option{-t}). To find out file attributes, include the
address@hidden (@option{-v}) option.
+
+For example, to find out about files in the directory @file{practice}, in
+the archive file @file{music.tar}, type:
+
address@hidden
+$ @kbd{tar --list --verbose --file=music.tar practice}
address@hidden smallexample
+
address@hidden responds:
+
address@hidden
+drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
+-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
address@hidden smallexample
+
+When you use a directory name as a file name argument, @command{tar} acts on
+all the files (including sub-directories) in that directory.
+
address@hidden extract
address@hidden How to Extract Members from an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Extraction
address@hidden Retrieving files from an archive
address@hidden Resurrecting files from an archive
+
address@hidden extract
+Creating an archive is only half the job---there is no point in storing
+files in an archive if you can't retrieve them. The act of retrieving
+members from an archive so they can be used and manipulated as
+unarchived files again is called @dfn{extraction}. To extract files
+from an archive, use the @option{--extract} (@option{--get} or
address@hidden) operation. As with @option{--create}, specify the name
+of the archive with @option{--file} (@option{-f}) option. Extracting
+an archive does not modify the archive in any way; you can extract it
+multiple times if you want or need to.
+
+Using @option{--extract}, you can extract an entire archive, or specific
+files. The files can be directories containing other files, or not. As
+with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you
may use the short or the
+long form of the operation without affecting the performance.
+
address@hidden
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
address@hidden menu
+
address@hidden extracting archives
address@hidden Extracting an Entire Archive
+
+To extract an entire archive, specify the archive file name only, with
+no individual file names as arguments. For example,
+
address@hidden
+$ @kbd{tar -xvf collection.tar}
address@hidden smallexample
+
address@hidden
+produces this:
+
address@hidden
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
address@hidden smallexample
+
address@hidden extracting files
address@hidden Extracting Specific Files
+
+To extract specific archive members, give their exact member names as
+arguments, as printed by @option{--list} (@option{-t}). If you had
+mistakenly deleted one of the files you had placed in the archive
address@hidden earlier (say, @file{blues}), you can extract it
+from the archive without changing the archive's structure. Its
+contents will be identical to the original file @file{blues} that you
+deleted.
+
+First, make sure you are in the @file{practice} directory, and list the
+files in the directory. Now, delete the file, @samp{blues}, and list
+the files in the directory again.
+
+You can now extract the member @file{blues} from the archive file
address@hidden like this:
+
address@hidden
+$ @kbd{tar --extract --file=collection.tar blues}
address@hidden smallexample
+
address@hidden
+If you list the files in the directory again, you will see that the file
address@hidden has been restored, with its original permissions, data
+modification times, and address@hidden is only accidentally
+true, but not in general. Whereas modification times are always
+restored, in most cases, one has to be root for restoring the owner,
+and use a special option for restoring permissions. Here, it just
+happens that the restoring user is also the owner of the archived
+members, and that the current @code{umask} is compatible with original
+permissions.} (These parameters will be identical to those which
+the file had when you originally placed it in the archive; any changes
+you may have made before deleting the file from the file system,
+however, will @emph{not} have been made to the archive member.) The
+archive file, @samp{collection.tar}, is the same as it was before you
+extracted @samp{blues}. You can confirm this by running @command{tar} with
address@hidden (@option{-t}).
+
+Remember that as with other operations, specifying the exact member
+name is important. @address@hidden --extract --file=bfiles.tar birds}}
+will fail, because there is no member named @file{birds}. To extract
+the member named @file{./birds}, you must specify @address@hidden
+--extract --file=bfiles.tar ./birds}}. If you don't remember the
+exact member names, use @option{--list} (@option{-t}) option
+(@pxref{list}). You can also extract those members that match a
+specific @dfn{globbing pattern}. For example, to extract from
address@hidden all files that begin with @samp{b}, no matter their
+directory prefix, you could type:
+
address@hidden
+$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'}
address@hidden smallexample
+
address@hidden
+Here, @option{--wildcards} instructs @command{tar} to treat
+command line arguments as globbing patterns and @option{--no-anchored}
+informs it that the patterns apply to member names after any @samp{/}
+delimiter. The use of globbing patterns is discussed in detail in
address@hidden
+
+You can extract a file to standard output by combining the above options
+with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard
+Output}).
+
+If you give the @option{--verbose} option, then @option{--extract}
+will print the names of the archive members as it extracts them.
+
address@hidden extract dir
address@hidden Extracting Files that are Directories
+
+Extracting directories which are members of an archive is similar to
+extracting other files. The main difference to be aware of is that if
+the extracted directory has the same name as any directory already in
+the working directory, then files in the extracted directory will be
+placed into the directory of the same name. Likewise, if there are
+files in the pre-existing directory with the same names as the members
+which you extract, the files from the extracted archive will replace
+the files already in the working directory (and possible
+subdirectories). This will happen regardless of whether or not the
+files in the working directory were more recent than those extracted
+(there exist, however, special options that alter this behavior
address@hidden).
+
+However, if a file was stored with a directory name as part of its file
+name, and that directory does not exist under the working directory when
+the file is extracted, @command{tar} will create the directory.
+
+We can demonstrate how to use @option{--extract} to extract a directory
+file with an example. Change to the @file{practice} directory if you
+weren't there, and remove the files @file{folk} and @file{jazz}. Then,
+go back to the parent directory and extract the archive
address@hidden You may either extract the entire archive, or you may
+extract only the files you just deleted. To extract the entire archive,
+don't give any file names as arguments after the archive name
address@hidden To extract only the files you deleted, use the
+following command:
+
address@hidden
+$ @kbd{tar -xvf music.tar practice/folk practice/jazz}
+practice/folk
+practice/jazz
address@hidden smallexample
+
address@hidden
+If you were to specify two @option{--verbose} (@option{-v}) options,
@command{tar}
+would have displayed more detail about the extracted files, as shown
+in the example below:
+
address@hidden
+$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
+-rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
+-rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
address@hidden smallexample
+
address@hidden
+Because you created the directory with @file{practice} as part of the
+file names of each of the files by archiving the @file{practice}
+directory as @file{practice}, you must give @file{practice} as part
+of the file names when you extract those files from the archive.
+
address@hidden extracting untrusted archives
address@hidden Extracting Archives from Untrusted Sources
+
+Extracting files from archives can overwrite files that already exist.
+If you receive an archive from an untrusted source, you should make a
+new directory and extract into that directory, so that you don't have
+to worry about the extraction overwriting one of your existing files.
+For example, if @file{untrusted.tar} came from somewhere else on the
+Internet, and you don't necessarily trust its contents, you can
+extract it as follows:
+
address@hidden
+$ @kbd{mkdir newdir}
+$ @kbd{cd newdir}
+$ @kbd{tar -xvf ../untrusted.tar}
address@hidden smallexample
+
+It is also a good practice to examine contents of the archive
+before extracting it, using @option{--list} (@option{-t}) option, possibly
combined
+with @option{--verbose} (@option{-v}).
+
address@hidden failing commands
address@hidden Commands That Will Fail
+
+Here are some sample commands you might try which will not work, and why
+they won't work.
+
+If you try to use this command,
+
address@hidden
+$ @kbd{tar -xvf music.tar folk jazz}
address@hidden smallexample
+
address@hidden
+you will get the following response:
+
address@hidden
+tar: folk: Not found in archive
+tar: jazz: Not found in archive
+$
address@hidden smallexample
+
address@hidden
+This is because these files were not originally @emph{in} the parent
+directory @file{..}, where the archive is located; they were in the
address@hidden directory, and their file names reflect this:
+
address@hidden
+$ @kbd{tar -tvf music.tar}
+practice/folk
+practice/jazz
+practice/rock
address@hidden smallexample
+
address@hidden
address@hidden
+
+
address@hidden
+Likewise, if you try to use this command,
+
address@hidden
+$ @kbd{tar -tvf music.tar folk jazz}
address@hidden smallexample
+
address@hidden
+you would get a similar response. Members with those names are not in the
+archive. You must use the correct member names, or wildcards, in order
+to extract the files from the archive.
+
+If you have forgotten the correct names of the files in the archive,
+use @address@hidden --list --verbose}} to list them correctly.
+
address@hidden
address@hidden
+
+
address@hidden going further
address@hidden Going Further Ahead in this Manual
+
address@hidden
address@hidden
+
+
address@hidden tar invocation
address@hidden Invoking @acronym{GNU} @command{tar}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+This chapter is about how one invokes the @acronym{GNU} @command{tar}
+command, from the command synopsis (@pxref{Synopsis}). There are
+numerous options, and many styles for writing them. One mandatory
+option specifies the operation @command{tar} should perform
+(@pxref{Operation Summary}), other options are meant to detail how
+this operation should be performed (@pxref{Option Summary}).
+Non-option arguments are not always interpreted the same way,
+depending on what the operation is.
+
+You will find in this chapter everything about option styles and rules for
+writing them (@pxref{Styles}). On the other hand, operations and options
+are fully described elsewhere, in other chapters. Here, you will find
+only synthetic descriptions for operations and options, together with
+pointers to other parts of the @command{tar} manual.
+
+Some options are so special they are fully described right in this
+chapter. They have the effect of inhibiting the normal operation of
address@hidden or else, they globally alter the amount of feedback the user
+receives about what is going on. These are the @option{--help} and
address@hidden (@pxref{help}), @option{--verbose} (@pxref{verbose})
+and @option{--interactive} options (@pxref{interactive}).
+
address@hidden
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
address@hidden menu
+
address@hidden Synopsis
address@hidden General Synopsis of @command{tar}
+
+The @acronym{GNU} @command{tar} program is invoked as either one of:
+
address@hidden
address@hidden @address@hidden address@hidden@dots{}}
address@hidden @address@hidden address@hidden@dots{} address@hidden@dots{}
address@hidden@dots{}}
address@hidden smallexample
+
+The second form is for when old options are being used.
+
+You can use @command{tar} to store files in an archive, to extract them from
+an archive, and to do other types of archive manipulation. The primary
+argument to @command{tar}, which is called the @dfn{operation}, specifies
+which action to take. The other arguments to @command{tar} are either
address@hidden, which change the way @command{tar} performs an operation,
+or file names or archive members, which specify the files or members
address@hidden is to act on.
+
+You can actually type in arguments in any order, even if in this manual
+the options always precede the other arguments, to make examples easier
+to understand. Further, the option stating the main operation mode
+(the @command{tar} main command) is usually given first.
+
+Each @var{name} in the synopsis above is interpreted as an archive member
+name when the main command is one of @option{--compare}
+(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract}
+(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or
address@hidden (@option{-u}). When naming archive members, you
+must give the exact name of the member in the archive, as it is
+printed by @option{--list}. For @option{--append} (@option{-r}) and
address@hidden (@option{-c}), these @var{name} arguments specify
+the names of either files or directory hierarchies to place in the archive.
+These files or hierarchies should already exist in the file system,
+prior to the execution of the @command{tar} command.
+
address@hidden interprets relative file names as being relative to the
+working directory. @command{tar} will make all file names relative
+(by removing leading slashes when archiving or restoring files),
+unless you specify otherwise (using the @option{--absolute-names}
+option). @xref{absolute}, for more information about
address@hidden
+
+If you give the name of a directory as either a file name or a member
+name, then @command{tar} acts recursively on all the files and directories
+beneath that directory. For example, the name @file{/} identifies all
+the files in the file system to @command{tar}.
+
+The distinction between file names and archive member names is especially
+important when shell globbing is used, and sometimes a source of confusion
+for newcomers. @xref{wildcards}, for more information about globbing.
+The problem is that shells may only glob using existing files in the
+file system. Only @command{tar} itself may glob on archive members, so when
+needed, you must ensure that wildcard characters reach @command{tar} without
+being interpreted by the shell first. Using a backslash before @samp{*}
+or @samp{?}, or putting the whole argument between quotes, is usually
+sufficient for this.
+
+Even if @var{name}s are often specified on the command line, they
+can also be read from a text file in the file system, using the
address@hidden@var{file-of-names}} (@option{-T @var{file-of-names}}) option.
+
+If you don't use any file name arguments, @option{--append} (@option{-r}),
address@hidden and @option{--concatenate} (@option{--catenate},
address@hidden) will do nothing, while @option{--create} (@option{-c})
+will usually yield a diagnostic and inhibit @command{tar} execution.
+The other operations of @command{tar} (@option{--list},
address@hidden, @option{--compare}, and @option{--update})
+will act on the entire contents of the archive.
+
address@hidden exit status
address@hidden return status
+Besides successful exits, @acronym{GNU} @command{tar} may fail for
+many reasons. Some reasons correspond to bad usage, that is, when the
address@hidden command is improperly written. Errors may be
+encountered later, while encountering an error processing the archive
+or the files. Some errors are recoverable, in which case the failure
+is delayed until @command{tar} has completed all its work. Some
+errors are such that it would not meaningful, or at least risky, to
+continue processing: @command{tar} then aborts processing immediately.
+All abnormal exits, whether immediate or delayed, should always be
+clearly diagnosed on @code{stderr}, after a line stating the nature of
+the error.
+
address@hidden @command{tar} returns only a few exit statuses. I'm really
+aiming simplicity in that area, for now. If you are not using the
address@hidden @option{--diff}, @option{-d}) option, zero means
+that everything went well, besides maybe innocuous warnings. Nonzero
+means that something went wrong. Right now, as of today, ``nonzero''
+is almost always 2, except for remote operations, where it may be
+128.
+
address@hidden using tar options
address@hidden Using @command{tar} Options
+
address@hidden @command{tar} has a total of eight operating modes which
+allow you to perform a variety of tasks. You are required to choose
+one operating mode each time you employ the @command{tar} program by
+specifying one, and only one operation as an argument to the
address@hidden command (two lists of four operations each may be found
+at @ref{frequent operations} and @ref{Operations}). Depending on
+circumstances, you may also wish to customize how the chosen operating
+mode behaves. For example, you may wish to change the way the output
+looks, or the format of the files that you wish to archive may require
+you to do something special in order to make the archive look right.
+
+You can customize and control @command{tar}'s performance by running
address@hidden with one or more options (such as @option{--verbose}
+(@option{-v}), which we used in the tutorial). As we said in the
+tutorial, @dfn{options} are arguments to @command{tar} which are (as
+their name suggests) optional. Depending on the operating mode, you
+may specify one or more options. Different options will have different
+effects, but in general they all change details of the operation, such
+as archive format, archive name, or level of user interaction. Some
+options make sense with all operating modes, while others are
+meaningful only with particular modes. You will likely use some
+options frequently, while you will only use others infrequently, or
+not at all. (A full list of options is available in @pxref{All Options}.)
+
address@hidden TAR_OPTIONS, environment variable
address@hidden
+The @env{TAR_OPTIONS} environment variable specifies default options to
+be placed in front of any explicit options. For example, if
address@hidden is @samp{-v --unlink-first}, @command{tar} behaves as
+if the two options @option{-v} and @option{--unlink-first} had been
+specified before any explicit options. Option specifications are
+separated by whitespace. A backslash escapes the next character, so it
+can be used to specify an option containing whitespace or a backslash.
+
+Note that @command{tar} options are case sensitive. For example, the
+options @option{-T} and @option{-t} are different; the first requires an
+argument for stating the name of a file providing a list of @var{name}s,
+while the second does not require an argument and is another way to
+write @option{--list} (@option{-t}).
+
+In addition to the eight operations, there are many options to
address@hidden, and three different styles for writing both: long (mnemonic)
+form, short form, and old style. These styles are discussed below.
+Both the options and the operations can be written in any of these three
+styles.
+
address@hidden
address@hidden
+
+
address@hidden Styles
address@hidden The Three Option Styles
+
+There are three styles for writing operations and options to the command
+line invoking @command{tar}. The different styles were developed at
+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
+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
+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
+subtle, yet can often be very important; incorrect option placement
+can cause you to overwrite a number of important files. We urge you
+to note these differences, and only use the option style(s) which
+makes the most sense to you until you feel comfortable with the others.
+
+Some options @emph{may} take an argument. Such options may have at
+most long and short forms, they do not have old style equivalent. The
+rules for specifying an argument for such options are stricter than
+those for specifying mandatory arguments. Please, pay special
+attention to them.
+
address@hidden
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
address@hidden menu
+
address@hidden Long Options
address@hidden Long Option Style
+
+Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with
two
+dashes in a row, e.g., @option{--list}. The long names are more clear than
+their corresponding short or old names. It sometimes happens that a
+single long option has many different different names which are
+synonymous, such as @option{--compare} and @option{--diff}. In addition,
+long option names can be given unique abbreviations. For example,
address@hidden can be used in place of @option{--create} because there is no
+other long option which begins with @samp{cre}. (One way to find
+this out is by trying it and seeing what happens; if a particular
+abbreviation could represent more than one option, @command{tar} will tell
+you that that abbreviation is ambiguous and you'll know that that
+abbreviation won't work. You may also choose to run @samp{tar --help}
+to see a list of options. Be aware that if you run @command{tar} with a
+unique abbreviation for the long name of an option you didn't want to
+use, you are stuck; @command{tar} will perform the command as ordered.)
+
+Long options are meant to be obvious and easy to remember, and their
+meanings are generally easier to discern than those of their
+corresponding short options (see below). For example:
+
address@hidden
+$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
address@hidden smallexample
+
address@hidden
+gives a fairly good set of hints about what the command does, even
+for those not fully acquainted with @command{tar}.
+
+Long options which require arguments take those arguments
+immediately following the option name. There are two ways of
+specifying a mandatory argument. It can be separated from the
+option name either by an equal sign, or by any amount of
+white space characters. For example, the @option{--file} option (which
+tells the name of the @command{tar} archive) is given a file such as
address@hidden as argument by using any of the following notations:
address@hidden or @option{--file archive.tar}.
+
+In contrast, optional arguments must always be introduced using
+an equal sign. For example, the @option{--backup} option takes
+an optional argument specifying backup type. It must be used
+as @address@hidden
+
address@hidden Short Options
address@hidden Short Option Style
+
+Most options also have a @dfn{short option} name. Short options start with
+a single dash, and are followed by a single character, e.g., @option{-t}
+(which is equivalent to @option{--list}). The forms are absolutely
+identical in function; they are interchangeable.
+
+The short option names are faster to type than long option names.
+
+Short options which require arguments take their arguments immediately
+following the option, usually separated by white space. It is also
+possible to stick the argument right after the short option name, using
+no intervening space. For example, you might write @address@hidden
+archive.tar}} or @option{-farchive.tar} instead of using
address@hidden Both @address@hidden and
address@hidden@option{-f @var{archive-name}}} denote the option which indicates
a
+specific archive, here named @file{archive.tar}.
+
+Short options which take optional arguments take their arguments
+immediately following the option letter, @emph{without any intervening
+white space characters}.
+
+Short options' letters may be clumped together, but you are not
+required to do this (as compared to old options; see below). When
+short options are clumped as a set, use one (single) dash for them
+all, e.g., @address@hidden@command{tar} -cvf}}. Only the last option in
+such a set is allowed to have an address@hidden many
+options, the last of which has an argument, is a rather opaque way to
+write options. Some wonder if @acronym{GNU} @code{getopt} should not
+even be made helpful enough for considering such usages as invalid.}.
+
+When the options are separated, the argument for each option which requires
+an argument directly follows that option, as is usual for Unix programs.
+For example:
+
address@hidden
+$ @kbd{tar -c -v -b 20 -f /dev/rmt0}
address@hidden smallexample
+
+If you reorder short options' locations, be sure to move any arguments
+that belong to them. If you do not move the arguments properly, you may
+end up overwriting files.
+
address@hidden Old Options
address@hidden Old Option Style
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Like short options, @dfn{old options} are single letters. However, old options
+must be written together as a single clumped set, without spaces separating
+them or dashes preceding address@hidden that if you precede options
+with a dash, you are announcing the short option style instead of the
+old option style; short options are decoded differently.}. This set
+of letters must be the first to appear on the command line, after the
address@hidden program name and some white space; old options cannot appear
+anywhere else. The letter of an old option is exactly the same letter as
+the corresponding short option. For example, the old option @samp{t} is
+the same as the short option @option{-t}, and consequently, the same as the
+long option @option{--list}. So for example, the command @address@hidden
+cv}} specifies the option @option{-v} in addition to the operation @option{-c}.
+
+When options that need arguments are given together with the command,
+all the associated arguments follow, in the same order as the options.
+Thus, the example given previously could also be written in the old
+style as follows:
+
address@hidden
+$ @kbd{tar cvbf 20 /dev/rmt0}
address@hidden smallexample
+
address@hidden
+Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
+the argument of @option{-f}.
+
+On the other hand, this old style syntax makes it difficult to match
+option letters with their corresponding arguments, and is often
+confusing. In the command @address@hidden cvbf 20 /dev/rmt0}}, for example,
address@hidden is the argument for @option{-b}, @samp{/dev/rmt0} is the
+argument for @option{-f}, and @option{-v} does not have a corresponding
+argument. Even using short options like in @address@hidden -c -v -b 20 -f
+/dev/rmt0}} is clearer, putting all arguments next to the option they
+pertain to.
+
+If you want to reorder the letters in the old option argument, be
+sure to reorder any corresponding argument appropriately.
+
+This old way of writing @command{tar} options can surprise even experienced
+users. For example, the two commands:
+
address@hidden
address@hidden cfz archive.tar.gz file}
address@hidden -cfz archive.tar.gz file}
address@hidden smallexample
+
address@hidden
+are quite different. The first example uses @file{archive.tar.gz} as
+the value for option @samp{f} and recognizes the option @samp{z}. The
+second example, however, uses @file{z} as the value for option
address@hidden --- probably not what was intended.
+
+Old options are kept for compatibility with old versions of @command{tar}.
+
+This second example could be corrected in many ways, among which the
+following are equivalent:
+
address@hidden
address@hidden -czf archive.tar.gz file}
address@hidden -cf archive.tar.gz -z file}
address@hidden cf archive.tar.gz -z file}
address@hidden smallexample
+
address@hidden option syntax, traditional
+As far as we know, all @command{tar} programs, @acronym{GNU} and
address@hidden, support old options. @acronym{GNU} @command{tar}
+supports them not only for historical reasons, but also because many
+people are used to them. For compatibility with Unix @command{tar},
+the first argument is always treated as containing command and option
+letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
+equivalent to @address@hidden -c}:} both of them specify the
address@hidden (@option{-c}) command to create an archive.
+
address@hidden Mixing
address@hidden Mixing Option Styles
+
+All three styles may be intermixed in a single @command{tar} command,
+so long as the rules for each style are fully
address@hidden @acronym{GNU} @command{tar} version 1.11.6,
+a bug prevented intermixing old style options with long options in
+some cases.}. Old style options and either of the modern styles of
+options may be mixed within a single @command{tar} command. However,
+old style options must be introduced as the first arguments only,
+following the rule for old options (old options must appear directly
+after the @command{tar} command and some white space). Modern options
+may be given only after all arguments to the old options have been
+collected. If this rule is not respected, a modern option might be
+falsely interpreted as the value of the argument to one of the old
+style options.
+
+For example, all the following commands are wholly equivalent, and
+illustrate the many combinations and orderings of option styles.
+
address@hidden
address@hidden --create --file=archive.tar}
address@hidden --create -f archive.tar}
address@hidden --create -farchive.tar}
address@hidden --file=archive.tar --create}
address@hidden --file=archive.tar -c}
address@hidden -c --file=archive.tar}
address@hidden -c -f archive.tar}
address@hidden -c -farchive.tar}
address@hidden -cf archive.tar}
address@hidden -cfarchive.tar}
address@hidden -f archive.tar --create}
address@hidden -f archive.tar -c}
address@hidden -farchive.tar --create}
address@hidden -farchive.tar -c}
address@hidden c --file=archive.tar}
address@hidden c -f archive.tar}
address@hidden c -farchive.tar}
address@hidden cf archive.tar}
address@hidden f archive.tar --create}
address@hidden f archive.tar -c}
address@hidden fc archive.tar}
address@hidden smallexample
+
+On the other hand, the following commands are @emph{not} equivalent to
+the previous set:
+
address@hidden
address@hidden -f -c archive.tar}
address@hidden -fc archive.tar}
address@hidden -fcarchive.tar}
address@hidden -farchive.tarc}
address@hidden cfarchive.tar}
address@hidden smallexample
+
address@hidden
+These last examples mean something completely different from what the
+user intended (judging based on the example in the previous set which
+uses long options, whose intent is therefore very clear). The first
+four specify that the @command{tar} archive would be a file named
address@hidden, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc},
+respectively. The first two examples also specify a single non-option,
address@hidden argument having the value @samp{archive.tar}. The last
+example contains only old style option letters (repeating option
address@hidden twice), not all of which are meaningful (eg., @samp{.},
address@hidden, or @samp{i}), with no argument value. @allow-recursion
address@hidden
+
+
address@hidden All Options
address@hidden All @command{tar} Options
+
+The coming manual sections contain an alphabetical listing of all
address@hidden 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.
+
address@hidden
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
address@hidden menu
+
address@hidden Operation Summary
address@hidden Operations
+
address@hidden @option
+
address@hidden ANCHOR--append 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --append
address@hidden -r
+
+Appends files to the end of the archive. @xref{append}.
+
address@hidden ANCHOR--catenate 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --catenate
address@hidden -A
+
+Same as @option{--concatenate}. @xref{concatenate}.
+
address@hidden ANCHOR--compare 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --compare
address@hidden -d
+
+Compares archive members with their counterparts in the file
+system, and reports differences in file size, mode, owner,
+modification date and contents. @xref{compare}.
+
address@hidden ANCHOR--concatenate 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --concatenate
address@hidden -A
+
+Appends other @command{tar} archives to the end of the archive.
address@hidden
+
address@hidden ANCHOR--create 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --create
address@hidden -c
+
+Creates a new @command{tar} archive. @xref{create}.
+
address@hidden ANCHOR--delete 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --delete
+
+Deletes members from the archive. Don't try this on a archive on a
+tape! @xref{delete}.
+
address@hidden ANCHOR--diff 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --diff
address@hidden -d
+
+Same @option{--compare}. @xref{compare}.
+
address@hidden ANCHOR--extract 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --extract
address@hidden -x
+
+Extracts members from the archive into the file system. @xref{extract}.
+
address@hidden ANCHOR--get 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --get
address@hidden -x
+
+Same as @option{--extract}. @xref{extract}.
+
address@hidden ANCHOR--list 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --list
address@hidden -t
+
+Lists the members in an archive. @xref{list}.
+
address@hidden ANCHOR--update 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --update
address@hidden -u
+
+Adds files to the end of the archive, but only if they are newer than
+their counterparts already in the archive, or if they do not already
+exist in the archive. @xref{update}.
+
address@hidden table
+
address@hidden Option Summary
address@hidden @command{tar} Options
+
address@hidden @option
+
address@hidden ANCHOR--absolute-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --absolute-names
address@hidden -P
+
+Normally when creating an archive, @command{tar} strips an initial
address@hidden/} from member names. This option disables that behavior.
address@hidden
+
address@hidden ANCHOR--after-date 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --after-date
+
+(See @option{--newer}, @pxref{after})
+
address@hidden ANCHOR--anchored 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --anchored
+A pattern must match an initial subsequence of the name's components.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--atime-preserve 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --atime-preserve
address@hidden --atime-preserve=replace
address@hidden --atime-preserve=system
+
+Attempt to preserve the access time of files when reading them. This
+option currently is effective only on files that you own, unless you
+have superuser privileges.
+
address@hidden remembers the access time of a file
+before reading it, and then restores the access time afterwards. This
+may cause problems if other programs are reading the file at the same
+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
+to detect this situation, but cannot do so reliably due to race
+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.
+
address@hidden avoids changing time stamps on files,
+without interfering with time stamp updates
+caused by other programs, so it works better with incremental backups.
+However, it requires a special @code{O_NOATIME} option from the
+underlying operating and file system implementation, and it also requires
+that searching directories does not update their access times. As of
+this writing (November 2005) this works only with Linux, and only with
+Linux kernels 2.6.8 and later. Worse, there is currently no reliable
+way to know whether this feature actually works. Sometimes
address@hidden knows that it does not work, and if you use
address@hidden then @command{tar} complains and
+exits right away. But other times @command{tar} might think that the
+option works when it actually does not.
+
+Currently @option{--atime-preserve} with no operand defaults to
address@hidden, but this may change in the future
+as support for @option{--atime-preserve=system} improves.
+
+If your operating system does not support
address@hidden@-system}, you might be able to preserve access
+times reliably by 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
+superuser privileges and can be a pain to manage.
+
address@hidden ANCHOR--backup 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Rather than deleting files from the file system, @command{tar} will
+back them up using simple or numbered backups, depending upon
address@hidden @xref{backup}.
+
address@hidden ANCHOR--block-number 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --block-number
address@hidden -R
+
+With this option present, @command{tar} prints error messages for read errors
+with the block number in the archive file. @xref{block-number}.
+
address@hidden ANCHOR--blocking-factor 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -b @var{blocking}
+
+Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per
+record. @xref{Blocking Factor}.
+
address@hidden ANCHOR--bzip2 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --bzip2
address@hidden -j
+
+This option tells @command{tar} to read or write archives through
address@hidden @xref{gzip}.
+
address@hidden ANCHOR--checkpoint 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+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}.
+
address@hidden ANCHOR--check-links 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --check-links
address@hidden -l
+If this option was given, @command{tar} will 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, a warning message will be
+output @footnote{Earlier versions of @acronym{GNU} @command{tar} understood
@option{-l} as a
+synonym for @option{--one-file-system}. The current semantics, which
+complies to UNIX98, was introduced with version
+1.15.91. @xref{Changes}, for more information.}.
+
address@hidden ANCHOR--compress 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--uncompress 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --compress
address@hidden --uncompress
address@hidden -Z
+
address@hidden will use the @command{compress} program when reading or
+writing the archive. This allows you to directly act on archives
+while saving space. @xref{gzip}.
+
address@hidden ANCHOR--confirmation 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --confirmation
+
+(See @option{--interactive}.) @xref{interactive}.
+
address@hidden ANCHOR--delay-directory-restore 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --delay-directory-restore
+
+Delay setting modification times and permissions of extracted
+directories until the end of extraction. @xref{Directory Modification Times
and Permissions}.
+
address@hidden ANCHOR--dereference 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --dereference
address@hidden -h
+
+When creating a @command{tar} archive, @command{tar} will archive the
+file that a symbolic link points to, rather than archiving the
+symlink. @xref{dereference}.
+
address@hidden ANCHOR--directory 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -C @var{dir}
+
+When this option is specified, @command{tar} will change its current directory
+to @var{dir} before performing any operations. When this option is used
+during archive creation, it is order sensitive. @xref{directory}.
+
address@hidden ANCHOR--exclude 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When performing operations, @command{tar} will skip files that match
address@hidden @xref{exclude}.
+
address@hidden ANCHOR--exclude-from 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -X @var{file}
+
+Similar to @option{--exclude}, except @command{tar} will use the list of
+patterns in the file @var{file}. @xref{exclude}.
+
address@hidden ANCHOR--exclude-caches 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --exclude-caches
+
+Automatically excludes all directories
+containing a cache directory tag. @xref{exclude}.
+
address@hidden ANCHOR--file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -f @var{archive}
+
address@hidden will use the file @var{archive} as the @command{tar} archive it
+performs operations on, rather than @command{tar}'s compilation dependent
+default. @xref{file tutorial}.
+
address@hidden ANCHOR--files-from 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -T @var{file}
+
address@hidden will use the contents of @var{file} as a list of archive members
+or files to operate on, in addition to those specified on the
+command-line. @xref{files}.
+
address@hidden ANCHOR--force-local 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --force-local
+
+Forces @command{tar} to interpret the filename given to @option{--file}
+as a local file, even if it looks like a remote tape drive name.
address@hidden and remote archives}.
+
address@hidden ANCHOR--format 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -H @var{format}
+
+Selects output archive format. @var{Format} may be one of the
+following:
+
address@hidden @samp
address@hidden v7
+Creates an archive that is compatible with Unix V7 @command{tar}.
+
address@hidden oldgnu
+Creates an archive that is compatible with GNU @command{tar} version
+1.12 or earlier.
+
address@hidden gnu
+Creates archive in GNU tar 1.13 format. Basically it is the same as
address@hidden with the only difference in the way it handles long
+numeric fields.
+
address@hidden ustar
+Creates a @acronym{POSIX.1-1988} compatible archive.
+
address@hidden posix
+Creates a @acronym{POSIX.1-2001 archive}.
+
address@hidden table
+
address@hidden, for a detailed discussion of these formats.
+
address@hidden ANCHOR--group 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Files added to the @command{tar} archive will have a group id of @var{group},
+rather than the group from the source file. @var{group} is first decoded
+as a group symbolic name, but if this interpretation fails, it has to be
+a decimal numeric group ID. @xref{override}.
+
+Also see the comments for the @address@hidden option.
+
address@hidden ANCHOR--gzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--gunzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--ungzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --gzip
address@hidden --gunzip
address@hidden --ungzip
address@hidden -z
+
+This option tells @command{tar} to read or write archives through
address@hidden, allowing @command{tar} to directly operate on several
+kinds of compressed archives transparently. @xref{gzip}.
+
address@hidden ANCHOR--help 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --help
address@hidden -?
+
address@hidden will print out a short message summarizing the operations and
+options to @command{tar} and exit. @xref{help}.
+
address@hidden ANCHOR--ignore-case 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-case
+Ignore case when matching member or file names with
+patterns. @xref{controlling pattern-matching}.
+
address@hidden ANCHOR--ignore-command-error 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-command-error
+Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--ignore-failed-read 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-failed-read
+
+Do not exit unsuccessfully merely because an unreadable file was encountered.
address@hidden
+
address@hidden ANCHOR--ignore-zeros 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-zeros
address@hidden -i
+
+With this option, @command{tar} will ignore zeroed blocks in the
+archive, which normally signals EOF. @xref{Reading}.
+
address@hidden ANCHOR--incremental 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --incremental
address@hidden -G
+
+Used to inform @command{tar} that it is working with an old
address@hidden incremental backup archive. It is intended
+primarily for backwards compatibility only. @xref{Incremental Dumps},
+for a detailed discussion of incremental archives.
+
address@hidden ANCHOR--index-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Send verbose output to @var{file} instead of to standard output.
+
address@hidden ANCHOR--info-script 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--new-volume-script 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden address@hidden
address@hidden -F @var{script-file}
+
+When @command{tar} is performing multi-tape backups, @var{script-file} is run
+at the end of each tape. If @var{script-file} exits with nonzero status,
address@hidden fails immediately. @xref{info-script}, for a detailed
+discussion of @var{script-file}.
+
address@hidden ANCHOR--interactive 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --interactive
address@hidden --confirmation
address@hidden -w
+
+Specifies that @command{tar} should ask the user for confirmation before
+performing potentially destructive options, such as overwriting files.
address@hidden
+
address@hidden ANCHOR--keep-newer-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --keep-newer-files
+
+Do not replace existing files that are newer than their archive copies
+when extracting files from an archive.
+
address@hidden ANCHOR--keep-old-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --keep-old-files
address@hidden -k
+
+Do not overwrite existing files when extracting files from an archive.
address@hidden Old Files}.
+
address@hidden ANCHOR--label 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -V @var{name}
+
+When creating an archive, instructs @command{tar} to write @var{name}
+as a name record in the archive. When extracting or listing archives,
address@hidden will only operate on archives that have a label matching
+the pattern specified in @var{name}. @xref{Tape Files}.
+
address@hidden ANCHOR--listed-incremental 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -g @var{snapshot-file}
+
+During a @option{--create} operation, specifies that the archive that
address@hidden creates is a new @acronym{GNU}-format incremental
+backup, using @var{snapshot-file} to determine which files to backup.
+With other operations, informs @command{tar} that the archive is in
+incremental format. @xref{Incremental Dumps}.
+
address@hidden ANCHOR--mode 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use
address@hidden for the archive members, rather than the permissions
+from the files. @var{permissions} can be specified either as an octal
+number or as symbolic permissions, like with
address@hidden @xref{override}.
+
address@hidden ANCHOR--mtime 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use @var{date} as
+the modification time of members when creating archives, instead of
+their actual modification times. The value of @var{date} can be
+either a textual date representation (@pxref{Date input formats}) or a
+name of the existing file, starting with @samp{/} or @samp{.}. In the
+latter case, the modification time of that file is used. @xref{override}.
+
address@hidden ANCHOR--multi-volume 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --multi-volume
address@hidden -M
+
+Informs @command{tar} that it should create or otherwise operate on a
+multi-volume @command{tar} archive. @xref{Using Multiple Tapes}.
+
address@hidden address@hidden, summary}
address@hidden --new-volume-script
+
+(see --info-script)
+
address@hidden ANCHOR--seek 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --seek
address@hidden -n
+
+Assume that the archive media supports seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. This option is intended for use
+in cases when such recognition fails.
+
address@hidden ANCHOR--newer 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden address@hidden
address@hidden -N
+
+When creating an archive, @command{tar} will only add files that have changed
+since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it
+is taken to be the name of a file whose data modification time specifies
+the date. @xref{after}.
+
address@hidden ANCHOR--newer-mtime 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Like @option{--newer}, but add only files whose
+contents have changed (as opposed to just @option{--newer}, which will
+also back up files for which any status information has
+changed). @xref{after}.
+
address@hidden ANCHOR--no-anchored 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-anchored
+An exclude pattern can match any subsequence of the name's components.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-delay-directory-restore 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-delay-directory-restore
+
+Setting modification times and permissions of extracted
+directories when all files from this directory has been
+extracted. This is the default. @xref{Directory Modification Times and
Permissions}.
+
address@hidden ANCHOR--no-ignore-case 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-ignore-case
+Use case-sensitive matching.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-ignore-command-error 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-ignore-command-error
+Print warnings about subprocesses terminated with a non-zero exit
+code. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--no-overwrite-dir 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-overwrite-dir
+
+Preserve metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--no-quote-chars 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option
+(@pxref{quoting styles}).
+
address@hidden ANCHOR--no-recursion 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-recursion
+
+With this option, @command{tar} will not recurse into directories.
address@hidden
+
address@hidden ANCHOR--no-same-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-same-owner
address@hidden -o
+
+When extracting an archive, do not attempt to preserve the owner
+specified in the @command{tar} archive. This the default behavior
+for ordinary users.
+
address@hidden ANCHOR--no-same-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-same-permissions
+
+When extracting an archive, subtract the user's umask from files from
+the permissions specified in the archive. This is the default behavior
+for ordinary users.
+
address@hidden ANCHOR--no-unquote 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-unquote
+Treat all input file or member names literally, do not interpret
+escape sequences. @xref{input name quoting}.
+
address@hidden ANCHOR--no-wildcards 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-wildcards
+Do not use wildcards.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-wildcards-match-slash 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-wildcards-match-slash
+Wildcards do not match @samp{/}.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--null 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --null
+
+When @command{tar} is using the @option{--files-from} option, this option
+instructs @command{tar} to expect filenames terminated with @option{NUL}, so
address@hidden can correctly work with file names that contain newlines.
address@hidden
+
address@hidden ANCHOR--numeric-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --numeric-owner
+
+This option will notify @command{tar} that it should use numeric user
+and group IDs when creating a @command{tar} file, rather than names.
address@hidden
+
address@hidden -o
+The function of this option depends on the action @command{tar} is
+performing. When extracting files, @option{-o} is a synonym for
address@hidden, i.e. it prevents @command{tar} from
+restoring ownership of files being extracted.
+
+When creating an archive, it is a synonym for
address@hidden This behavior is for compatibility
+with previous versions of @acronym{GNU} @command{tar}, and will be
+removed in the future releases.
+
address@hidden, for more information.
+
address@hidden ANCHOR--occurrence 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+This option can be used in conjunction with one of the subcommands
address@hidden, @option{--diff}, @option{--extract} or
address@hidden when a list of files is given either on the command
+line or via @option{-T} option.
+
+This option instructs @command{tar} to process only the @var{number}th
+occurrence of each named file. @var{Number} defaults to 1, so
+
address@hidden
+tar -x -f archive.tar --occurrence filename
address@hidden smallexample
+
address@hidden
+will extract the first occurrence of the member @file{filename} from
@file{archive.tar}
+and will terminate without scanning to the end of the archive.
+
address@hidden ANCHOR--old-archive 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --old-archive
+Synonym for @option{--format=v7}.
+
address@hidden ANCHOR--one-file-system 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --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 @acronym{GNU} @command{tar} understood
@option{-l} as a
+synonym for @option{--one-file-system}. This has changed in version
+1.15.91. @xref{Changes}, for more information.}.
+
address@hidden ANCHOR--overwrite 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --overwrite
+
+Overwrite existing files and directory metadata when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--overwrite-dir 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --overwrite-dir
+
+Overwrite the metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file. @var{user} is first decoded as a user symbolic name, but if
+this interpretation fails, it has to be a decimal numeric user ID.
address@hidden
+
+This option does not affect extraction from archives.
+
address@hidden ANCHOR--transform 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Transform file or member names using @command{sed} replacement expression
address@hidden For example,
+
address@hidden
+$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .}
address@hidden smallexample
+
address@hidden
+will add to @file{archive} files from the current working directory,
+replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
+discussion, @xref{transform}.
+
+To see transformed member names in verbose listings, use
address@hidden option
+(@pxref{show-transformed-names}).
+
address@hidden ANCHOR--quote-chars 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them (@pxref{quoting styles}).
+
address@hidden ANCHOR--quoting-style 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Set quoting style to use when printing member and file names
+(@pxref{quoting styles}). Valid @var{style} values are:
address@hidden, @code{shell}, @code{shell-always}, @code{c},
address@hidden, @code{locale}, and @code{clocale}. Default quoting
+style is @code{escape}, unless overridden while configuring the
+package.
+
address@hidden ANCHOR--pax-option 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+This option is meaningful only with @acronym{POSIX.1-2001} archives
+(@pxref{posix}). It modifies the way @command{tar} handles the
+extended header keywords. @var{Keyword-list} is a comma-separated
+list of keyword options. @xref{PAX keywords}, for a detailed
+discussion.
+
address@hidden ANCHOR--portability 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --portability
address@hidden --old-archive
+Synonym for @option{--format=v7}.
+
address@hidden ANCHOR--posix 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --posix
+Same as @option{--format=posix}.
+
address@hidden ANCHOR--preserve 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve
+
+Synonymous with specifying both @option{--preserve-permissions} and
address@hidden @xref{Setting Access Permissions}.
+
address@hidden ANCHOR--preserve-order 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve-order
+
+(See @option{--same-order}; @pxref{Reading}.)
+
address@hidden ANCHOR--preserve-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--same-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve-permissions
address@hidden --same-permissions
address@hidden -p
+
+When @command{tar} is extracting an archive, it normally subtracts the
+users' umask from the permissions specified in the archive and uses
+that number as the permissions to create the destination file.
+Specifying this option instructs @command{tar} that it should use the
+permissions directly from the archive. @xref{Setting Access Permissions}.
+
address@hidden ANCHOR--read-full-records 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --read-full-records
address@hidden -B
+
+Specifies that @command{tar} should reblock its input, for reading
+from pipes on systems with buggy implementations. @xref{Reading}.
+
address@hidden ANCHOR--record-size 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Instructs @command{tar} to use @var{size} bytes per record when accessing the
+archive. @xref{Blocking Factor}.
+
address@hidden ANCHOR--recursion 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --recursion
+
+With this option, @command{tar} recurses into directories.
address@hidden
+
address@hidden ANCHOR--recursive-unlink 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --recursive-unlink
+
+Remove existing
+directory hierarchies before extracting directories of the same name
+from the archive. @xref{Recursive Unlink}.
+
address@hidden ANCHOR--remove-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --remove-files
+
+Directs @command{tar} to remove the source file from the file system after
+appending it to an archive. @xref{remove files}.
+
address@hidden ANCHOR--restrict 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --restrict
+
+Disable use of some potentially harmful @command{tar} options.
+Currently this option disables shell invocaton from multi-volume menu
+(@pxref{Using Multiple Tapes}).
+
address@hidden ANCHOR--rmt-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Notifies @command{tar} that it should use @var{cmd} instead of
+the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}).
+
address@hidden ANCHOR--rsh-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Notifies @command{tar} that is should use @var{cmd} to communicate with remote
+devices. @xref{Device}.
+
address@hidden ANCHOR--same-order 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --same-order
address@hidden --preserve-order
address@hidden -s
+
+This option is an optimization for @command{tar} when running on machines with
+small amounts of memory. It informs @command{tar} that the list of file
+arguments has already been sorted to match the order of files in the
+archive. @xref{Reading}.
+
address@hidden ANCHOR--same-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --same-owner
+
+When extracting an archive, @command{tar} will attempt to preserve the owner
+specified in the @command{tar} archive with this option present.
+This is the default behavior for the superuser; this option has an
+effect only for ordinary users. @xref{Attributes}.
+
address@hidden address@hidden, summary}
address@hidden --same-permissions
+
+(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
+
address@hidden ANCHOR--show-defaults 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-defaults
+
+Displays the default options used by @command{tar} and exits
+successfully. This option is intended for use in shell scripts.
+Here is an example of what you can see using this option:
+
address@hidden
+$ tar --show-defaults
+--format=gnu -f- -b20 --quoting-style=escape \
+--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
address@hidden smallexample
+
address@hidden ANCHOR--show-omitted-dirs 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-omitted-dirs
+
+Instructs @command{tar} to mention directories its skipping over when
+operating on a @command{tar} archive. @xref{show-omitted-dirs}.
+
address@hidden ANCHOR--show-transformed-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--show-stored-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-transformed-names
address@hidden --show-stored-names
+
+Display file or member names after applying any transformations
+(@pxref{transform}). In particular, when used in conjunction with one of
+archive creation operations it instructs tar to list the member names
+stored in the archive, as opposed to the actual file
+names. @xref{listing member and file names}.
+
address@hidden ANCHOR--sparse 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --sparse
address@hidden -S
+
+Invokes a @acronym{GNU} extension when adding files to an archive that handles
+sparse files efficiently. @xref{sparse}.
+
address@hidden ANCHOR--sparse-version 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Specified the @dfn{format version} to use when archiving sparse
+files. Implies @option{--sparse}. @xref{sparse}. For the description
+of the supported sparse formats, @xref{Sparse Formats}.
+
address@hidden ANCHOR--starting-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -K @var{name}
+
+This option affects extraction only; @command{tar} will skip extracting
+files in the archive until it finds one that matches @var{name}.
address@hidden
+
address@hidden ANCHOR--strip-components 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Strip given @var{number} of leading components from file names before
address@hidden option was called @option{--strip-path} in
+version 1.14.} For example, if archive @file{archive.tar} contained
address@hidden/some/file/name}, then running
+
address@hidden
+tar --extract --file archive.tar --strip-components=2
address@hidden smallexample
+
address@hidden
+would extract this file to file @file{name}.
+
address@hidden ANCHOR--suffix 1
address@hidden
address@hidden address@hidden, summary}, summary
address@hidden address@hidden
+
+Alters the suffix @command{tar} uses when backing up files from the default
address@hidden @xref{backup}.
+
address@hidden ANCHOR--tape-length 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -L @var{num}
+
+Specifies the length of tapes that @command{tar} is writing as being
address@hidden@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}.
+
address@hidden ANCHOR--test-label 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --test-label
+
+Reads the volume label. If an argument is specified, test whether it
+matches the volume label. @xref{--test-label option}.
+
address@hidden ANCHOR--to-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+During extraction @command{tar} will pipe extracted files to the
+standard input of @var{command}. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--to-stdout 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --to-stdout
address@hidden -O
+
+During extraction, @command{tar} will extract files to stdout rather
+than to the file system. @xref{Writing to Standard Output}.
+
address@hidden ANCHOR--totals 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Displays the total number of bytes transferred when processing an
+archive. If an argument is given, these data are displayed on
+request, when signal @var{signo} is delivered to @command{tar}.
address@hidden
+
address@hidden ANCHOR--touch 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --touch
address@hidden -m
+
+Sets the data modification time of extracted files to the extraction time,
+rather than the data modification time stored in the archive.
address@hidden Modification Times}.
+
address@hidden address@hidden, summary}
address@hidden --uncompress
+
+(See @option{--compress}. @pxref{gzip})
+
address@hidden address@hidden, summary}
address@hidden --ungzip
+
+(See @option{--gzip}. @pxref{gzip})
+
address@hidden ANCHOR--unlink-first 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --unlink-first
address@hidden -U
+
+Directs @command{tar} to remove the corresponding file from the file
+system before extracting it from the archive. @xref{Unlink First}.
+
address@hidden ANCHOR--unquote 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --unquote
+Enable unquoting input file or member names (default). @xref{input
+name quoting}.
+
address@hidden ANCHOR--use-compress-program 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Instructs @command{tar} to access the archive through @var{prog}, which is
+presumed to be a compression program of some sort. @xref{gzip}.
+
address@hidden ANCHOR--utc 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --utc
+
+Display file modification dates in @acronym{UTC}. This option implies
address@hidden
+
address@hidden ANCHOR--verbose 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --verbose
address@hidden -v
+
+Specifies that @command{tar} should be more verbose about the operations its
+performing. This option can be specified multiple times for some
+operations to increase the amount of information displayed.
address@hidden
+
address@hidden ANCHOR--verify 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --verify
address@hidden -W
+
+Verifies that the archive was correctly written when creating an
+archive. @xref{verify}.
+
address@hidden ANCHOR--version 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --version
+
+Print information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden
+
address@hidden ANCHOR--volno-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Used in conjunction with @option{--multi-volume}. @command{tar} will
+keep track of which volume of a multi-volume archive its working in
address@hidden @xref{volno-file}.
+
address@hidden ANCHOR--wildcards 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --wildcards
+Use wildcards when matching member names with patterns.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--wildcards-match-slash 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --wildcards-match-slash
+Wildcards match @samp{/}.
address@hidden pattern-matching}.
address@hidden table
+
address@hidden Short Option Summary
address@hidden Short Options Cross Reference
+
+Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
+
address@hidden @columnfractions 0.20 0.80
address@hidden Short Option @tab Reference
+
address@hidden -A @tab @ref{--concatenate}.
+
address@hidden -B @tab @ref{--read-full-records}.
+
address@hidden -C @tab @ref{--directory}.
+
address@hidden -F @tab @ref{--info-script}.
+
address@hidden -G @tab @ref{--incremental}.
+
address@hidden -K @tab @ref{--starting-file}.
+
address@hidden -L @tab @ref{--tape-length}.
+
address@hidden -M @tab @ref{--multi-volume}.
+
address@hidden -N @tab @ref{--newer}.
+
address@hidden -O @tab @ref{--to-stdout}.
+
address@hidden -P @tab @ref{--absolute-names}.
+
address@hidden -R @tab @ref{--block-number}.
+
address@hidden -S @tab @ref{--sparse}.
+
address@hidden -T @tab @ref{--files-from}.
+
address@hidden -U @tab @ref{--unlink-first}.
+
address@hidden -V @tab @ref{--label}.
+
address@hidden -W @tab @ref{--verify}.
+
address@hidden -X @tab @ref{--exclude-from}.
+
address@hidden -Z @tab @ref{--compress}.
+
address@hidden -b @tab @ref{--blocking-factor}.
+
address@hidden -c @tab @ref{--create}.
+
address@hidden -d @tab @ref{--compare}.
+
address@hidden -f @tab @ref{--file}.
+
address@hidden -g @tab @ref{--listed-incremental}.
+
address@hidden -h @tab @ref{--dereference}.
+
address@hidden -i @tab @ref{--ignore-zeros}.
+
address@hidden -j @tab @ref{--bzip2}.
+
address@hidden -k @tab @ref{--keep-old-files}.
+
address@hidden -l @tab @ref{--check-links}.
+
address@hidden -m @tab @ref{--touch}.
+
address@hidden -o @tab When creating, @ref{--no-same-owner}, when extracting ---
address@hidden
+
+The later usage is deprecated. It is retained for compatibility with
+the earlier versions of @acronym{GNU} @command{tar}. In the future releases
address@hidden will be equivalent to @option{--no-same-owner} only.
+
address@hidden -p @tab @ref{--preserve-permissions}.
+
address@hidden -r @tab @ref{--append}.
+
address@hidden -s @tab @ref{--same-order}.
+
address@hidden -t @tab @ref{--list}.
+
address@hidden -u @tab @ref{--update}.
+
address@hidden -v @tab @ref{--verbose}.
+
address@hidden -w @tab @ref{--interactive}.
+
address@hidden -x @tab @ref{--extract}.
+
address@hidden -z @tab @ref{--gzip}.
+
address@hidden multitable
+
address@hidden help
address@hidden @acronym{GNU} @command{tar} documentation
+
address@hidden Getting program version number
address@hidden version
address@hidden Version of the @command{tar} program
+Being careful, the first thing is really checking that you are using
address@hidden @command{tar}, indeed. The @option{--version} option
+causes @command{tar} to print information about its name, version,
+origin and legal status, all on standard output, and then exit
+successfully. For example, @address@hidden --version}} might print:
+
address@hidden
+tar (GNU tar) 1.15.92
+Copyright (C) 2006 Free Software Foundation, Inc.
+This is free software. You may redistribute copies of it under the terms
+of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by John Gilmore and Jay Fenlason.
address@hidden smallexample
+
address@hidden
+The first occurrence of @samp{tar} in the result above is the program
+name in the package (for example, @command{rmt} is another program),
+while the second occurrence of @samp{tar} is the name of the package
+itself, containing possibly many programs. The package is currently
+named @samp{tar}, after the name of the main program it
address@hidden are plans to merge the @command{cpio} and
address@hidden packages into a single one which would be called
address@hidden So, who knows if, one of this days, the
address@hidden would not output @address@hidden (@acronym{GNU}
+paxutils) 3.2}}}.
+
address@hidden Obtaining help
address@hidden Listing all @command{tar} options
address@hidden address@hidden, introduction}
+Another thing you might want to do is checking the spelling or meaning
+of some particular @command{tar} option, without resorting to this
+manual, for once you have carefully read it. @acronym{GNU} @command{tar}
+has a short help feature, triggerable through the
address@hidden option. By using this option, @command{tar} will
+print a usage message listing all available options on standard
+output, then exit successfully, without doing anything else and
+ignoring all other options. Even if this is only a brief summary, it
+may be several screens long. So, if you are not using some kind of
+scrollable window, you might prefer to use something like:
+
address@hidden
+$ @kbd{tar --help | less}
address@hidden smallexample
+
address@hidden
+presuming, here, that you like using @command{less} for a pager. Other
+popular pagers are @command{more} and @command{pg}. If you know about some
address@hidden which interests you and do not want to read all the
address@hidden output, another common idiom is doing:
+
address@hidden
+tar --help | grep @var{keyword}
address@hidden smallexample
+
address@hidden
+for getting only the pertinent lines. Notice, however, that some
address@hidden options have long description lines and the above
+command will list only the first of them.
+
+The exact look of the option summary displayed by @kbd{tar --help} is
+configurable. @xref{Configuring Help Summary}, for a detailed description.
+
address@hidden 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
address@hidden option 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
+this paragraph, you already have the @command{tar} manual in some
+form. This manual is available in a variety of forms from
address@hidden://www.gnu.org/software/tar/manual}. It may be printed out of
the @acronym{GNU} @command{tar}
+distribution, provided you have @TeX{} already installed somewhere,
+and a laser printer around. Just configure the distribution, execute
+the command @address@hidden dvi}}, then print @file{doc/tar.dvi} the
+usual way (contact your local guru to know how). If @acronym{GNU}
@command{tar}
+has been conveniently installed at your place, this
+manual is also available in interactive, hypertextual form as an Info
+file. Just call @address@hidden tar}} or, if you do not have the
address@hidden program handy, use the Info reader provided within
address@hidden Emacs, calling @samp{tar} from the main Info menu.
+
+There is currently no @code{man} page for @acronym{GNU} @command{tar}.
+If you observe such a @code{man} page on the system you are running,
+either it does not belong to @acronym{GNU} @command{tar}, or it has not
+been produced by @acronym{GNU}. Some package maintainers convert
address@hidden --help} output to a man page, using @command{help2man}. In
+any case, please bear in mind that the authoritative source of
+information about @acronym{GNU} @command{tar} is this Texinfo documentation.
+
address@hidden defaults
address@hidden Obtaining @acronym{GNU} @command{tar} default values
+
address@hidden show-defaults
address@hidden @command{tar} has some predefined defaults that are used when
you do not
+explicitely specify another values. To obtain a list of such
+defaults, use @option{--show-defaults} option. This will output the
+values in the form of @command{tar} command line options:
+
address@hidden
address@hidden
address@hidden --show-defaults}
+--format=gnu -f- -b20 --quoting-style=escape
+--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that this option outputs only one line. The example output above
+has been split to fit page boundaries.
+
address@hidden
+The above output shows that this version of @acronym{GNU} @command{tar}
defaults to
+using @samp{gnu} archive format (@pxref{Formats}), it uses standard
+output as the archive, if no @option{--file} option has been given
+(@pxref{file tutorial}), the default blocking factor is 20
+(@pxref{Blocking Factor}). It also shows the default locations where
address@hidden will look for @command{rmt} and @command{rsh} binaries.
+
address@hidden verbose
address@hidden Checking @command{tar} progress
+
+Typically, @command{tar} performs most operations without reporting any
+information to the user except error messages. When using @command{tar}
+with many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
address@hidden provides several options that make observing @command{tar}
+easier. These options cause @command{tar} to print information as it
+progresses in its job, and you might want to use them just for being
+more careful about what is going on, or merely for entertaining
+yourself. If you have encountered a problem when operating on an
+archive, however, you may need more information than just an error
+message in order to solve the problem. The following options can be
+helpful diagnostic tools.
+
address@hidden Verbose operation
address@hidden verbose
+Normally, the @option{--list} (@option{-t}) command to list an archive
+prints just the file names (one per line) and the other commands are
+silent. When used with most operations, the @option{--verbose}
+(@option{-v}) option causes @command{tar} to print the name of each
+file or archive member as it is processed. This and the other options
+which make @command{tar} print status information can be useful in
+monitoring @command{tar}.
+
+With @option{--create} or @option{--extract}, @option{--verbose} used
+once just prints the names of the files or members as they are processed.
+Using it twice causes @command{tar} to print a longer listing
+(@xref{verbose member listing}, for the description) for each member.
+Since @option{--list} already prints the names of the members,
address@hidden used once with @option{--list} causes @command{tar}
+to print an @samp{ls -l} type listing of the files in the archive.
+The following examples both extract members with long list output:
+
address@hidden
+$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
+$ @kbd{tar xvvf archive.tar}
address@hidden smallexample
+
+Verbose output appears on the standard output except when an archive is
+being written to the standard output, as with @samp{tar --create
+--file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+installer let standard output be the default archive). In that case
address@hidden writes verbose output to the standard error stream.
+
+If @address@hidden is specified, @command{tar} sends
+verbose output to @var{file} rather than to standard output or standard
+error.
+
address@hidden
address@hidden Obtaining total status information
address@hidden totals
+The @option{--totals} option causes @command{tar} to print on the
+standard error the total amount of bytes transferred when processing
+an archive. When creating or appending to an archive, this option
+prints the number of bytes written to the archive and the average
+speed at which they have been written, e.g.:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --totals /home}
+Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
address@hidden group
address@hidden smallexample
+
+When reading an archive, this option displays the number of bytes
+read:
+
address@hidden
address@hidden
+$ @kbd{tar -x -f archive.tar --totals}
+Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
address@hidden group
address@hidden smallexample
+
+Finally, when deleting from an archive, the @option{--totals} option
+displays both numbers plus number of bytes removed from the archive:
+
address@hidden
address@hidden
+$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'}
+Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+Total bytes deleted: 1474048
address@hidden group
address@hidden smallexample
+
+You can also obtain this information on request. When
address@hidden is used with an argument, this argument is
+interpreted as a symbolic name of a signal, upon delivery of which the
+statistics is to be printed:
+
address@hidden @option
address@hidden address@hidden
+Print statistics upon delivery of signal @var{signo}. Valid arguments
+are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and
address@hidden Shortened names without @samp{SIG} prefix are also
+accepted.
address@hidden table
+
+Both forms of @option{--totals} option can be used simultaneously.
+Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to
+extract all members from its default archive and print statistics
+after finishing the extraction, as well as when receiving signal
address@hidden
+
address@hidden information}
address@hidden Progress information
address@hidden 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
address@hidden (@option{-R}), but do want visual confirmation
+that @command{tar} is actually making forward progress. By default it
+prints a message each 10 records read or written. This can be changed
+by giving it a numeric argument after an equal sign:
+
address@hidden
+$ @kbd{tar -c --checkpoint=1000} /var
+tar: Write checkpoint 1000
+tar: Write checkpoint 2000
+tar: Write checkpoint 3000
address@hidden smallexample
+
+This example shows the default checkpoint message used by
address@hidden If you place a dot immediately after the equal
+sign, it will print a @samp{.} at each checkpoint. For example:
+
address@hidden
+$ @kbd{tar -c --checkpoint=.1000} /var
+...
address@hidden smallexample
+
address@hidden show-omitted-dirs
address@hidden
+The @option{--show-omitted-dirs} option, when reading an archive---with
address@hidden or @option{--extract}, for example---causes a message
+to be printed for each directory in the archive which is skipped.
+This happens regardless of the reason for skipping: the directory might
+not have been named on the command line (implicitly or explicitly),
+it might be excluded by the use of the
address@hidden@var{pattern}} option, or some other reason.
+
address@hidden block-number
address@hidden Block number where error occurred
address@hidden
+If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along
with
+every message it would normally produce, the block number within the
+archive where the message was triggered. Also, supplementary messages
+are triggered when reading blocks full of NULs, or when hitting end of
+file on the archive. As of now, if the archive if properly terminated
+with a NUL block, the reading of the file may stop before end of file
+is met, so the position of end of file will not usually show when
address@hidden (@option{-R}) is used. Note that @acronym{GNU} @command{tar}
+drains the archive before exiting when reading the
+archive from a pipe.
+
address@hidden Error message, block number of
+This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
address@hidden (@option{-t}) when listing a file-system backup tape, allowing
you to
+choose among several backup tapes when retrieving a file later, in
+favor of the tape where the file appears earliest (closest to the
+front of the tape). @xref{backup}.
+
address@hidden interactive
address@hidden Asking for Confirmation During Operations
address@hidden Interactive operation
+
+Typically, @command{tar} carries out a command without stopping for
+further instructions. In some situations however, you may want to
+exclude some files and archive members from the operation (for instance
+if disk or storage space is tight). You can do this by excluding
+certain files automatically (@pxref{Choosing}), or by performing
+an operation interactively, using the @option{--interactive} (@option{-w})
option.
address@hidden also accepts @option{--confirmation} for this option.
+
address@hidden interactive
+When the @option{--interactive} (@option{-w}) option is specified, before
+reading, writing, or deleting files, @command{tar} first prints a message
+for each such file, telling what operation it intends to take, then asks
+for confirmation on the terminal. The actions which require
+confirmation include adding a file to the archive, extracting a file
+from the archive, deleting a file from the archive, and deleting a file
+from disk. To confirm the action, you must type a line of input
+beginning with @samp{y}. If your input line begins with anything other
+than @samp{y}, @command{tar} skips that file.
+
+If @command{tar} is reading the archive from the standard input,
address@hidden opens the file @file{/dev/tty} to support the interactive
+communications.
+
+Verbose output is normally sent to standard output, separate from
+other error messages. However, if the archive is produced directly
+on standard output, then verbose output is mixed with errors on
address@hidden Producing the archive on standard output may be used
+as a way to avoid using disk space, when the archive is soon to be
+consumed by another process reading it, say. Some people felt the need
+of producing an archive on stdout, still willing to segregate between
+verbose output and error output. A possible approach would be using a
+named pipe to receive the archive, and having the consumer process to
+read from that named pipe. This has the advantage of letting standard
+output free to receive verbose output, all separate from errors.
+
address@hidden operations
address@hidden @acronym{GNU} @command{tar} Operations
+
address@hidden
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
address@hidden menu
+
address@hidden Basic tar
address@hidden Basic @acronym{GNU} @command{tar} Operations
+
+The basic @command{tar} operations, @option{--create} (@option{-c}),
address@hidden (@option{-t}) and @option{--extract} (@option{--get},
address@hidden), are currently presented and described in the tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+
address@hidden @option
address@hidden address@hidden, complementary notes}
address@hidden --create
address@hidden -c
+
+Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use @option{--append}
+(@option{-r}) for adding all members. Some applications would not
+welcome making an exception in the way of adding the first archive
+member. On the other hand, many people reported that it is
+dangerously too easy for @command{tar} to destroy a magnetic tape with
+an empty address@hidden is well described in @cite{Unix-haters
+Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG
+Books, ISBN 1-56884-203-1.}. The two most common errors are:
+
address@hidden
address@hidden
+Mistakingly using @code{create} instead of @code{extract}, when the
+intent was to extract the full contents of an archive. This error
+is likely: keys @kbd{c} and @kbd{x} are right next to each other on
+the QWERTY keyboard. Instead of being unpacked, the archive then
+gets wholly destroyed. When users speak about @dfn{exploding} an
+archive, they usually mean something else :-).
+
address@hidden
+Forgetting the argument to @code{file}, when the intent was to create
+an archive with a single file in it. This error is likely because a
+tired user can easily add the @kbd{f} key to the cluster of option
+letters, by the mere force of habit, without realizing the full
+consequence of doing so. The usual consequence is that the single
+file, which was meant to be saved, is rather destroyed.
address@hidden enumerate
+
+So, recognizing the likelihood and the catastrophical nature of these
+errors, @acronym{GNU} @command{tar} now takes some distance from elegance, and
+cowardly refuses to create an archive when @option{--create} option is
+given, there are no arguments besides options, and
address@hidden (@option{-T}) option is @emph{not} used. To get
+around the cautiousness of @acronym{GNU} @command{tar} and nevertheless create
an
+archive with nothing in it, one may still use, as the value for the
address@hidden option, a file with no names in it, as shown in
+the following commands:
+
address@hidden
address@hidden --create --file=empty-archive.tar --files-from=/dev/null}
address@hidden cfT empty-archive.tar /dev/null}
address@hidden smallexample
+
address@hidden address@hidden, complementary notes}
address@hidden --extract
address@hidden --get
address@hidden -x
+
+A socket is stored, within a @acronym{GNU} @command{tar} archive, as a pipe.
+
address@hidden @option{--list} (@option{-t})
+
address@hidden @command{tar} now shows dates as @samp{1996-08-30},
+while it used to show them as @samp{Aug 30 1996}. Preferably,
+people should get used to ISO 8601 dates. Local American dates should
+be made available again with full date localization support, once
+ready. In the meantime, programs not being localizable for dates
+should prefer international dates, that's really the way to go.
+
+Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you
+are curious, it contains a detailed explanation of the ISO 8601 standard.
+
address@hidden table
+
address@hidden Advanced tar
address@hidden Advanced @acronym{GNU} @command{tar} Operations
+
+Now that you have learned the basics of using @acronym{GNU} @command{tar}, you
may want
+to learn about further ways in which @command{tar} can help you.
+
+This chapter presents five, more advanced operations which you probably
+won't use on a daily basis, but which serve more specialized functions.
+We also explain the different styles of options and why you might want
+to use one or another, or a combination of them in your @command{tar}
+commands. Additionally, this chapter includes options which allow you to
+define the output from @command{tar} more carefully, and provide help and
+error correction in special circumstances.
+
address@hidden
address@hidden
+
+
address@hidden
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
address@hidden menu
+
address@hidden Operations
address@hidden The Five Advanced @command{tar} Operations
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+In the last chapter, you learned about the first three operations to
address@hidden This chapter presents the remaining five operations to
address@hidden: @option{--append}, @option{--update}, @option{--concatenate},
address@hidden, and @option{--compare}.
+
+You are not likely to use these operations as frequently as those
+covered in the last chapter; however, since they perform specialized
+functions, they are quite useful when you do need to use them. We
+will give examples using the same directory and files that you created
+in the last chapter. As you may recall, the directory is called
address@hidden, the files are @samp{jazz}, @samp{blues}, @samp{folk},
address@hidden, and the two archive files you created are
address@hidden and @samp{music.tar}.
+
+We will also use the archive files @samp{afiles.tar} and
address@hidden The archive @samp{afiles.tar} contains the members @samp{apple},
address@hidden, and @samp{aspic}; @samp{bfiles.tar} contains the members
address@hidden/birds}, @samp{baboon}, and @samp{./box}.
+
+Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the @file{practice} directory that
+you created in the previous chapter; see @ref{prepare for examples}.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+
+The five operations that we will cover in this chapter are:
+
address@hidden @option
address@hidden --append
address@hidden -r
+Add new entries to an archive that already exists.
address@hidden --update
address@hidden -r
+Add more recent copies of archive members to the end of an archive, if
+they exist.
address@hidden --concatenate
address@hidden --catenate
address@hidden -A
+Add one or more pre-existing archives to the end of another archive.
address@hidden --delete
+Delete items from an archive (does not work on tapes).
address@hidden --compare
address@hidden --diff
address@hidden -d
+Compare archive members to their counterparts in the file system.
address@hidden table
+
address@hidden append
address@hidden How to Add Files to Existing Archives: @option{--append}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden append
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use @option{--append} (@option{-r}).
+The archive must already exist in order to use @option{--append}. (A
+related operation is the @option{--update} operation; you can use this
+to add newer versions of archive members to an existing archive. To learn how
to
+do this with @option{--update}, @pxref{update}.)
+
+If you use @option{--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 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 @option{--list} (@option{-t}), you will see all
+of those members listed, with their data modification times, owners, etc.
+
+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
+other members would end up in the working directory. This is because
address@hidden 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 address@hidden you give it
address@hidden option, or the disk copy is newer than the
+the one in the archive and you invoke @command{tar} with
address@hidden 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
address@hidden contained three copies of file @file{myfile}, then
+the command
+
address@hidden
+tar --extract --file archive.tar --occurrence=2 myfile
address@hidden smallexample
+
address@hidden
+would extract only the second copy. @xref{Option
+Summary,---occurrence}, for the description of @option{--occurrence}
+option.
+
address@hidden
address@hidden
+
+
address@hidden Members, replacing with other members
address@hidden Replacing members with other members
+If you want to replace an archive member, use @option{--delete} to
+delete the member you want to remove from the archive, , and then use
address@hidden to add the member you want to be in the archive. Note
+that you can not change the order of the archive; the most recently
+added member will still appear last. In this sense, you cannot truly
+``replace'' one member with another. (Replacing one member with another
+will not work on certain types of media, such as tapes; see @ref{delete}
+and @ref{Media}, for more information.)
+
address@hidden
+* appending files:: Appending Files to an Archive
+* multiple::
address@hidden menu
+
address@hidden appending files
address@hidden Appending Files to an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Adding files to an Archive
address@hidden Appending files to an Archive
address@hidden Archives, Appending files to
+
+The simplest way to add a file to an already existing archive is the
address@hidden (@option{-r}) operation, which writes specified
+files into the archive whether or not they are already among the
+archived files.
+
+When you use @option{--append}, you @emph{must} specify file name
+arguments, as there is no default. If you specify a file that already
+exists in the archive, another copy of the file will be added to the
+end of the archive. As with other operations, the member names of the
+newly added files will be exactly the same as their names given on the
+command line. The @option{--verbose} (@option{-v}) option will print
+out the names of the files as they are written into the archive.
+
address@hidden cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid @command{tar} archive, or else the results of using this
+operation will be unpredictable. @xref{Media}.
+
+To demonstrate using @option{--append} to add a file to an archive,
+create a file called @file{rock} in the @file{practice} directory.
+Make sure you are in the @file{practice} directory. Then, run the
+following @command{tar} command to add @file{rock} to
address@hidden:
+
address@hidden
+$ @kbd{tar --append --file=collection.tar rock}
address@hidden smallexample
+
address@hidden
+If you now use the @option{--list} (@option{-t}) operation, you will see that
address@hidden has been added to the archive:
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
address@hidden smallexample
+
address@hidden multiple
address@hidden Multiple Members with the Same Name
+
+You can use @option{--append} (@option{-r}) to add copies of files
+which have been updated since the archive was created. (However, we
+do not recommend doing this since there is another @command{tar}
+option called @option{--update}; @xref{update}, for more information.
+We describe this use of @option{--append} here for the sake of
+completeness.) When you extract the archive, the older version will
+be effectively lost. This works because files are extracted from an
+archive in the order in which they were archived. Thus, when the
+archive is extracted, a file archived later in time will replace a
+file of the same name which was archived earlier, even though the
+older version of the file will remain in the archive unless you delete
+all versions of the file.
+
+Supposing you change the file @file{blues} and then append the changed
+version to @file{collection.tar}. As you saw above, the original
address@hidden is in the archive @file{collection.tar}. If you change the
+file and append the new version of the file to the archive, there will
+be two copies in the archive. When you extract the archive, the older
+version of the file will be extracted first, and then replaced by the
+newer version when it is extracted.
+
+You can append the new, changed copy of the file @file{blues} to the
+archive in this way:
+
address@hidden
+$ @kbd{tar --append --verbose --file=collection.tar blues}
+blues
address@hidden smallexample
+
address@hidden
+Because you specified the @option{--verbose} option, @command{tar} has
+printed the name of the file being appended as it was acted on. Now
+list the contents of the archive:
+
address@hidden
+$ @kbd{tar --list --verbose --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
+-rw-r--r-- me user 58 1996-10-24 18:30 blues
address@hidden smallexample
+
address@hidden
+The newest version of @file{blues} is now at the end of the archive
+(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.
+
+If you wish to extract the first occurrence of the file @file{blues}
+from the archive, use @option{--occurrence} option, as shown in
+the following example:
+
address@hidden
+$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
address@hidden smallexample
+
address@hidden, for more information on @option{--extract} and
address@hidden Summary, --occurrence}, for the description of
address@hidden option.
+
address@hidden update
address@hidden Updating an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Updating an archive
+
address@hidden update
+In the previous section, you learned how to use @option{--append} to
+add a file to an existing archive. A related operation is
address@hidden (@option{-u}). The @option{--update} operation
+updates a @command{tar} archive by comparing the date of the specified
+archive members against the date of the file with the same name. If
+the file has been modified more recently than the archive member, then
+the newer version of the file is added to the archive (as with
address@hidden).
+
+Unfortunately, you cannot use @option{--update} with magnetic tape drives.
+The operation will fail.
+
address@hidden
address@hidden
+
+
+Both @option{--update} and @option{--append} work by adding to the end
+of the archive. When you extract a file from the archive, only the
+version stored last will wind up in the file system, unless you use
+the @option{--backup} option. @xref{multiple}, for a detailed discussion.
+
address@hidden
+* how to update::
address@hidden menu
+
address@hidden how to update
address@hidden How to Update an Archive Using @option{--update}
+
+You must use file name arguments with the @option{--update}
+(@option{-u}) operation. If you don't specify any files,
address@hidden won't act on any files and won't tell you that it didn't
+do anything (which may end up confusing you).
+
address@hidden note: the above parenthetical added because in fact, this
address@hidden behavior just confused the author. :-)
+
+To see the @option{--update} option at work, create a new file,
address@hidden, in your practice directory, and some extra text to the
+file @file{blues}, using any text editor. Then invoke @command{tar} with
+the @samp{update} operation and the @option{--verbose} (@option{-v})
+option specified, using the names of all the files in the practice
+directory as file name arguments:
+
address@hidden
+$ @kbd{tar --update -v -f collection.tar blues folk rock classical}
+blues
+classical
+$
address@hidden smallexample
+
address@hidden
+Because we have specified verbose mode, @command{tar} prints out the names
+of the files it is working on, which in this case are the names of the
+files that needed to be updated. If you run @samp{tar --list} and look
+at the archive, you will see @file{blues} and @file{classical} at its
+end. There will be a total of two versions of the member @samp{blues};
+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
+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.
+
address@hidden (@option{-u}) is not suitable for performing backups for two
+reasons: it does not change directory content entries, and it
+lengthens the archive every time it is used. The @acronym{GNU} @command{tar}
+options intended specifically for backups are more
+efficient. If you need to run backups, please consult @ref{Backups}.
+
address@hidden concatenate
address@hidden Combining Archives with @option{--concatenate}
+
address@hidden Adding archives to an archive
address@hidden Concatenating Archives
address@hidden concatenate
address@hidden catenate
address@hidden @cindex @option{-A} described
+Sometimes it may be convenient to add a second archive onto the end of
+an archive rather than adding individual files to the archive. To add
+one or more archives to the end of another archive, you should use the
address@hidden (@option{--catenate}, @option{-A}) operation.
+
+To use @option{--concatenate}, give the first archive with
address@hidden 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.
address@hidden 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
address@hidden, @command{tar} will use the value of the environment
+variable @env{TAPE}, or, if this has not been set, the default archive name.
+
address@hidden
address@hidden
+
+
+To demonstrate how @option{--concatenate} works, create two small archives
+called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
+files from @file{practice}:
+
address@hidden
+$ @kbd{tar -cvf bluesrock.tar blues rock}
+blues
+rock
+$ @kbd{tar -cvf folkjazz.tar folk jazz}
+folk
+jazz
address@hidden smallexample
+
address@hidden
+If you like, You can run @samp{tar --list} to make sure the archives
+contain what they are supposed to:
+
address@hidden
+$ @kbd{tar -tvf bluesrock.tar}
+-rw-r--r-- melissa user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa user 33 1997-01-20 15:34 rock
+$ @kbd{tar -tvf jazzfolk.tar}
+-rw-r--r-- melissa user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
address@hidden smallexample
+
+We can concatenate these two archives with @command{tar}:
+
address@hidden
+$ @kbd{cd ..}
+$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
address@hidden smallexample
+
+If you now list the contents of the @file{bluesrock.tar}, you will see
+that now it also contains the archive members of @file{jazzfolk.tar}:
+
address@hidden
+$ @kbd{tar --list --file=bluesrock.tar}
+blues
+rock
+folk
+jazz
address@hidden smallexample
+
+When you use @option{--concatenate}, the source and target archives must
+already exist and must have been created using compatible format
+parameters. Notice, that @command{tar} does not check whether the
+archives it concatenates have compatible formats, it does not
+even check if the files are really tar archives.
+
+Like @option{--append} (@option{-r}), this operation cannot be performed on
some
+tape drives, due to deficiencies in the formats those tape drives use.
+
address@hidden @code{concatenate} vs @command{cat}
address@hidden @command{cat} vs @code{concatenate}
+It may seem more intuitive to you to want or try to use @command{cat} to
+concatenate two archives instead of using the @option{--concatenate}
+operation; after all, @command{cat} is the utility for combining files.
+
+However, @command{tar} archives incorporate an end-of-file marker which
+must be removed if the concatenated archives are to be read properly as
+one archive. @option{--concatenate} removes the end-of-archive marker
+from the target archive before each new archive is appended. If you use
address@hidden to combine the archives, the result will not be a valid
address@hidden format archive. If you need to retrieve files from an
+archive that was added to using the @command{cat} utility, use the
address@hidden (@option{-i}) option. @xref{Ignore Zeros}, for further
+information on dealing with archives improperly combined using the
address@hidden shell utility.
+
address@hidden delete
address@hidden Removing Archive Members Using @option{--delete}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Deleting files from an archive
address@hidden Removing files from an archive
+
address@hidden delete
+You can remove members from an archive by using the @option{--delete}
+option. Specify the name of the archive with @option{--file}
+(@option{-f}) and then specify the names of the members to be deleted;
+if you list no member names, nothing will be deleted. The
address@hidden option will cause @command{tar} to print the names
+of the members as they are deleted. As with @option{--extract}, you
+must give the exact member names when using @samp{tar --delete}.
address@hidden will remove all versions of the named file from the
+archive. The @option{--delete} operation can run very slowly.
+
+Unlike other operations, @option{--delete} has no short form.
+
address@hidden Tapes, using @option{--delete} and
address@hidden Deleting from tape archives
+This operation will rewrite the archive. You can only use
address@hidden on an archive if the archive device allows you to
+write to any point on the media, such as a disk; because of this, it
+does not work on magnetic tapes. Do not try to delete an archive member
+from a magnetic tape; the action will not succeed, and you will be
+likely to scramble the archive and damage your tape. There is no safe
+way (except by completely re-writing the archive) to delete files from
+most kinds of magnetic tape. @xref{Media}.
+
+To delete all versions of the file @file{blues} from the archive
address@hidden in the @file{practice} directory, make sure you
+are in that directory, and then,
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
+blues
+folk
+jazz
+rock
+$ @kbd{tar --delete --file=collection.tar blues}
+$ @kbd{tar --list --file=collection.tar}
+folk
+jazz
+rock
+$
address@hidden smallexample
+
address@hidden
address@hidden
+
+
+The @option{--delete} option has been reported to work properly when
address@hidden acts as a filter from @code{stdin} to @code{stdout}.
+
address@hidden compare
address@hidden Comparing Archive Members with the File System
address@hidden Verifying the currency of an archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden compare
+The @option{--compare} (@option{-d}), or @option{--diff} operation compares
+specified archive members against files with the same names, and then
+reports differences in file size, mode, owner, modification date and
+contents. You should @emph{only} specify archive member names, not file
+names. If you do not name any members, then @command{tar} will compare the
+entire archive. If a file is represented in the archive but does not
+exist in the file system, @command{tar} reports a difference.
+
+You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
address@hidden ignores files in the file system that do not have
+corresponding members in the archive.
+
+The following example compares the archive members @file{rock},
address@hidden and @file{funk} in the archive @file{bluesrock.tar} with
+files of the same name in the file system. (Note that there is no file,
address@hidden; @command{tar} will report an error message.)
+
address@hidden
+$ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
+rock
+blues
+tar: funk not found in archive
address@hidden smallexample
+
+The spirit behind the @option{--compare} (@option{--diff},
address@hidden) 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}.
+
address@hidden create options
address@hidden Options Used by @option{--create}
+
address@hidden address@hidden, additional options}
+The previous chapter described the basics of how to use
address@hidden (@option{-c}) to create an archive from a set of files.
address@hidden This section described advanced options to be used with
address@hidden
+
address@hidden
+* override:: Overriding File Metadata.
+* Ignore Failed Read::
address@hidden menu
+
address@hidden override
address@hidden Overriding File Metadata
+
+As described above, a @command{tar} archive keeps, for each member it contains,
+its @dfn{metadata}, such as modification time, mode and ownership of
+the file. @acronym{GNU} @command{tar} allows to replace these data with other
values
+when adding files to the archive. The options described in this
+section affect creation of archives of any type. For POSIX archives,
+see also @ref{PAX keywords}, for additional ways of controlling
+metadata, stored in the archive.
+
address@hidden @option
address@hidden mode
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use
address@hidden for the archive members, rather than the permissions
+from the files. @var{permissions} can be specified either as an octal
+number or as symbolic permissions, like with
address@hidden (@xref{File permissions, Permissions, File
+permissions, fileutils, @acronym{GNU} file utilities}. This reference
+also has useful information for those not being overly familiar with
+the UNIX permission system). Using latter syntax allows for
+more flexibility. For example, the value @samp{a+rw} adds read and write
+permissions for everybody, while retaining executable bits on directories
+or on any other file already marked as executable:
+
address@hidden
+$ @kbd{tar -c -f archive.tar --mode='a+rw' .}
address@hidden smallexample
+
address@hidden address@hidden
address@hidden mtime
+
+When adding files to an archive, @command{tar} will use @var{date} as
+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
+with @samp{/} or @samp{.}. In the latter case, the modification time
+of that file will be used.
+
+The following example will set the modification date to 00:00:00 UTC,
+January 1, 1970:
+
address@hidden
+$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .}
address@hidden smallexample
+
address@hidden
+When used with @option{--verbose} (@pxref{verbose tutorial}) @acronym{GNU}
@command{tar}
+will try to convert the specified date back to its textual
+representation and compare it with the one given with
address@hidden options. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date.
+
+For example:
+
address@hidden
+$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
+tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+13:06:29.152478
address@hidden
address@hidden smallexample
+
address@hidden address@hidden
address@hidden owner
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file. The argument @var{user} can be either an existing user symbolic
+name, or a decimal numeric user ID.
+
+There is no value indicating a missing number, and @samp{0} usually means
address@hidden Some people like to force @samp{0} as the value to offer in
+their distributions for the owner of files, because the @code{root} user is
+anonymous anyway, so that might as well be the owner of anonymous
+archives. For example:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --owner=0 .}
+# @r{Or:}
+$ @kbd{tar -c -f archive.tar --owner=root .}
address@hidden group
address@hidden smallexample
+
address@hidden address@hidden
address@hidden group
+
+Files added to the @command{tar} archive will have a group id of @var{group},
+rather than the group from the source file. The argument @var{group}
+can be either an existing group symbolic name, or a decimal numeric group ID.
address@hidden table
+
address@hidden Ignore Failed Read
address@hidden Ignore Fail Read
+
address@hidden @option
address@hidden --ignore-failed-read
address@hidden ignore-failed-read
+Do not exit with nonzero on unreadable files or directories.
address@hidden table
+
address@hidden extract options
address@hidden Options Used by @option{--extract}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden address@hidden, additional options}
+The previous chapter showed how to use @option{--extract} to extract
+an archive into the file system. Various options cause @command{tar} to
+extract more information than just file contents, such as the owner,
+the permissions, the modification date, and so forth. This section
+presents options to be used with @option{--extract} when certain special
+considerations arise. You may review the information presented in
address@hidden for more basic information about the
address@hidden operation.
+
address@hidden
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
address@hidden menu
+
address@hidden Reading
address@hidden Options to Help Read Archives
address@hidden Options when reading archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Reading incomplete records
address@hidden Records, incomplete
address@hidden read-full-records
+Normally, @command{tar} will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
address@hidden will report an error. However, some devices do not always
+return full records, or do not require the last record of an archive to
+be padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the @option{--read-full-records}
(@option{-B}) option
+in conjunction with the @option{--extract} or @option{--list} operations.
address@hidden
+
+The @option{--read-full-records} (@option{-B}) option is turned on by default
when
address@hidden reads an archive from standard input, or from a remote
+machine. This is because on BSD Unix systems, attempting to read a
+pipe returns however much happens to be in the pipe, even if it is
+less than was requested. If this option were not enabled, @command{tar}
+would fail as soon as it read an incomplete record from the pipe.
+
+If you're not sure of the blocking factor of an archive, you can
+read the archive by specifying @option{--read-full-records} (@option{-B}) and
address@hidden@var{512-size}} (@option{-b
address@hidden), using a blocking factor larger than what the archive
+uses. This lets you avoid having to determine the blocking factor
+of an archive. @xref{Blocking Factor}.
+
address@hidden
+* read full records::
+* Ignore Zeros::
address@hidden menu
+
address@hidden read full records
address@hidden Reading Full Records
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden read-full-records
address@hidden --read-full-records
address@hidden -B
+Use in conjunction with @option{--extract} (@option{--get},
address@hidden) to read an archive which contains incomplete records, or
+one which has a blocking factor less than the one specified.
address@hidden table
+
address@hidden Ignore Zeros
address@hidden Ignoring Blocks of Zeros
+
address@hidden End-of-archive blocks, ignoring
address@hidden Ignoring end-of-archive blocks
address@hidden ignore-zeros
+Normally, @command{tar} stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
address@hidden (@option{-i}) allows @command{tar} to
+completely read an archive which contains a block of zeros before the
+end (i.e., a damaged archive, or one that was created by concatenating
+several archives together).
+
+The @option{--ignore-zeros} (@option{-i}) option is turned off by default
because many
+versions of @command{tar} write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read. @acronym{GNU}
@command{tar}
+does not write after the end of an archive, but seeks to
+maintain compatiblity among archiving utilities.
+
address@hidden @option
address@hidden --ignore-zeros
address@hidden -i
+To ignore blocks of zeros (i.e., end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
address@hidden or @option{--list}.
address@hidden table
+
address@hidden Writing
address@hidden Changing How @command{tar} Writes Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
address@hidden menu
+
address@hidden Dealing with Old Files
address@hidden Options Controlling the Overwriting of Existing Files
+
address@hidden address@hidden, introduced}
+When extracting files, if @command{tar} discovers that the extracted
+file already exists, it normally replaces the file by removing it before
+extracting it, to prevent confusion in the presence of hard or symbolic
+links. (If the existing file is a symbolic link, it is removed, not
+followed.) However, if a directory cannot be removed because it is
+nonempty, @command{tar} normally overwrites its metadata (ownership,
+permission, etc.). The @option{--overwrite-dir} option enables this
+default behavior. To be more cautious and preserve the metadata of
+such a directory, use the @option{--no-overwrite-dir} option.
+
address@hidden Overwriting old files, prevention
address@hidden address@hidden, introduced}
+To be even more cautious and prevent existing files from being replaced, use
+the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar}
to refuse
+to replace or update a file that already exists, i.e., a file with the
+same name as an archive member prevents extraction of that archive
+member. Instead, it reports an error.
+
address@hidden address@hidden, introduced}
+To be more aggressive about altering existing files, use the
address@hidden option. It causes @command{tar} to overwrite
+existing files and to follow existing symbolic links when extracting.
+
address@hidden Protecting old files
+Some people argue that @acronym{GNU} @command{tar} should not hesitate
+to overwrite files with other files when extracting. When extracting
+a @command{tar} archive, they expect to see a faithful copy of the
+state of the file system when the archive was created. It is debatable
+that this would always be a proper behavior. For example, suppose one
+has an archive in which @file{usr/local} is a link to
address@hidden/local2}. Since then, maybe the site removed the link and
+renamed the whole hierarchy from @file{/usr/local2} to
address@hidden/usr/local}. Such things happen all the time. I guess it would
+not be welcome at all that @acronym{GNU} @command{tar} removes the
+whole hierarchy just to make room for the link to be reinstated
+(unless it @emph{also} simultaneously restores the full
address@hidden/usr/local2}, of course!) @acronym{GNU} @command{tar} is indeed
+able to remove a whole hierarchy to reestablish a symbolic link, for
+example, but @emph{only if} @option{--recursive-unlink} is specified
+to allow this behavior. In any case, single files are silently
+removed.
+
address@hidden address@hidden, introduced}
+Finally, the @option{--unlink-first} (@option{-U}) option can improve
performance in
+some cases by causing @command{tar} to remove files unconditionally
+before extracting them.
+
address@hidden Overwrite Old Files
address@hidden Overwrite Old Files
+
address@hidden @option
address@hidden overwrite
address@hidden --overwrite
+Overwrite existing files and directory metadata when extracting files
+from an archive.
+
+This causes @command{tar} to write extracted files into the file system without
+regard to the files already on the system; i.e., files with the same
+names as archive members are overwritten when the archive is extracted.
+It also causes @command{tar} to extract the ownership, permissions,
+and time stamps onto any preexisting files or directories.
+If the name of a corresponding file name is a symbolic link, the file
+pointed to by the symbolic link will be overwritten instead of the
+symbolic link itself (if this is possible). Moreover, special devices,
+empty directories and even symbolic links are automatically removed if
+they are in the way of extraction.
+
+Be careful when using the @option{--overwrite} option, particularly when
+combined with the @option{--absolute-names} (@option{-P}) option, as this
combination
+can change the contents, ownership or permissions of any file on your
+system. Also, many systems do not take kindly to overwriting files that
+are currently being executed.
+
address@hidden overwrite-dir
address@hidden --overwrite-dir
+Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
address@hidden table
+
address@hidden Keep Old Files
address@hidden Keep Old Files
+
address@hidden @option
address@hidden keep-old-files
address@hidden --keep-old-files
address@hidden -k
+Do not replace existing files from archive. The
address@hidden (@option{-k}) option prevents @command{tar}
+from replacing existing files with files with the same name from the
+archive. The @option{--keep-old-files} option is meaningless with
address@hidden (@option{-t}). Prevents @command{tar} from replacing
+files in the file system during extraction.
address@hidden table
+
address@hidden Keep Newer Files
address@hidden Keep Newer Files
+
address@hidden @option
address@hidden keep-newer-files
address@hidden --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @option{--list} (@option{-t}).
address@hidden table
+
address@hidden Unlink First
address@hidden Unlink First
+
address@hidden @option
address@hidden unlink-first
address@hidden --unlink-first
address@hidden -U
+Remove files before extracting over them.
+This can make @command{tar} run a bit faster if you know in advance
+that the extracted files all need to be removed. Normally this option
+slows @command{tar} down slightly, so it is disabled by default.
address@hidden table
+
address@hidden Recursive Unlink
address@hidden Recursive Unlink
+
address@hidden @option
address@hidden recursive-unlink
address@hidden --recursive-unlink
+When this option is specified, try removing files and directory hierarchies
+before extracting over them. @emph{This is a dangerous option!}
address@hidden table
+
+If you specify the @option{--recursive-unlink} option,
address@hidden removes @emph{anything} that keeps you from extracting a file
+as far as current permissions will allow it. This could include removal
+of the contents of a full directory hierarchy.
+
address@hidden Data Modification Times
address@hidden Setting Data Modification Times
+
address@hidden Data modification times of extracted files
address@hidden Modification times of extracted files
+Normally, @command{tar} sets the data modification times of extracted
+files to the corresponding times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the data modification times of extracted files to the time when
+the files were extracted, use the @option{--touch} (@option{-m}) option in
+conjunction with @option{--extract} (@option{--get}, @option{-x}).
+
address@hidden @option
address@hidden touch
address@hidden --touch
address@hidden -m
+Sets the data modification time of extracted archive members to the time
+they were extracted, not the time recorded for them in the archive.
+Use in conjunction with @option{--extract} (@option{--get}, @option{-x}).
address@hidden table
+
address@hidden Setting Access Permissions
address@hidden Setting Access Permissions
+
address@hidden Permissions of extracted files
address@hidden Modes of extracted files
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use @option{--same-permissions}
+in conjunction with the @option{--extract} (@option{--get},
address@hidden) operation.
+
address@hidden @option
address@hidden preserve-permissions
address@hidden same-permissions
address@hidden --preserve-permissions
address@hidden --same-permissions
address@hidden @itemx --ignore-umask
address@hidden -p
+Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
address@hidden (@option{--get}, @option{-x}).
address@hidden table
+
address@hidden Directory Modification Times and Permissions
address@hidden Directory Modification Times and Permissions
+
+After sucessfully extracting a file member, @acronym{GNU} @command{tar}
normally
+restores its permissions and modification times, as described in the
+previous sections. This cannot be done for directories, because
+after extracting a directory @command{tar} will almost certainly
+extract files into that directory and this will cause the directory
+modification time to be updated. Moreover, restoring that directory
+permissions may not permit file creation within it. Thus, restoring
+directory permissions and modification times must be delayed at least
+until all files have been extracted into that directory. @acronym{GNU}
@command{tar}
+restores directories using the following approach.
+
+The extracted directories are created with the mode specified in the
+archive, as modified by the umask of the user, which gives sufficient
+permissions to allow file creation. The meta-information about the
+directory is recorded in the temporary list of directories. When
+preparing to extract next archive member, @acronym{GNU} @command{tar} checks
if the
+directory prefix of this file contains the remembered directory. If
+it does not, the program assumes that all files have been extracted
+into that directory, restores its modification time and permissions
+and removes its entry from the internal list. This approach allows
+to correctly restore directory meta-information in the majority of
+cases, while keeping memory requirements sufficiently small. It is
+based on the fact, that most @command{tar} archives use the predefined
+order of members: first the directory, then all the files and
+subdirectories in that directory.
+
+However, this is not always true. The most important exception are
+incremental archives (@pxref{Incremental Dumps}). The member order in
+an incremental archive is reversed: first all directory members are
+stored, followed by other (non-directory) members. So, when extracting
+from incremental archives, @acronym{GNU} @command{tar} alters the above
procedure. It
+remebers all restored directories, and restores their meta-data
+only after the entire archive has been processed. Notice, that you do
+not need to specity any special options for that, as @acronym{GNU}
@command{tar}
+automatically detects archives in incremental format.
+
+There may be cases, when such processing is required for normal archives
+too. Consider the following example:
+
address@hidden
address@hidden
+$ @kbd{tar --no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2}
+foo/
+foo/file1
+bar/
+bar/file
+foo/file2
address@hidden group
address@hidden smallexample
+
+During the normal operation, after encountering @file{bar}
address@hidden @command{tar} will assume that all files from the directory
@file{foo}
+were already extracted and will therefore restore its timestamp and
+permission bits. However, after extracting @file{foo/file2} the
+directory timestamp will be offset again.
+
+To correctly restore directory meta-information in such cases, use
address@hidden command line option:
+
address@hidden @option
address@hidden delay-directory-restore
address@hidden --delay-directory-restore
+Delays restoring of the modification times and permissions of extracted
+directories until the end of extraction. This way, correct
+meta-information is restored even if the archive has unusual member
+ordering.
+
address@hidden no-delay-directory-restore
address@hidden --no-delay-directory-restore
+Cancel the effect of the previous @option{--delay-directory-restore}.
+Use this option if you have used @option{--delay-directory-restore} in
address@hidden variable (@pxref{TAR_OPTIONS}) and wish to
+temporarily disable it.
address@hidden table
+
address@hidden Writing to Standard Output
address@hidden Writing to Standard Output
+
address@hidden Writing extracted files to standard output
address@hidden Standard output, writing extracted files to
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @option{--to-stdout} (@option{-O})
in
+conjunction with @option{--extract} (@option{--get}, @option{-x}). This
option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
address@hidden @option
address@hidden to-stdout
address@hidden --to-stdout
address@hidden -O
+Writes files to the standard output. Use only in conjunction with
address@hidden (@option{--get}, @option{-x}). When this option is
+used, instead of creating the files specified, @command{tar} writes
+the contents of the files extracted to its standard output. This may
+be useful if you are only extracting the files in order to send them
+through a pipe. This option is meaningless with @option{--list}
+(@option{-t}).
address@hidden table
+
+This can be useful, for example, if you have a tar archive containing
+a big file and don't want to store the file on disk before processing
+it. You can use a command like this:
+
address@hidden
+tar -xOzf foo.tgz bigfile | process
address@hidden smallexample
+
+or even like this if you want to process the concatenation of the files:
+
address@hidden
+tar -xOzf foo.tgz bigfile1 bigfile2 | process
address@hidden smallexample
+
+Hovewer, @option{--to-command} may be more convenient for use with
+multiple files. See the next section.
+
address@hidden Writing to an External Program
address@hidden Writing to an External Program
+
+You can instruct @command{tar} to send the contents of each extracted
+file to the standard input of an external program:
+
address@hidden @option
address@hidden to-command
address@hidden address@hidden
+Extract files and pipe their contents to the standard input of
address@hidden When this option is used, instead of creating the
+files specified, @command{tar} invokes @var{command} and pipes the
+contents of the files to its standard output. @var{Command} may
+contain command line arguments. The program is executed via
address@hidden -c}. Notice, that @var{command} is executed once for each
regular file
+extracted. Non-regular files (directories, etc.) are ignored when this
+option is used.
address@hidden table
+
+The command can obtain the information about the file it processes
+from the following environment variables:
+
address@hidden @var
address@hidden TAR_FILETYPE, to-command environment
address@hidden TAR_FILETYPE
+Type of the file. It is a single letter with the following meaning:
+
address@hidden @columnfractions 0.10 0.90
address@hidden f @tab Regular file
address@hidden d @tab Directory
address@hidden l @tab Symbolic link
address@hidden h @tab Hard link
address@hidden b @tab Block device
address@hidden c @tab Character device
address@hidden multitable
+
+Currently only regular files are supported.
+
address@hidden TAR_MODE, to-command environment
address@hidden TAR_MODE
+File mode, an octal number.
+
address@hidden TAR_FILENAME, to-command environment
address@hidden TAR_FILENAME
+The name of the file.
+
address@hidden TAR_REALNAME, to-command environment
address@hidden TAR_REALNAME
+Name of the file as stored in the archive.
+
address@hidden TAR_UNAME, to-command environment
address@hidden TAR_UNAME
+Name of the file owner.
+
address@hidden TAR_GNAME, to-command environment
address@hidden TAR_GNAME
+Name of the file owner group.
+
address@hidden TAR_ATIME, to-command environment
address@hidden TAR_ATIME
+Time of last access. It is a decimal number, representing seconds
+since the epoch. If the archive provides times with nanosecond
+precision, the nanoseconds are appended to the timestamp after a
+decimal point.
+
address@hidden TAR_MTIME, to-command environment
address@hidden TAR_MTIME
+Time of last modification.
+
address@hidden TAR_CTIME, to-command environment
address@hidden TAR_CTIME
+Time of last status change.
+
address@hidden TAR_SIZE, to-command environment
address@hidden TAR_SIZE
+Size of the file.
+
address@hidden TAR_UID, to-command environment
address@hidden TAR_UID
+UID of the file owner.
+
address@hidden TAR_GID, to-command environment
address@hidden TAR_GID
+GID of the file owner.
address@hidden table
+
+In addition to these variables, @env{TAR_VERSION} contains the
address@hidden @command{tar} version number.
+
+If @var{command} exits with a non-0 status, @command{tar} will print
+an error message similar to the following:
+
address@hidden
+tar: 2345: Child returned status 1
address@hidden smallexample
+
+Here, @samp{2345} is the PID of the finished process.
+
+If this behavior is not wanted, use @option{--ignore-command-error}:
+
address@hidden @option
address@hidden ignore-command-error
address@hidden --ignore-command-error
+Ignore exit codes of subprocesses. Notice that if the program
+exits on signal or otherwise terminates abnormally, the error message
+will be printed even if this option is used.
+
address@hidden no-ignore-command-error
address@hidden --no-ignore-command-error
+Cancel the effect of any previous @option{--ignore-command-error}
+option. This option is useful if you have set
address@hidden in @env{TAR_OPTIONS}
+(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it.
address@hidden table
+
address@hidden remove files
address@hidden Removing Files
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden remove-files
address@hidden --remove-files
+Remove files after adding them to the archive.
address@hidden table
+
address@hidden Scarce
address@hidden Coping with Scarce Resources
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Small memory
address@hidden Running out of space
+
address@hidden
+* Starting File::
+* Same Order::
address@hidden menu
+
address@hidden Starting File
address@hidden Starting File
+
address@hidden @option
address@hidden starting-file
address@hidden address@hidden
address@hidden -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @option{--extract} (@option{--get}, @option{-x}) or @option{--list}
(@option{-t}).
address@hidden table
+
address@hidden Middle of the archive, starting in the
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @address@hidden (@option{-K
address@hidden) to start extracting only after member @var{name} of the
+archive. This assumes, of course, that there is now free space, or
+that you are now extracting into a different file system. (You could
+also choose to suspend @command{tar}, remove unnecessary files from
+the file system, and then restart the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.
address@hidden Dumps}, @xref{interactive}, and @ref{exclude}.)
+
address@hidden Same Order
address@hidden Same Order
+
address@hidden @option
address@hidden Large lists of file names on small machines
address@hidden same-order
address@hidden preserve-order
address@hidden --same-order
address@hidden --preserve-order
address@hidden -s
+To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with @option{--compare} (@option{--diff},
address@hidden), @option{--list} (@option{-t}) or @option{--extract}
+(@option{--get}, @option{-x}).
address@hidden table
+
+The @option{--same-order} (@option{--preserve-order}, @option{-s}) option
tells @command{tar} that the list of file
+names to be listed or extracted is sorted in the same order as the
+files in the archive. This allows a large list of names to be used,
+even on a small machine that would not otherwise be able to hold all
+the names in memory at the same time. Such a sorted list can easily be
+created by running @samp{tar -t} on the archive and editing its output.
+
+This option is probably never needed on modern computer systems.
+
address@hidden backup
address@hidden Backup options
+
address@hidden backup options
+
address@hidden @command{tar} offers options for making backups of files
+before writing new versions. These options control the details of
+these backups. They may apply to the archive itself before it is
+created or rewritten, as well as individual extracted members. Other
address@hidden programs (@command{cp}, @command{install}, @command{ln},
+and @command{mv}, for example) offer similar options.
+
+Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting archives
+on systems having file name limitations, making different members appear
+has having similar names through the side-effect of name truncation.
+(This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.)
+When any existing file is backed up before being overwritten by extraction,
+then clashing files are automatically be renamed to be unique, and the
+true name is kept for only the last file of a series of clashing files.
+By using verbose mode, users may track exactly what happens.
+
+At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So, please
+do not learn to depend blindly on the details of the backup features.
+For example, currently, directories themselves are never renamed through
+using these options, so, extracting a file over a directory still has
+good chances to fail. Also, backup options apply to created archives,
+not only to extracted members. For created archives, backups will not
+be attempted when the archive is a block or character device, or when it
+refers to a remote file.
+
+For the sake of simplicity and efficiency, backups are made by renaming old
+files prior to creation or extraction, and not by copying. The original
+name is restored if the file creation fails. If a failure occurs after a
+partial extraction of a file, both the backup and the partially extracted
+file are kept.
+
address@hidden @samp
address@hidden address@hidden
address@hidden backup
address@hidden VERSION_CONTROL
address@hidden backups
+Back up files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+
+Use @var{method} to determine the type of backups made.
+If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
+environment variable. And if @env{VERSION_CONTROL} is not set,
+use the @samp{existing} method.
+
address@hidden version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the same values for @var{method} are accepted as in Emacs. This option
+also allows more descriptive names. The valid @var{method}s are:
+
address@hidden @samp
address@hidden t
address@hidden numbered
address@hidden numbered @r{backup method}
+Always make numbered backups.
+
address@hidden nil
address@hidden existing
address@hidden existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
address@hidden never
address@hidden simple
address@hidden simple @r{backup method}
+Always make simple backups.
+
address@hidden table
+
address@hidden address@hidden
address@hidden suffix
address@hidden backup suffix
address@hidden SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{--backup}. If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
address@hidden table
+
address@hidden Applications
address@hidden Notable @command{tar} Usages
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
address@hidden uuencode
+You can easily use archive files to transport a group of files from
+one system to another: put all relevant files into an archive on one
+computer system, transfer the archive to another system, and extract
+the contents there. The basic transfer medium might be magnetic tape,
+Internet FTP, or even electronic mail (though you must encode the
+archive with @command{uuencode} in order to transport it properly by
+mail). Both machines do not have to use the same operating system, as
+long as they both support the @command{tar} program.
+
+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:
+
address@hidden
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
address@hidden smallexample
+
address@hidden
+You can avoid subshells by using @option{-C} option:
+
address@hidden
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
address@hidden smallexample
+
address@hidden
+The command also works using short option forms:
+
address@hidden
+$ @kbd{(cd sourcedir; tar --create --file=- . ) \
+ | (cd targetdir; tar --extract --file=-)}
+# Or:
+$ @kbd{tar --directory sourcedir --create --file=- . ) \
+ | tar --directory targetdir --extract --file=-}
address@hidden smallexample
+
address@hidden
+This is one of the easiest methods to transfer a @command{tar} archive.
+
address@hidden looking ahead
address@hidden Looking Ahead: The Rest of this Manual
+
+You have now seen how to use all eight of the operations available to
address@hidden, and a number of the possible options. The next chapter
+explains how to choose and change file and archive names, how to use
+files to store names of other files which you can then call as
+arguments to @command{tar} (this can help you save time if you expect to
+archive the same list of files a number of times), and so forth.
address@hidden
address@hidden
+
+
+If there are too many files to conveniently list on the command line,
+you can list the names in a file, and @command{tar} will read that file.
address@hidden
+
+There are various ways of causing @command{tar} to skip over some files,
+and not archive them. @xref{Choosing}.
+
address@hidden Backups
address@hidden Performing Backups and Restoring Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @command{tar} is distributed along with the scripts
+which the Free Software Foundation uses for performing backups. There
+is no corresponding scripts available yet for doing restoration of
+files. Even if there is a good chance those scripts may be satisfying
+to you, they are not the only scripts or methods available for doing
+backups and restore. You may well create your own, or use more
+sophisticated packages dedicated to that purpose.
+
+Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
+This is free software, and it is available at these places:
+
address@hidden
+http://www.cs.umd.edu/projects/amanda/amanda.html
+ftp://ftp.cs.umd.edu/pub/amanda
address@hidden smallexample
+
address@hidden
address@hidden
+
+
+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
+all the files in that file system. Those archives can then be used to
+restore any or all of those files (for instance if a disk crashes or a
+file is accidentally deleted). File system @dfn{backups} are also
+called @dfn{dumps}.
+
address@hidden
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental
Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
address@hidden menu
+
address@hidden Full Dumps
address@hidden Using @command{tar} to Perform Full Dumps
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden full dumps
address@hidden dumps, full
+
address@hidden corrupted archives
+Full dumps should only be made when no other people or programs
+are modifying files in the file system. If files are modified while
address@hidden is making the backup, they may not be stored properly in
+the archive, in which case you won't be able to restore them if you
+have to. (Files not being modified are written with no trouble, and do
+not corrupt the entire archive.)
+
+You will want to use the @address@hidden
+(@option{-V @var{archive-label}}) option to give the archive a
+volume label, so you can tell what this archive is even if the label
+falls off the tape, or anything like that.
+
+Unless the file system you are dumping is guaranteed to fit on
+one volume, you will need to use the @option{--multi-volume} (@option{-M})
option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each file system separately you will need to use
+the @option{--one-file-system} option to prevent
address@hidden from crossing file system boundaries when storing
+(sub)directories.
+
+The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
+option is not needed, since this is a complete copy of everything in
+the file system, and a full restore from this backup would only be
+done onto a completely
+empty disk.
+
+Unless you are in a hurry, and trust the @command{tar} program (and your
+tapes), it is a good idea to use the @option{--verify} (@option{-W})
+option, to make sure your files really made it onto the dump properly.
+This will also detect cases where the file was modified while (or just
+after) it was being archived. Not all media (notably cartridge tapes)
+are capable of being verified, unfortunately.
+
address@hidden Incremental Dumps
address@hidden Using @command{tar} to Perform Incremental Dumps
+
address@hidden backup} is a special form of @acronym{GNU} @command{tar} archive
that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+
address@hidden @command{tar} currently offers two options for handling
incremental
+backups: @address@hidden (@option{-g
address@hidden) and @option{--incremental} (@option{-G}).
+
address@hidden listed-incremental
+The option @option{--listed-incremental} instructs tar to operate on
+an incremental archive with additional metadata stored in a standalone
+file, called a @dfn{snapshot file}. The purpose of this file is to help
+determine which files have been changed, added or deleted since the
+last backup, so that the next incremental backup will contain only
+modified files. The name of the snapshot file is given as an argument
+to the option:
+
address@hidden @option
address@hidden address@hidden
address@hidden -g @var{file}
+ Handle incremental backups with snapshot data in @var{file}.
address@hidden table
+
+To create an incremental backup, you would use
address@hidden together with @option{--create}
+(@pxref{create}). For example:
+
address@hidden
+$ @kbd{tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
address@hidden smallexample
+
+This will create in @file{archive.1.tar} an incremental backup of
+the @file{/usr} file system, storing additional metadata in the file
address@hidden/var/log/usr.snar}. If this file does not exist, it will be
+created. The created archive will then be a @dfn{level 0 backup};
+please see the next section for more on backup levels.
+
+Otherwise, if the file @file{/var/log/usr.snar} exists, it
+determines which files are modified. In this case only these files will be
+stored in the archive. Suppose, for example, that after running the
+above command, you delete file @file{/usr/doc/old} and create
+directory @file{/usr/local/db} with the following contents:
+
address@hidden
+$ @kbd{ls /usr/local/db}
+/usr/local/db/data
+/usr/local/db/index
address@hidden smallexample
+
+Some time later you create another incremental backup. You will
+then see:
+
address@hidden
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+tar: usr/local/db: Directory is new
+usr/local/db/
+usr/local/db/data
+usr/local/db/index
address@hidden smallexample
+
address@hidden
+The created archive @file{archive.2.tar} will contain only these
+three members. This archive is called a @dfn{level 1 backup}. Notice
+that @file{/var/log/usr.snar} will be updated with the new data, so if
+you plan to create more @samp{level 1} backups, it is necessary to
+create a working copy of the snapshot file before running
address@hidden The above example will then be modified as follows:
+
address@hidden
+$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr}
address@hidden smallexample
+
+Incremental dumps depend crucially on time stamps, so the results are
+unreliable if you modify a file's time stamps during dumping (e.g.,
+with the @option{--atime-preserve=replace} option), or if you set the clock
+backwards.
+
+Metadata stored in snapshot files include device numbers, which,
+obviously is supposed to be a non-volatile value. However, it turns
+out that NFS devices have undependable values when an automounter
+gets in the picture. This can lead to a great deal of spurious
+redumping in incremental dumps, so it is somewhat useless to compare
+two NFS devices numbers over time. The solution implemented currently
+is to considers all NFS devices as being equal when it comes to
+comparing directories; this is fairly gross, but there does not seem
+to be a better way to go.
+
+Note that incremental archives use @command{tar} extensions and may
+not be readable by address@hidden versions of the @command{tar} program.
+
address@hidden address@hidden, using with @option{--extract}}
address@hidden address@hidden, using with @option{--listed-incremental}}
+To extract from the incremental dumps, use
address@hidden together with @option{--extract}
+option (@pxref{extracting files}). In this case, @command{tar} does
+not need to access snapshot file, since all the data necessary for
+extraction are stored in the archive itself. So, when extracting, you
+can give whatever argument to @option{--listed-incremental}, the usual
+practice is to use @option{--listed-incremental=/dev/null}.
+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
+option, @pxref{incremental-op}).
+
+When extracting from the incremental backup @acronym{GNU} @command{tar}
attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will @emph{delete} those files in the file
+system that did not exist in their directories when the archive was
+created. If you have created several levels of incremental files,
+then in order to restore the exact contents the file system had when
+the last level was created, you will need to restore from all backups
+in turn. Continuing our example, to restore the state of @file{/usr}
+file system, one would address@hidden, that since both archives
+were created withouth @option{-P} option (@pxref{absolute}), these
+commands should be run from the root file system.}:
+
address@hidden
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar}
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar}
address@hidden smallexample
+
+To list the contents of an incremental archive, use @option{--list}
+(@pxref{list}), as usual. To obtain more information about the
+archive, use @option{--listed-incremental} or @option{--incremental}
+combined with two @option{--verbose} address@hidden
address@hidden options were selected to avoid breaking usual
+verbose listing output (@option{--list --verbose}) when using in
+scripts.
+
address@hidden address@hidden, using with @option{--list}}
address@hidden address@hidden, using with @option{--list}}
address@hidden address@hidden, using with @option{--incremental}}
address@hidden address@hidden, using with @option{--listed-incremental}}
+Versions of @acronym{GNU} @command{tar} up to 1.15.1 used to dump verbatim
binary
+contents of the DUMPDIR header (with terminating nulls) when
address@hidden or @option{--listed-incremental} option was
+given, no matter what the verbosity level. This behavior, and,
+especially, the binary output it produced were considered incovenient
+and were changed in version 1.16}:
+
address@hidden
address@hidden --list --incremental --verbose --verbose archive.tar}
address@hidden smallexample
+
+This command will print, for each directory in the archive, the list
+of files in that directory at the time the archive was created. This
+information is put out in a format which is both human-readable and
+unambiguous for a program: each file name is printed as
+
address@hidden
address@hidden @var{file}
address@hidden smallexample
+
address@hidden
+where @var{x} is a letter describing the status of the file: @samp{Y}
+if the file is present in the archive, @samp{N} if the file is not
+included in the archive, or a @samp{D} if the file is a directory (and
+is included in the archive). @xref{Dumpdir}, for the detailed
+description of dumpdirs and status codes. Each such
+line is terminated by a newline character. The last line is followed
+by an additional newline to indicate the end of the data.
+
address@hidden option @option{--incremental} (@option{-G})
+gives the same behavior as @option{--listed-incremental} when used
+with @option{--list} and @option{--extract} options. When used with
address@hidden option, it creates an incremental archive without
+creating snapshot file. Thus, it is impossible to create several
+levels of incremental backups with @option{--incremental} option.
+
address@hidden Backup Levels
address@hidden Levels of Backups
+
+An archive containing all the files in the file system is called a
address@hidden backup} or @dfn{full dump}. You could insure your data by
+creating a full dump every day. This strategy, however, would waste a
+substantial amount of archive media and user time, as unchanged files
+are daily re-archived.
+
+It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level
+one} dump archives all the files that have changed since the last full
+dump.
+
+A typical dump strategy would be to perform a full dump once a week,
+and a level one dump once a day. This means some versions of files
+will in fact be archived more than once, but this dump strategy makes
+it possible to restore a file system to within one day of accuracy by
+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).
+
address@hidden @command{tar} comes with scripts you can use to do full
+and level-one (actually, even level-two and so on) dumps. Using
+scripts (shell programs) to perform backups and restoration is a
+convenient and reliable alternative to typing out file name lists
+and @command{tar} commands by hand.
+
+Before you use these scripts, you need to edit the file
address@hidden, which specifies parameters used by the backup
+scripts and by the restore script. This file is usually located
+in @file{/etc/backup} directory. @xref{Backup Parameters}, for its
+detailed description. Once the backup parameters are set, you can
+perform backups or restoration by running the appropriate script.
+
+The name of the backup script is @code{backup}. The name of the
+restore script is @code{restore}. The following sections describe
+their use in detail.
+
address@hidden Note:} The backup and restoration scripts are
+designed to be used together. While it is possible to restore files by
+hand from an archive which was created using a backup script, and to create
+an archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. @xref{Incremental Dumps}, before
+making such an attempt.
+
address@hidden Backup Parameters
address@hidden Setting Parameters for Backups and Restoration
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @command{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+Syntactically, @file{backup-specs} is a shell script, containing
+mainly variable assignments. However, any valid shell construct
+is allowed in this file. Particularly, you may wish to define
+functions within that script (e.g., see @code{RESTORE_BEGIN} below).
+For more information about shell script syntax, please refer to
address@hidden://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02, the definition of the Shell Command Language}. See also
address@hidden,,Bash Features,bashref,Bash Reference Manual}.
+
+The shell variables controlling behavior of @code{backup} and
address@hidden are described in the following subsections.
+
address@hidden
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
address@hidden menu
+
address@hidden General-Purpose Variables
address@hidden General-Purpose Variables
+
address@hidden {Backup variable} ADMINISTRATOR
+The user name of the backup administrator. @code{Backup} scripts
+sends a backup report to this address.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the time specification in form @var{hours}:@var{minutes},
+or the string @samp{now}.
+
+This variable is used by @code{backup}. Its value may be overridden
+using @option{--time} option (@pxref{Scripted Backups}).
address@hidden defvr
+
address@hidden {Backup variable} TAPE_FILE
+
+The device @command{tar} writes the archive to. If @var{TAPE_FILE}
+is a remote archive (@pxref{remote-dev}), backup script will suppose
+that your @command{mt} is able to access remote devices. If @var{RSH}
+(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
+invocations of @command{mt}.
address@hidden defvr
+
address@hidden {Backup variable} BLOCKING
+
+The blocking factor @command{tar} will use when writing the dump archive.
address@hidden Factor}.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_DIRS
+
+A list of file systems to be dumped (for @code{backup}), or restored
+(for @code{restore}). You can include any directory
+name in the list --- subdirectories on that file system will be
+included, regardless of how they may look to other networked machines.
+Subdirectories on other file systems will be ignored.
+
+The host name specifies which host to run @command{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have @acronym{GNU} @command{tar} installed, and
+must be able to access the directory containing the backup scripts and
+their support files using the same file name that is used on the
+machine where the scripts are run (i.e. what @command{pwd} will print
+when in that directory on that machine). If the host that contains
+the file system does not have this capability, you can specify another
+host as long as it can access the file system through NFS.
+
+If the list of file systems is very long you may wish to put it
+in a separate file. This file is usually named
address@hidden/etc/backup/dirs}, but this name may be overridden in
address@hidden using @code{DIRLIST} variable.
address@hidden defvr
+
address@hidden {Backup variable} DIRLIST
+
+A path to the file containing the list of the file systems to backup
+or restore. By default it is @file{/etc/backup/dirs}.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_FILES
+
+A list of individual files to be dumped (for @code{backup}), or restored
+(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
+in a separate file. This file is usually named
address@hidden/etc/backup/files}, but this name may be overridden in
address@hidden using @code{FILELIST} variable.
address@hidden defvr
+
address@hidden {Backup variable} FILELIST
+
+A path to the file containing the list of the individual files to backup
+or restore. By default it is @file{/etc/backup/files}.
address@hidden defvr
+
address@hidden {Backup variable} MT
+
+Full file name of @command{mt} binary.
address@hidden defvr
+
address@hidden {Backup variable} RSH
address@hidden
+Full file name of @command{rsh} binary or its equivalent. You may wish to
+set it to @code{ssh}, to improve security. In this case you will have
+to use public key authentication.
address@hidden defvr
+
address@hidden {Backup variable} RSH_COMMAND
+
+Full file name of @command{rsh} binary on remote mashines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @acronym{GNU} @command{tar}.
address@hidden defvr
+
address@hidden {Backup variable} VOLNO_FILE
+
+Name of temporary file to hold volume numbers. This needs to be accessible
+by all the machines which have file systems to be dumped.
address@hidden defvr
+
address@hidden {Backup variable} XLIST
+
+Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
+located on the remote machine and containing the list of files to
+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).
+
+This variable affects only @code{backup}.
address@hidden defvr
+
address@hidden {Backup variable} SLEEP_TIME
+
+Time to sleep between dumps of any two successive file systems
+
+This variable affects only @code{backup}.
address@hidden defvr
+
address@hidden {Backup variable} DUMP_REMIND_SCRIPT
+
+Script to be run when it's time to insert a new tape in for the next
+volume. Administrators may want to tailor this script for their site.
+If this variable isn't set, @acronym{GNU} @command{tar} will display its
built-in
+prompt, and will expect confirmation from the console. For the
+description of the default prompt, see @ref{change volume prompt}.
+
address@hidden defvr
+
address@hidden {Backup variable} SLEEP_MESSAGE
+
+Message to display on the terminal while waiting for dump time. Usually
+this will just be some literal text.
address@hidden defvr
+
address@hidden {Backup variable} TAR
+
+Full file name of the @acronym{GNU} @command{tar} executable. If this is not
set, backup
+scripts will search @command{tar} in the current shell path.
address@hidden defvr
+
address@hidden Magnetic Tape Control
address@hidden Magnetic Tape Control
+
+Backup scripts access tape device using special @dfn{hook functions}.
+These functions take a single argument -- the name of the tape
+device. Their names are kept in the following variables:
+
address@hidden {Backup variable} MT_BEGIN
+The name of @dfn{begin} function. This function is called before
+accessing the drive. By default it retensions the tape:
+
address@hidden
+MT_BEGIN=mt_begin
+
+mt_begin() @{
+ mt -f "$1" retension
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden {Backup variable} MT_REWIND
+The name of @dfn{rewind} function. The default definition is as
+follows:
+
address@hidden
+MT_REWIND=mt_rewind
+
+mt_rewind() @{
+ mt -f "$1" rewind
address@hidden
address@hidden smallexample
+
address@hidden defvr
+
address@hidden {Backup variable} MT_OFFLINE
+The name of the function switching the tape off line. By default
+it is defined as follows:
+
address@hidden
+MT_OFFLINE=mt_offline
+
+mt_offline() @{
+ mt -f "$1" offl
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden {Backup variable} MT_STATUS
+The name of the function used to obtain the status of the archive device,
+including error count. Default definition:
+
address@hidden
+MT_STATUS=mt_status
+
+mt_status() @{
+ mt -f "$1" status
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden User Hooks
address@hidden User Hooks
+
address@hidden hooks} are shell functions executed before and after
+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:
+
address@hidden {User Hook Function} hook @var{level} @var{host} @var{fs}
@var{fsname}
+Its arguments are:
+
address@hidden @var
address@hidden level
+Current backup or restore level.
+
address@hidden host
+Name or IP address of the host machine being dumped or restored.
+
address@hidden fs
+Full path name to the file system being dumped or restored.
+
address@hidden fsname
+File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
address@hidden table
address@hidden deffn
+
+Following variables keep the names of user hook functions
+
address@hidden {Backup variable} DUMP_BEGIN
+Dump begin function. It is executed before dumping the file system.
address@hidden defvr
+
address@hidden {Backup variable} DUMP_END
+Executed after dumping the file system.
address@hidden defvr
+
address@hidden {Backup variable} RESTORE_BEGIN
+Executed before restoring the file system.
address@hidden defvr
+
address@hidden {Backup variable} RESTORE_END
+Executed after restoring the file system.
address@hidden defvr
+
address@hidden backup-specs example
address@hidden An Example Text of @file{Backup-specs}
+
+The following is an example of @file{backup-specs}:
+
address@hidden
+# site-specific parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+
+# Use @code{ssh} instead of the less secure @code{rsh}
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
+
+# Override MT_STATUS function:
+my_status() @{
+ mts -t $TAPE_FILE
address@hidden
+MT_STATUS=my_status
+
+# Disable MT_OFFLINE function
+MT_OFFLINE=:
+
+BLOCKING=124
+BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
+
+BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+
address@hidden smallexample
+
address@hidden Scripted Backups
address@hidden Using the Backup Scripts
+
+The syntax for running a backup script is:
+
address@hidden
+backup address@hidden address@hidden
address@hidden smallexample
+
+The @option{level} option requests the dump level. Thus, to produce
+a full dump, specify @code{--level=0} (this is the default, so
address@hidden may be omitted if its value is @code{0}).
address@hidden backward compatibility, the @code{backup} will also
+try to deduce the requested dump level from the name of the
+script itself. If the name consists of a string @samp{level-}
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from @code{backup}
+to @code{level-1} and then run @code{level-1} whenever you need to
+create a level one dump.}
+
+The @option{--time} option determines when should the backup be
+run. @var{Time} may take three forms:
+
address@hidden @asis
address@hidden @var{hh}:@var{mm}
+
+The dump must be run at @var{hh} hours @var{mm} minutes.
+
address@hidden @var{hh}
+
+The dump must be run at @var{hh} hours
+
address@hidden now
+
+The dump must be run immediately.
address@hidden table
+
+You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it
+needs them. Media volumes don't have to correspond to archive
+files --- a multi-volume archive can be started in the middle of a
+tape that already contains the end of another multi-volume archive.
+The @code{restore} script prompts for media by its archive volume,
+so to avoid an error message you should keep track of which tape
+(or disk) contains which volume of the archive (@pxref{Scripted
+Restoration}).
+
+The backup scripts write two files on the file system. The first is a
+record file in @file{/etc/tar-backup/}, which is used by the scripts
+to store and retrieve information about which files were dumped. This
+file is not meant to be read by humans, and should not be deleted by
+them. @xref{Snapshot Files}, for a more detailed explanation of this
+file.
+
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+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
address@hidden@address@hidden, 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.
+
+Following is the full list of options accepted by @code{backup}
+script:
+
address@hidden @option
address@hidden -l @var{level}
address@hidden address@hidden
+Do backup level @var{level} (default 0).
+
address@hidden -f
address@hidden --force
+Force backup even if today's log file already exists.
+
address@hidden address@hidden
address@hidden address@hidden
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
address@hidden -t @var{start-time}
address@hidden address@hidden
+Wait till @var{time}, then do backup.
+
address@hidden -h
address@hidden --help
+Display short help message and exit.
+
address@hidden -V
address@hidden --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden table
+
+
address@hidden Scripted Restoration
address@hidden Using the Restore Script
+
+To restore files that were archived using a scripted backup, use the
address@hidden script. Its usage is quite straightforward. In the
+simplest form, invoke @code{restore --all}, it will
+then restore all the file systems and files specified in
address@hidden (@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
+line. For example, running
+
address@hidden
+restore 'albert:*'
address@hidden smallexample
+
address@hidden
+will restore all file systems on the machine @samp{albert}. A more
+complicated example:
+
address@hidden
+restore 'albert:*' '*:/var'
address@hidden smallexample
+
address@hidden
+This command will restore all file systems on the machine @samp{albert}
+as well as @file{/var} file system on all machines.
+
+By default @code{restore} will start restoring files from the lowest
+available dump level (usually zero) and will continue through
+all available dump levels. There may be situations where such a
+thorough restore is not necessary. For example, you may wish to
+restore only files from the recent level one backup. To do so,
+use @option{--level} option, as shown in the example below:
+
address@hidden
+restore --level=1
address@hidden smallexample
+
+The full list of options accepted by @code{restore} follows:
+
address@hidden @option
address@hidden -a
address@hidden --all
+Restore all file systems and files specified in @file{backup-specs}
+
address@hidden -l @var{level}
address@hidden address@hidden
+Start restoring from the given backup level, instead of the default 0.
+
address@hidden address@hidden
address@hidden address@hidden
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
address@hidden -h
address@hidden --help
+Display short help message and exit.
+
address@hidden -V
address@hidden --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden table
+
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @xref{Tape Positioning}, for a discussion of tape
+positioning.
+
address@hidden
address@hidden:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
address@hidden quotation
+
address@hidden Dumps}, for an explanation of how the script makes
+that determination.
+
address@hidden Choosing
address@hidden Choosing Files and Names for @command{tar}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Certain options to @command{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.
+
+This chapter discusses these options in detail.
+
address@hidden
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
address@hidden menu
+
address@hidden file
address@hidden Choosing and Naming Archive Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Naming an archive
address@hidden Archive Name
address@hidden Choosing an archive file
address@hidden Where is the archive?
+By default, @command{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @command{tar}
+on the system may not have set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
address@hidden where to find (or create) the archive. The
address@hidden@var{archive-name}} (@option{-f @var{archive-name}})
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
address@hidden @option
address@hidden address@hidden, short description}
address@hidden address@hidden
address@hidden -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
address@hidden table
+
+For example, in this @command{tar} command,
+
address@hidden
+$ @kbd{tar -cvf collection.tar blues folk jazz}
address@hidden smallexample
+
address@hidden
address@hidden is the name of the archive. It must directly
+follow the @option{-f} option, since whatever directly follows @option{-f}
address@hidden end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @command{tar} will use this file's name
+for the archive name.
+
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
address@hidden Writing new archives
address@hidden Archive creation
+If you do not name the archive, @command{tar} uses the value of the
+environment variable @env{TAPE} as the file name for the archive. If
+that is not available, @command{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (i.e. @file{/dev/tu00}).
+
address@hidden Standard input and output
address@hidden tar to standard input and output
+If you use @file{-} as an @var{archive-name}, @command{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
address@hidden as an @var{archive-name} when modifying an archive,
address@hidden reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+
+The following example is a convenient way of copying directory
+hierarchy from @file{sourcedir} to @file{targetdir}.
+
address@hidden
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
address@hidden smallexample
+
+The @option{-C} option allows to avoid using subshells:
+
address@hidden
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
address@hidden smallexample
+
+In both examples above, the leftmost @command{tar} invocation archives
+the contents of @file{sourcedir} to the standard output, while the
+rightmost one reads this archive from its standard input and
+extracts it. The @option{-p} option tells it to restore permissions
+of the extracted files.
+
address@hidden Remote devices
address@hidden tar to a remote device
address@hidden
+To specify an archive file on a device attached to a remote machine,
+use the following:
+
address@hidden
address@hidden@var{hostname}:/@var{dev}/@var{file-name}}
address@hidden smallexample
+
address@hidden
address@hidden will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
address@hidden@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
+
address@hidden Local and remote archives
address@hidden and remote archives}
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
address@hidden@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @command{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @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
+the @acronym{GNU} @command{tar} distribution and by default is installed under
address@hidden@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 @option{--force-local} option.
+
+When the archive is being created to @file{/dev/null}, @acronym{GNU}
@command{tar}
+tries to minimize input and output operations. The Amanda backup
+system, when used with @acronym{GNU} @command{tar}, has an initial sizing pass
which
+uses this feature.
+
address@hidden Selecting Archive Members
address@hidden Selecting Archive Members
address@hidden Specifying files to act on
address@hidden Specifying archive members
+
address@hidden Name arguments} specify which files in the file system
address@hidden operates on, when creating or adding to an archive, or which
+archive members @command{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
+
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
address@hidden
address@hidden @var{operation} address@hidden @var{option2} @dots{}]
address@hidden name-1} @var{file name-2} @dots{}]
address@hidden smallexample
+
+If a file name begins with dash (@samp{-}), precede it with
address@hidden option to prevent it from being treated as an
+option.
+
address@hidden name quoting}
+By default @acronym{GNU} @command{tar} attempts to @dfn{unquote} each file or
member
+name, replacing @dfn{escape sequences} according to the following
+table:
+
address@hidden @columnfractions 0.20 0.60
address@hidden Escape @tab Replaced with
address@hidden \a @tab Audible bell (ASCII 7)
address@hidden \b @tab Backspace (ASCII 8)
address@hidden \f @tab Form feed (ASCII 12)
address@hidden \n @tab New line (ASCII 10)
address@hidden \r @tab Carriage return (ASCII 13)
address@hidden \t @tab Horizontal tabulation (ASCII 9)
address@hidden \v @tab Vertical tabulation (ASCII 11)
address@hidden \? @tab ASCII 127
address@hidden address@hidden @tab ASCII @var{n} (@var{n} should be an octal
number
+ of up to 3 digits)
address@hidden multitable
+
+A backslash followed by any other symbol is retained.
+
+This default behavior is controlled by the following command line
+option:
+
address@hidden @option
address@hidden unquote
address@hidden --unquote
+Enable unquoting input file or member names (default).
+
address@hidden no-unquote
address@hidden --no-unquote
+Disable unquoting input file or member names.
address@hidden table
+
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @command{tar}.
+
+If you do not specify files, @command{tar} behavior differs depending
+on the operation mode as described below:
+
+When @command{tar} is invoked with @option{--create} (@option{-c}),
address@hidden will stop immediately, reporting the following:
+
address@hidden
address@hidden
+$ @kbd{tar cf a.tar}
+tar: Cowardly refusing to create an empty archive
+Try `tar --help' or `tar --usage' for more information.
address@hidden group
address@hidden smallexample
+
+If you specify either @option{--list} (@option{-t}) or
address@hidden (@option{--get}, @option{-x}), @command{tar}
+operates on all the archive members in the archive.
+
+If run with @option{--diff} option, tar will compare the archive with
+the contents of the current working directory.
+
+If you specify any other operation, @command{tar} does nothing.
+
+By default, @command{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @command{tar} selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
+
address@hidden files
address@hidden Reading Names from a File
+
address@hidden Reading file names from a file
address@hidden Lists of file names
address@hidden File Name arguments, alternatives
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
address@hidden@var{file-of-names}} (@option{-T
address@hidden) option to @command{tar}. Give the name of the
+file which contains the list of files to include as the argument to
address@hidden In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @command{find} utility.
+
address@hidden @option
address@hidden files-from
address@hidden address@hidden
address@hidden -T @var{file-name}
+Get names to extract or create from file @var{file-name}.
address@hidden table
+
+If you give a single dash as a file name for @option{--files-from}, (i.e.,
+you specify either @code{--files-from=-} or @code{-T -}), then the file
+names are read from standard input.
+
+Unless you are running @command{tar} with @option{--create}, you can not use
+both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
+command.
+
+Any number of @option{-T} options can be given in the command line.
+
+The following example shows how to use @command{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @option{-T} option to
address@hidden to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @option{-z} option to
address@hidden compresses the archive with @command{gzip}; @pxref{gzip} for
+more information.)
+
address@hidden
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
address@hidden smallexample
+
address@hidden
+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 address@hidden of @acronym{GNU} @command{tar} up to 1.15.1
+recognized only @option{-C} option in file lists, and only if the
+option and its argument occupied two consecutive lines.} For example,
+the common use of this feature is to change to another directory by
+specifying @option{-C} option:
+
address@hidden
address@hidden
+$ @kbd{cat list}
+-C/etc
+passwd
+hosts
+-C/lib
+libc.a
+$ @kbd{tar -c -f foo.tar --files-from list}
address@hidden group
address@hidden smallexample
+
address@hidden
+In this example, @command{tar} will first switch to @file{/etc}
+directory and add files @file{passwd} and @file{hosts} to the
+archive. Then it will change to @file{/lib} directory and will archive
+the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will
+contain:
+
address@hidden
address@hidden
+$ @kbd{tar tf foo.tar}
+passwd
+hosts
+libc.a
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden address@hidden, using in @option{--files-from} argument}
+Notice that the option parsing algorithm used with @option{-T} is
+stricter than the one used by shell. Namely, when specifying option
+arguments, you should observe the following rules:
+
address@hidden @bullet
address@hidden
+When using short (single-letter) option form, its argument must
+immediately follow the option letter, without any intervening
+whitespace. For example: @code{-Cdir}.
+
address@hidden
+When using long option form, the option argument must be separated
+from the option by a single equal sign. No whitespace is allowed on
+any side of the equal sign. For example: @code{--directory=dir}.
+
address@hidden
+For both short and long option forms, the option argument can be given
+on the next line after the option name, e.g.:
+
address@hidden
address@hidden
+--directory
+dir
address@hidden group
address@hidden smallexample
+
address@hidden
+and
+
address@hidden
address@hidden
+-C
+dir
address@hidden group
address@hidden smallexample
address@hidden itemize
+
address@hidden add-file
+If you happen to have a file whose name starts with @samp{-},
+precede it with @option{--add-file} option to prevent it from
+being recognized as an option. For example: @code{--add-file=--my-file}.
+
address@hidden
+* nul::
address@hidden menu
+
address@hidden nul
address@hidden @code{NUL} Terminated File Names
+
address@hidden File names, terminated by @code{NUL}
address@hidden @code{NUL} terminated file names
+The @option{--null} option causes
address@hidden@var{file-of-names}} (@option{-T @var{file-of-names}})
+to read file names terminated by a @code{NUL} instead of a newline, so
+files whose names contain newlines can be archived using
address@hidden
+
address@hidden @option
address@hidden null
address@hidden --null
+Only consider @code{NUL} terminated file names, instead of files that
+terminate in a newline.
address@hidden table
+
+The @option{--null} option is just like the one in @acronym{GNU}
address@hidden and @command{cpio}, and is useful with the
address@hidden predicate of @acronym{GNU} @command{find}. In
address@hidden, @option{--null} also disables special handling for
+file names that begin with dash.
+
+This example shows how to use @command{find} to generate a list of files
+larger than 800K in length and put that list into a file called
address@hidden 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
address@hidden and @option{-T} options to specify that @command{tar} get the
+files from that file, @file{long-files}, to create the archive
address@hidden The @option{--null} option to @command{tar} will cause
address@hidden to recognize the @code{NUL} separator between files.
+
address@hidden
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
address@hidden smallexample
+
address@hidden
address@hidden
+
+
address@hidden exclude
address@hidden Excluding Some Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden File names, excluding files by
address@hidden Excluding files by name and pattern
address@hidden Excluding files by file system
+To avoid operating on files whose names match a particular pattern,
+use the @option{--exclude} or @option{--exclude-from} options.
+
address@hidden @option
address@hidden exclude
address@hidden address@hidden
+Causes @command{tar} to ignore files that match the @var{pattern}.
address@hidden table
+
address@hidden exclude
+The @address@hidden option prevents any file or
+member whose name matches the shell wildcard (@var{pattern}) from
+being operated on.
+For example, to create an archive with all the contents of the directory
address@hidden except for files whose names end in @file{.o}, use the
+command @samp{tar -cf src.tar --exclude='*.o' src}.
+
+You may give multiple @option{--exclude} options.
+
address@hidden @option
address@hidden exclude-from
address@hidden address@hidden
address@hidden -X @var{file}
+Causes @command{tar} to ignore files that match the patterns listed in
address@hidden
address@hidden table
+
address@hidden exclude-from
+Use the @option{--exclude-from} option to read a
+list of patterns, one per line, from @var{file}; @command{tar} will
+ignore files matching those patterns. Thus if @command{tar} is
+called as @address@hidden -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
+
address@hidden @option
address@hidden exclude-caches
address@hidden --exclude-caches
+Causes @command{tar} to ignore directories containing a cache directory tag.
address@hidden table
+
address@hidden exclude-caches
+When creating an archive, the @option{--exclude-caches} option causes
address@hidden to exclude all directories that contain a @dfn{cache
+directory tag}. A cache directory tag is a short file with the
+well-known name @file{CACHEDIR.TAG} and having a standard header
+specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
+Various applications write cache directory tags into directories they
+use to hold regenerable, non-precious data, so that such data can be
+more easily excluded from backups.
+
address@hidden
+* problems with exclude::
address@hidden menu
+
address@hidden problems with exclude
address@hidden Problems with Using the @code{exclude} Options
+
address@hidden address@hidden, potential problems with}
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
+
address@hidden @bullet
address@hidden
+The main operating mode of @command{tar} does not act on a path name
+explicitly listed on the command line if one of its file name
+components is excluded. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{dir.o/foo} after all the options have been
+listed, @samp{dir.o/foo} will be excluded from the archive.
+
address@hidden
+You can sometimes confuse the meanings of @option{--exclude} and
address@hidden Be careful: use @option{--exclude} when files
+to be excluded are given as a pattern on the command line. Use
address@hidden to introduce the name of a file which contains
+a list of patterns, one per line; each of these patterns can exclude
+zero, one, or many files.
+
address@hidden
+When you use @address@hidden, be sure to quote the
address@hidden parameter, so @acronym{GNU} @command{tar} sees wildcard
characters
+like @samp{*}. If you do not do this, the shell might expand the
address@hidden itself using files at hand, so @command{tar} might receive a
+list of files instead of one pattern, or none at all, making the
+command somewhat illegal. This might not correspond to what you want.
+
+For example, write:
+
address@hidden
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
address@hidden smallexample
+
address@hidden
+rather than:
+
address@hidden
+# @emph{Wrong!}
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
address@hidden smallexample
+
address@hidden
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @command{tar}. If you try to use
address@hidden syntax to describe files to be excluded, your command
+might fail.
+
address@hidden
address@hidden
address@hidden
+
+In earlier versions of @command{tar}, what is now the
address@hidden option was called @option{--exclude} instead.
+Now, @option{--exclude} applies to patterns listed on the command
+line and @option{--exclude-from} applies to patterns listed in a
+file.
+
address@hidden itemize
+
address@hidden wildcards
address@hidden Wildcards Patterns and Matching
+
address@hidden is the operation by which @dfn{wildcard} characters,
address@hidden or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. @acronym{GNU} @command{tar} can
use wildcard
+patterns for matching (or globbing) archive members when extracting
+from or listing an archive. Wildcard patterns are also used for
+verifying volume labels of @command{tar} archives. This section has the
+purpose of explaining wildcard syntax for @command{tar}.
+
address@hidden
address@hidden
+
+
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
address@hidden in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
address@hidden would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
address@hidden would match any of the characters, @samp{-}, @samp{\},
address@hidden, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
address@hidden in a character class.)
+
address@hidden Excluding characters from a character class
address@hidden Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
+
+Other characters of the class stand for themselves. The special
+construction @address@hidden@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
address@hidden, inclusive.
+
address@hidden
address@hidden
+
+
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: thus, excluding a directory also excludes all the files beneath it.
+
address@hidden
+* controlling pattern-matching::
address@hidden menu
+
address@hidden controlling pattern-matching
address@hidden Controlling Pattern-Matching
+
+For the purposes of this section, we call @dfn{exclusion members} all
+member names obtained while processing @option{--exclude} and
address@hidden options, and @dfn{inclusion members} those
+member names that were given in the command line or read from the file
+specified with @option{--files-from} option.
+
+These two pairs of member lists are used in the following operations:
address@hidden, @option{--extract}, @option{--list},
address@hidden
+
+There are no inclusion members in create mode (@option{--create} and
address@hidden), since in this mode the names obtained from the
+command line refer to @emph{files}, not archive members.
+
+By default, inclusion members are compared with archive members
+literally @footnote{Notice that earlier @acronym{GNU} @command{tar} versions
used
+globbing for inclusion members, which contradicted to UNIX98
+specification and was not documented. @xref{Changes}, for more
+information on this and other changes.} and exclusion members are
+treated as globbing patterns. For example:
+
address@hidden
address@hidden
+$ @kbd{tar tf foo.tar}
+a.c
+b.c
+a.txt
+[remarks]
+# @i{Member names are used verbatim:}
+$ @kbd{tar -xf foo.tar -v '[remarks]'}
+[remarks]
+# @i{Exclude member names are globbed:}
+$ @kbd{tar -xf foo.tar -v --exclude '*.c'}
+a.txt
+[remarks]
address@hidden group
address@hidden smallexample
+
+This behavior can be altered by using the following options:
+
address@hidden @option
address@hidden wildcards
address@hidden --wildcards
+Treat all member names as wildcards.
+
address@hidden no-wildcards
address@hidden --no-wildcards
+Treat all member names as literal strings.
address@hidden table
+
+Thus, to extract files whose names end in @samp{.c}, you can use:
+
address@hidden
+$ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
+a.c
+b.c
address@hidden smallexample
+
address@hidden
+Notice quoting of the pattern to prevent the shell from interpreting
+it.
+
+The effect of @option{--wildcards} option is cancelled by
address@hidden This can be used to pass part of
+the command line arguments verbatim and other part as globbing
+patterns. For example, the following invocation:
+
address@hidden
+$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
address@hidden smallexample
+
address@hidden
+instructs @command{tar} to extract from @file{foo.tar} all files whose
+names end in @samp{.txt} and the file named @file{[remarks]}.
+
+Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where @samp{*}, @samp{?}, and
address@hidden are the usual shell wildcards, @samp{\} escapes wildcards,
+and wildcards can match @samp{/}.
+
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and names are used as-is. For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
+
+However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+
address@hidden
+--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
address@hidden smallexample
+
address@hidden
+ignores case when excluding @samp{makefile}, but not when excluding
address@hidden
+
address@hidden @option
address@hidden anchored
address@hidden no-anchored
address@hidden --anchored
address@hidden --no-anchored
+If anchored, a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any
+subsequence. Default is @option{--no-anchored} for exclusion members
+and @option{--anchored} inclusion members.
+
address@hidden ignore-case
address@hidden no-ignore-case
address@hidden --ignore-case
address@hidden --no-ignore-case
+When ignoring case, upper-case patterns match lower-case names and vice versa.
+When not ignoring case (the default), matching is case-sensitive.
+
address@hidden wildcards-match-slash
address@hidden no-wildcards-match-slash
address@hidden --wildcards-match-slash
address@hidden --no-wildcards-match-slash
+When wildcards match slash (the default for exclusion members), a
+wildcard like @samp{*} in the pattern can match a @samp{/} in the
+name. Otherwise, @samp{/} is matched only by @samp{/}.
+
address@hidden table
+
+The @option{--recursion} and @option{--no-recursion} options
+(@pxref{recurse}) also affect how member patterns are interpreted. If
+recursion is in effect, a pattern matches a name if it matches any of
+the name's parent directories.
+
+The following table summarizes pattern-matching default values:
+
address@hidden @columnfractions .3 .7
address@hidden Members @tab Default settings
address@hidden Inclusion @tab @option{--no-wildcards --anchored
--no-wildcards-match-slash}
address@hidden Exclusion @tab @option{--wildcards --no-anchored
--wildcards-match-slash}
address@hidden multitable
+
address@hidden quoting styles
address@hidden Quoting Member Names
+
+When displaying member names, @command{tar} takes care to avoid
+ambiguities caused by certain characters. This is called @dfn{name
+quoting}. The characters in question are:
+
address@hidden @bullet
address@hidden Non-printable control characters:
+
address@hidden @columnfractions 0.20 0.10 0.60
address@hidden Character @tab ASCII @tab Character name
address@hidden \a @tab 7 @tab Audible bell
address@hidden \b @tab 8 @tab Backspace
address@hidden \f @tab 12 @tab Form feed
address@hidden \n @tab 10 @tab New line
address@hidden \r @tab 13 @tab Carriage return
address@hidden \t @tab 9 @tab Horizontal tabulation
address@hidden \v @tab 11 @tab Vertical tabulation
address@hidden multitable
+
address@hidden Space (ASCII 32)
+
address@hidden Single and double quotes (@samp{'} and @samp{"})
+
address@hidden Backslash (@samp{\})
address@hidden itemize
+
+The exact way @command{tar} uses to quote these characters depends on
+the @dfn{quoting style}. The default quoting style, called
address@hidden (see below), uses backslash notation to represent control
+characters, space and backslash. Using this quoting style, control
+characters are represented as listed in column @samp{Character} in the
+above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
+
address@hidden @command{tar} offers seven distinct quoting styles, which can be
selected
+using @option{--quoting-style} option:
+
address@hidden @option
address@hidden address@hidden
address@hidden quoting-style
+
+Sets quoting style. Valid values for @var{style} argument are:
+literal, shell, shell-always, c, escape, locale, clocale.
address@hidden table
+
+These styles are described in detail below. To illustrate their
+effect, we will use an imaginary tar archive @file{arch.tar}
+containing the following members:
+
address@hidden
address@hidden
+# 1. Contains horizontal tabulation character.
+a tab
+# 2. Contains newline character
+a
+newline
+# 3. Contains a space
+a space
+# 4. Contains double quotes
+a"double"quote
+# 5. Contains single quotes
+a'single'quote
+# 6. Contains a backslash character:
+a\backslash
address@hidden group
address@hidden smallexample
+
+Here is how usual @command{ls} command would have listed them, if they
+had existed in the current working directory:
+
address@hidden
address@hidden
+$ @kbd{ls}
+a\ttab
+a\nnewline
+a\ space
+a"double"quote
+a'single'quote
+a\\backslash
address@hidden group
address@hidden smallexample
+
+Quoting styles:
+
address@hidden @samp
address@hidden literal
+No quoting, display each character as is:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=literal}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\backslash
+./a tab
+./a
+newline
address@hidden group
address@hidden smallexample
+
address@hidden shell
+Display characters the same way Bourne shell does:
+control characters, except @samp{\t} and @samp{\n}, are printed using
+backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
+single quote is printed as @samp{\'}. If a name contains any quoted
+characters, it is enclosed in single quotes. In particular, if a name
+contains single quotes, it is printed as several single-quoted strings:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=shell}
+./
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
address@hidden group
address@hidden smallexample
+
address@hidden shell-always
+Same as @samp{shell}, but the names are always enclosed in single
+quotes:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=shell-always}
+'./'
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
address@hidden group
address@hidden smallexample
+
address@hidden c
+Use the notation of the C programming language. All names are
+enclosed in double quotes. Control characters are quoted using
+backslash notations, double quotes are represented as @samp{\"},
+backslash characters are represented as @samp{\\}. Single quotes and
+spaces are not quoted:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=c}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
address@hidden group
address@hidden smallexample
+
address@hidden escape
+Control characters are printed using backslash notation, a space is
+printed as @samp{\ } and a backslash as @samp{\\}. This is the
+default quoting style, unless it was changed when configured the
+package.
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=escape}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
address@hidden group
address@hidden smallexample
+
address@hidden locale
+Control characters, single quote and backslash are printed using
+backslash notation. All names are quoted using left and right
+quotation marks, appropriate to the current locale. If it does not
+define quotation marks, use @samp{`} as left and @samp{'} as right
+quotation marks. Any occurrences of the right quotation mark in a
+name are escaped with @samp{\}, for example:
+
+For example:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=locale}
+`./'
+`./a space'
+`./a\'single\'quote'
+`./a"double"quote'
+`./a\\backslash'
+`./a\ttab'
+`./a\nnewline'
address@hidden group
address@hidden smallexample
+
address@hidden clocale
+Same as @samp{locale}, but @samp{"} is used for both left and right
+quotation marks, if not provided by the currently selected locale:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=clocale}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
address@hidden group
address@hidden smallexample
address@hidden table
+
+You can specify which characters should be quoted in addition to those
+implied by the current quoting style:
+
address@hidden @option
address@hidden address@hidden
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them.
address@hidden table
+
+For example, using @samp{escape} quoting (compare with the usual
+escape listing above):
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
+./
+./a\ space
+./a'single'quote
+./a\"double\"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
address@hidden group
address@hidden smallexample
+
+To disable quoting of such additional characters, use the following
+option:
+
address@hidden @option
address@hidden address@hidden
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option.
address@hidden table
+
+This option is particularly useful if you have added
address@hidden to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
+and wish to disable it for the current invocation.
+
+Note, that @option{--no-quote-chars} does @emph{not} disable those
+characters that are quoted by default in the selected quoting style.
+
address@hidden transform
address@hidden Modifying File and Member Names
+
address@hidden archives contain detailed information about files stored
+in them and full file names are part of that information. When
+storing file to an archive, its file name is recorded in the archive
+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
+of a file archiver. However, there are some cases when it is not.
+
+First of all, it is often unsafe to extract archive members with
+absolute file names or those that begin with a @file{../}. @acronym{GNU}
@command{tar}
+takes special precautions when extracting such names and provides a
+special option for handling them, which is described in
address@hidden
+
+Secondly, you may wish to extract file names without some leading
+directory components, or with otherwise modified names. In other
+cases it is desirable to store files under differing names in the
+archive.
+
address@hidden @command{tar} provides two options for these needs.
+
address@hidden @option
address@hidden strip-components
address@hidden address@hidden
+Strip given @var{number} of leading components from file names before
+extraction.
address@hidden table
+
+For example, suppose you have archived whole @file{/usr} hierarchy to
+a tar archive named @file{usr.tar}. Among other files, this archive
+contains @file{usr/include/stdlib.h}, which you wish to extract to
+the current working directory. To do so, you type:
+
address@hidden
+$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h}
address@hidden smallexample
+
+The option @option{--strip=2} instructs @command{tar} to strip the
+two leading components (@file{usr/} and @file{include/}) off the file
+name.
+
+If you add to the above invocation @option{--verbose} (@option{-v})
+option, you will note that the verbose listing still contains the
+full file name, with the two removed components still in place. This
+can be inconvenient, so @command{tar} provides a special option for
+altering this behavior:
+
address@hidden
address@hidden @option
address@hidden show-transformed-names
address@hidden --show-transformed-names
+Display file or member names with all requested transformations
+applied.
address@hidden table
+
address@hidden
+For example:
+
address@hidden
address@hidden
+$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h}
+usr/include/stdlib.h
+$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h}
+stdlib.h
address@hidden group
address@hidden smallexample
+
+Notice that in both cases the file is @file{stdlib.h} extracted to the
+current working directory, @option{--show-transformed-names} affects
+only the way its name is displayed.
+
+This option is especially useful for verifying whether the invocation
+will have the desired effect. Thus, before running
+
address@hidden
+$ @kbd{tar -x address@hidden
address@hidden smallexample
+
address@hidden
+it is often advisable to run
+
address@hidden
+$ @kbd{tar -t -v --show-transformed address@hidden
address@hidden smallexample
+
address@hidden
+to make sure the command will produce the intended results.
+
+In case you need to apply more complex modifications to the file name,
address@hidden @command{tar} provides a general-purpose transformation option:
+
address@hidden @option
address@hidden transform
address@hidden address@hidden
+Modify file names using supplied @var{expression}.
address@hidden table
+
address@hidden
+The @var{expression} is a @command{sed}-like replace expression of the
+form:
+
address@hidden
+s/@var{regexp}/@var{replace}/address@hidden
address@hidden smallexample
+
address@hidden
+where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
+replacement for each file name part that matches @var{regexp}. Both
address@hidden and @var{replace} are described in detail in
address@hidden "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
+
+Supported @var{flags} are:
+
address@hidden @samp
address@hidden g
+Apply the replacement to @emph{all} matches to the @var{regexp}, not
+just the first.
+
address@hidden i
+Use case-insensitive matching
+
address@hidden x
address@hidden is an @dfn{extended regular expression} (@pxref{Extended
+regexps, Extended regular expressions, Extended regular expressions,
+sed, GNU sed}).
+
address@hidden @var{number}
+Only replace the @var{number}th match of the @var{regexp}.
+
+Note: the @var{posix} standard does not specify what should happen
+when you mix the @samp{g} and @var{number} modifiers. @acronym{GNU}
@command{tar}
+follows the GNU @command{sed} implementation in this regard, so
+the the interaction is defined to be: ignore matches before the
address@hidden, and then match and replace all matches from the
address@hidden on.
+
address@hidden table
+
+Any delimiter can be used in lieue of @samp{/}, the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
address@hidden
address@hidden
+s/one/two/
+s,one,two,
address@hidden group
address@hidden smallexample
+
+Changing delimiters is often useful when the @var{regex} contains
+slashes. For example, it is more convenient to write @code{s,/,-,} than
address@hidden/\//-/}.
+
+Here are several examples of @option{--transform} usage:
+
address@hidden
address@hidden Extract @file{usr/} hierarchy into @file{usr/local/}:
+
address@hidden
+$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Strip two leading directory components (equivalent to
address@hidden):
+
address@hidden
+$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Prepend @file{/prefix/} to each file name:
+
address@hidden
+$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Convert each file name to lower case:
+
address@hidden
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
address@hidden smallexample
+
address@hidden enumerate
+
+Unlike @option{--strip-components}, @option{--transform} can be used
+in any @acronym{GNU} @command{tar} operation mode. For example, the following
command
+adds files to the archive while replacing the leading @file{usr/}
+component with @file{var/}:
+
address@hidden
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /}
address@hidden smallexample
+
+To test @option{--transform} effect we suggest using
address@hidden option:
+
address@hidden
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
+ --verbose --show-transformed-names /}
address@hidden smallexample
+
+If both @option{--strip-components} and @option{--transform} are used
+together, then @option{--transform} is applied first, and the required
+number of components is then stripped from its result.
+
address@hidden after
address@hidden Operating Only on New Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Excluding file by age
address@hidden Data Modification time, excluding files by
address@hidden Modification time, excluding files by
address@hidden Age, excluding files by
+The @address@hidden (@address@hidden,
address@hidden @var{date}}) option causes @command{tar} to only work on
+files whose data modification or status change times are newer than
+the @var{date} given. If @var{date} starts with @samp{/} or @samp{.},
+it is taken to be a file name; the data modification time of that file
+is used as the date. If you use this option when creating or appending
+to an archive, the archive will only include new files. If you use
address@hidden when extracting an archive, @command{tar} will
+only extract files newer than the @var{date} you specify.
+
+If you only want @command{tar} to make the date comparison based on
+modification of the file's data (rather than status
+changes), then use the @address@hidden option.
+
+You may use these options with any operation. Note that these options
+differ from the @option{--update} (@option{-u}) operation in that they
+allow you to specify a particular date against which @command{tar} can
+compare when deciding whether or not to archive the files.
+
address@hidden @option
address@hidden after-date
address@hidden newer
address@hidden address@hidden
address@hidden address@hidden
address@hidden -N @var{date}
+Only store files newer than @var{date}.
+
+Acts on files only if their data modification or status change times are
+later than @var{date}. Use in conjunction with any operation.
+
+If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
+name; the data modification time of that file is used as the date.
+
address@hidden newer-mtime
address@hidden address@hidden
+Acts like @option{--after-date}, but only looks at data modification times.
address@hidden table
+
+These options limit @command{tar} to operate only on files which have
+been modified after the date specified. A file's status is considered to have
+changed if its contents have been modified, or if its owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see @ref{Date input formats}; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+Gurus would say that @option{--after-date} tests both the data
+modification time (@code{mtime}, the time the contents of the file
+were last modified) and the status change time (@code{ctime}, the time
+the file's status was last changed: owner, permissions, etc.@:)
+fields, while @option{--newer-mtime} tests only the @code{mtime}
+field.
+
+To be precise, @option{--after-date} checks @emph{both} @code{mtime} and
address@hidden and processes the file if either one is more recent than
address@hidden, while @option{--newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither does it use @code{atime} (the last time the
+contents of the file were looked at).
+
+Date specifiers can have embedded spaces. Because of this, you may need
+to quote date arguments to keep the shell from parsing them as separate
+arguments. For example, the following command will add to the archive
+all the files modified less than two days ago:
+
address@hidden
+$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
address@hidden smallexample
+
+When any of these options is used with the option @option{--verbose}
+(@pxref{verbose tutorial}) @acronym{GNU} @command{tar} will try to convert the
specified
+date back to its textual representation and compare that with the
+one given with the option. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date. For example:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
+tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
+13:19:37.232434
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden Note:} @option{--after-date} and @option{--newer-mtime}
+should not be used for incremental backups. @xref{Incremental Dumps},
+for proper way of creating incremental backups.
address@hidden quotation
+
address@hidden recurse
address@hidden Descending into Directories
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Avoiding recursion in directories
address@hidden Descending directories, avoiding
address@hidden Directories, avoiding recursion
address@hidden Recursion in directories, avoiding
+
address@hidden
address@hidden
+
+
+Usually, @command{tar} will recursively explore all directories (either
+those given on the command line or through the @option{--files-from}
+option) for the various files they contain. However, you may not always
+want @command{tar} to act this way.
+
address@hidden no-recursion
+The @option{--no-recursion} option inhibits @command{tar}'s recursive descent
+into specified directories. If you specify @option{--no-recursion}, you can
+use the @command{find} utility for hunting through levels of directories to
+construct a list of file names which you could then pass to @command{tar}.
address@hidden allows you to be more selective when choosing which files to
+archive; see @ref{files}, for more information on using @command{find} with
address@hidden, or look.
+
address@hidden @option
address@hidden --no-recursion
+Prevents @command{tar} from recursively descending directories.
+
address@hidden recursion
address@hidden --recursion
+Requires @command{tar} to recursively descend directories.
+This is the default.
address@hidden table
+
+When you use @option{--no-recursion}, @acronym{GNU} @command{tar} grabs
+directory entries themselves, but does not descend on them
+recursively. Many people use @command{find} for locating files they
+want to back up, and since @command{tar} @emph{usually} recursively
+descends on directories, they have to use the @address@hidden -type d}}
+test in their @command{find} invocation (@pxref{Type, Type, Type test,
+find, Finding Files}), as they usually do not want all the files in a
+directory. They then use the @option{--files-from} option to archive
+the files located via @command{find}.
+
+The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
address@hidden (@option{--preserve-permissions},
address@hidden) option does not affect them---while users might really
+like it to. Specifying @option{--no-recursion} is a way to tell
address@hidden to grab only the directory entries given to it, adding
+no new files on its own. To summarize, if you use @command{find} to
+create a list of files to be stored in an archive, use it as follows:
+
address@hidden
address@hidden
+$ @kbd{find @var{dir} @var{tests} | \
+ tar -cf @var{archive} -T - --no-recursion}
address@hidden group
address@hidden smallexample
+
+The @option{--no-recursion} option also applies when extracting: it
+causes @command{tar} to extract only the matched directory entries, not
+the files under those directories.
+
+The @option{--no-recursion} option also affects how globbing patterns
+are interpreted (@pxref{controlling pattern-matching}).
+
+The @option{--no-recursion} and @option{--recursion} options apply to
+later options and operands, and can be overridden by later occurrences
+of @option{--no-recursion} and @option{--recursion}. For example:
+
address@hidden
+$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord}
address@hidden smallexample
+
address@hidden
+creates an archive with one entry for @file{grape}, and the recursive
+contents of @file{grape/concord}, but no entries under @file{grape}
+other than @file{grape/concord}.
+
address@hidden one
address@hidden Crossing File System Boundaries
address@hidden File system boundaries, not crossing
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden will normally automatically cross file system boundaries in
+order to archive files which are part of a directory tree. You can
+change this behavior by running @command{tar} and specifying
address@hidden This option only affects files that are
+archived because they are in a directory that is being archived;
address@hidden will still archive files explicitly named on the command line
+or through @option{--files-from}, regardless of where they reside.
+
address@hidden @option
address@hidden one-file-system
address@hidden --one-file-system
+Prevents @command{tar} from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
address@hidden table
+
+The @option{--one-file-system} option causes @command{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same file system as the directory itself, then
address@hidden will not archive that file. If the file is a directory
+itself, @command{tar} will not archive anything beneath it; in other words,
address@hidden will not cross mount points.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
address@hidden (@option{-v}), files that are excluded are
+mentioned by name on the standard error.
+
address@hidden
+* directory:: Changing Directory
+* absolute:: Absolute File Names
address@hidden menu
+
address@hidden directory
address@hidden Changing the Working Directory
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden Changing directory mid-stream
address@hidden Directory, changing mid-stream
address@hidden Working directory, specifying
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using
address@hidden (@option{-T}), use @option{--directory} (@option{-C}).
+This will change the working directory to the specified directory
+after that point in the list.
+
address@hidden @option
address@hidden directory
address@hidden address@hidden
address@hidden -C @var{directory}
+Changes the working directory in the middle of a command line.
address@hidden table
+
+For example,
+
address@hidden
+$ @kbd{tar -c -f jams.tar grape prune -C food cherry}
address@hidden smallexample
+
address@hidden
+will place the files @file{grape} and @file{prune} from the current
+directory into the archive @file{jams.tar}, followed by the file
address@hidden from the directory @file{food}. This option is especially
+useful when you have several widely separated files that you want to
+store in the same archive.
+
+Note that the file @file{cherry} is recorded in the archive under the
+precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the
+archive will contain three files that all appear to have come from the
+same directory; if the archive is extracted with plain @samp{tar
+--extract}, all three files will be written in the current directory.
+
+Contrast this with the command,
+
address@hidden
+$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
address@hidden smallexample
+
address@hidden
+which records the third file in the archive under the name
address@hidden/cherry} so that, if the archive is extracted using
address@hidden --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.
+The following command places the files @file{/etc/passwd},
address@hidden/etc/hosts}, and @file{/lib/libc.a} into the archive
address@hidden:
+
address@hidden
+$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
address@hidden smallexample
+
address@hidden
+However, the names of the archive members will be exactly what they were
+on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
+They will not appear to be related by file name to the original
+directories where those files were located.
+
+Note that @option{--directory} options are interpreted consecutively. If
address@hidden specifies a relative file name, it is interpreted
+relative to the then current directory, which might not be the same as
+the original current working directory of @command{tar}, due to a previous
address@hidden option.
+
+When using @option{--files-from} (@pxref{files}), you can put various
address@hidden options (including @option{-C}) in the file list. Notice,
+however, that in this case the option and its argument may not be
+separated by whitespace. If you use short option, its argument must
+either follow the option letter immediately, without any intervening
+whitespace, or occupy the next line. Otherwise, if you use long
+option, separate its argument by an equal sign.
+
+For instance, the file list for the above example will be:
+
address@hidden
address@hidden
+-C
+/etc
+passwd
+hosts
+-C
+/lib
+libc.a
address@hidden group
address@hidden smallexample
+
address@hidden
+To use it, you would invoke @command{tar} as follows:
+
address@hidden
+$ @kbd{tar -c -f foo.tar --files-from list}
address@hidden smallexample
+
+Notice also that you can only use the short option variant in the file
+list, i.e., always use @option{-C}, not @option{--directory}.
+
+The interpretation of @option{--directory} is disabled by
address@hidden option.
+
address@hidden absolute
address@hidden Absolute File Names
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @option
address@hidden absolute-names
address@hidden --absolute-names
address@hidden -P
+Do not strip leading slashes from file names, and permit file names
+containing a @file{..} file name component.
address@hidden table
+
+By default, @acronym{GNU} @command{tar} drops a leading @samp{/} on
+input or output, and complains about file names containing a @file{..}
+component. This option turns off this behavior.
+
+When @command{tar} extracts archive members from an archive, it strips any
+leading slashes (@samp{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
address@hidden/etc/passwd}, @command{tar} will extract it as if the name were
+really @file{etc/passwd}.
+
+File names containing @file{..} can cause problems when extracting, so
address@hidden normally warns you about such files when creating an
+archive, and rejects attempts to extracts such files.
+
+Other @command{tar} programs do not do this. As a result, if you
+create an archive whose member names start with a slash, they will be
+difficult for other people with a address@hidden @command{tar}
+program to use. Therefore, @acronym{GNU} @command{tar} also strips
+leading slashes from member names when putting members into the
+archive. For example, if you ask @command{tar} to add the file
address@hidden/bin/ls} to an archive, it will do so, but the member name will
+be @file{bin/address@hidden side effect of this is that when
address@hidden is used with @option{--verbose} the resulting output
+is not, generally speaking, the same as the one you'd get running
address@hidden --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.}
+
+If you use the @option{--absolute-names} (@option{-P}) option,
address@hidden will do none of these transformations.
+
+To archive or extract files relative to the root directory, specify
+the @option{--absolute-names} (@option{-P}) option.
+
+Normally, @command{tar} acts on files relative to the working
+directory---ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+When you specify @option{--absolute-names} (@option{-P}),
address@hidden stores file names including all superior directory
+names, and preserves leading slashes. If you only invoked
address@hidden from the root directory you would never need the
address@hidden option, but using this option
+may be more convenient than switching to root.
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden --absolute-names
+Preserves full file names (including superior directory names) when
+archiving files. Preserves leading slash when extracting files.
+
address@hidden table
+
address@hidden
address@hidden
+
+
address@hidden prints out a message about removing the @samp{/} from
+file names. This message appears once per @acronym{GNU} @command{tar}
+invocation. It represents something which ought to be told; ignoring
+what it means can cause very serious surprises, later.
+
+Some people, nevertheless, do not want to see this message. Wanting to
+play really dangerously, one may of course redirect @command{tar} standard
+error to the sink. For example, under @command{sh}:
+
address@hidden
+$ @kbd{tar -c -f archive.tar /home 2> /dev/null}
address@hidden smallexample
+
address@hidden
+Another solution, both nicer and simpler, would be to change to
+the @file{/} directory first, and then avoid absolute notation.
+For example:
+
address@hidden
+$ @kbd{(cd / && tar -c -f archive.tar home)}
+# @i{or}:
+$ @kbd{tar -c -f archive.tar -C / home}
address@hidden smallexample
+
address@hidden GNU date syntax documentation
+
address@hidden Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
2002,
address@hidden 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+
address@hidden Permission is granted to copy, distribute and/or modify this
document
address@hidden under the terms of the GNU Free Documentation License, Version
1.1 or
address@hidden any later version published by the Free Software Foundation;
with no
address@hidden Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover
address@hidden Texts. A copy of the license is included in the ``GNU Free
address@hidden Documentation License'' file as part of this distribution.
+
address@hidden Date input formats
address@hidden Date input formats
+
address@hidden date input formats
address@hidden get_date
+
+First, a quote:
+
address@hidden
+Our units of temporal measurement, from seconds on up to months, are so
+complicated, asymmetrical and disjunctive so as to make coherent mental
+reckoning in time all but impossible. Indeed, had some tyrannical god
+contrived to enslave our minds to time, to make it all but impossible
+for us to escape subjection to sodden routines and unpleasant surprises,
+he could hardly have done better than handing down our present system.
+It is like a set of trapezoidal building blocks, with no vertical or
+horizontal surfaces, like a language in which the simplest thought
+demands ornate constructions, useless particles and lengthy
+circumlocutions. Unlike the more successful patterns of language and
+science, which enable us to face experience boldly or at least
+level-headedly, our system of temporal calculation silently and
+persistently encourages our terror of time.
+
address@hidden It is as though architects had to measure length in feet, width
+in meters and height in ells; as though basic instruction manuals
+demanded a knowledge of five different languages. It is no wonder then
+that we often look into our own immediate past or future, last Tuesday
+or a week from Sunday, with feelings of helpless confusion. @dots{}
+
+--- Robert Grudin, @cite{Time and the Art of Living}.
address@hidden quotation
+
+This section describes the textual date representations that @sc{gnu}
+programs accept. These are the strings you, as a user, can supply as
+arguments to the various programs. The C interface (via the
address@hidden function) is not described here.
+
address@hidden
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
address@hidden menu
+
+
address@hidden General date syntax
address@hidden General date syntax
+
address@hidden general date syntax
+
address@hidden items in date strings
+A @dfn{date} is a string, possibly empty, containing many items
+separated by whitespace. The whitespace may be omitted when no
+ambiguity arises. The empty string means the beginning of today (i.e.,
+midnight). Order of the items is immaterial. A date string may contain
+many flavors of items:
+
address@hidden @bullet
address@hidden calendar date items
address@hidden time of day items
address@hidden time zone items
address@hidden day of the week items
address@hidden relative items
address@hidden pure numbers.
address@hidden itemize
+
address@hidden We describe each of these item types in turn, below.
+
address@hidden numbers, written-out
address@hidden ordinal numbers
address@hidden first @r{in date strings}
address@hidden next @r{in date strings}
address@hidden last @r{in date strings}
+A few ordinal numbers may be written out in words in some contexts. This is
+most useful for specifying day of the week items or relative items (see
+below). Among the most commonly used ordinal numbers, the word
address@hidden stands for @math{-1}, @samp{this} stands for 0, and
address@hidden and @samp{next} both stand for 1. Because the word
address@hidden stands for the unit of time there is no way to write the
+ordinal number 2, but for convenience @samp{third} stands for 3,
address@hidden for 4, @samp{fifth} for 5,
address@hidden for 6, @samp{seventh} for 7, @samp{eighth} for 8,
address@hidden for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
address@hidden for 12.
+
address@hidden months, written-out
+When a month is written this way, it is still considered to be written
+numerically, instead of being ``spelled in full''; this changes the
+allowed strings.
+
address@hidden language, in dates
+In the current implementation, only English is supported for words and
+abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
address@hidden, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
+
address@hidden language, in dates
address@hidden time zone item
+The output of the @command{date} command
+is not always acceptable as a date string,
+not only because of the language problem, but also because there is no
+standard meaning for time zone items like @samp{IST}. When using
address@hidden to generate a date string intended to be parsed later,
+specify a date format that is independent of language and that does not
+use time zone items other than @samp{UTC} and @samp{Z}. Here are some
+ways to do this:
+
address@hidden
+$ LC_ALL=C TZ=UTC0 date
+Mon Mar 1 00:21:42 UTC 2004
+$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+2004-03-01 00:21:42Z
+$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
+2004-02-29 16:21:42,692722128-0800
+$ date --rfc-2822 # a GNU extension
+Sun, 29 Feb 2004 16:21:42 -0800
+$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
+2004-02-29 16:21:42 -0800
+$ date +'@@%s.%N' # %s and %N are GNU extensions.
+@@1078100502.692722128
address@hidden example
+
address@hidden case, ignored in dates
address@hidden comments, in dates
+Alphabetic case is completely ignored in dates. Comments may be introduced
+between round parentheses, as long as included parentheses are properly
+nested. Hyphens not followed by a digit are currently ignored. Leading
+zeros on numbers are ignored.
+
+Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
+rejected. In the typical case of a host that does not support leap
+seconds, a time like @samp{23:59:60} is rejected even if it
+corresponds to a valid leap second.
+
+
address@hidden Calendar date items
address@hidden Calendar date items
+
address@hidden calendar date item
+
+A @dfn{calendar date item} specifies a day of the year. It is
+specified differently, depending on whether the month is specified
+numerically or literally. All these strings specify the same calendar date:
+
address@hidden
+1972-09-24 # @sc{iso} 8601.
+72-9-24 # Assume 19xx for 69 through 99,
+ # 20xx for 00 through 68.
+72-09-24 # Leading zeros are ignored.
+9/24/72 # Common U.S. writing.
+24 September 1972
+24 Sept 72 # September has a special abbreviation.
+24 Sep 72 # Three-letter abbreviations always allowed.
+Sep 24, 1972
+24-sep-72
+24sep72
address@hidden example
+
+The year can also be omitted. In this case, the last specified year is
+used, or the current year if none. For example:
+
address@hidden
+9/24
+sep 24
address@hidden example
+
+Here are the rules.
+
address@hidden @sc{iso} 8601 date format
address@hidden date format, @sc{iso} 8601
+For numeric months, the @sc{iso} 8601 format
address@hidden@address@hidden@var{day}} is allowed, where @var{year} is
+any positive number, @var{month} is a number between 01 and 12, and
address@hidden is a number between 01 and 31. A leading zero must be present
+if a number is less than ten. If @var{year} is 68 or smaller, then 2000
+is added to it; otherwise, if @var{year} is less than 100,
+then 1900 is added to it. The construct
address@hidden@var{month}/@var{day}/@var{year}}, popular in the United States,
+is accepted. Also @address@hidden/@var{day}}, omitting the year.
+
address@hidden month names in date strings
address@hidden abbreviations for months
+Literal months may be spelled out in full: @samp{January},
address@hidden, @samp{March}, @samp{April}, @samp{May}, @samp{June},
address@hidden, @samp{August}, @samp{September}, @samp{October},
address@hidden or @samp{December}. Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write @samp{Sept} instead of @samp{September}.
+
+When months are written literally, the calendar date may be given as any
+of the following:
+
address@hidden
address@hidden @var{month} @var{year}
address@hidden @var{month}
address@hidden @var{day} @var{year}
address@hidden@address@hidden
address@hidden example
+
+Or, omitting the year:
+
address@hidden
address@hidden @var{day}
address@hidden example
+
+
address@hidden Time of day items
address@hidden Time of day items
+
address@hidden time of day item
+
+A @dfn{time of day item} in date strings specifies the time on a given
+day. Here are some examples, all of which represent the same time:
+
address@hidden
+20:02:00.000000
+20:02
+8:02pm
+20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
address@hidden example
+
+More generally, the time of day may be given as
address@hidden@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
+a number between 0 and 23, @var{minute} is a number between 0 and
+59, and @var{second} is a number between 0 and 59 possibly followed by
address@hidden or @samp{,} and a fraction containing one or more digits.
+Alternatively,
address@hidden:@var{second}} can be omitted, in which case it is taken to
+be zero. On the rare hosts that support leap seconds, @var{second}
+may be 60.
+
address@hidden am @r{in date strings}
address@hidden pm @r{in date strings}
address@hidden midnight @r{in date strings}
address@hidden noon @r{in date strings}
+If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
+or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
address@hidden:@var{minute}} may be omitted (taken to be zero). @samp{am}
+indicates the first half of the day, @samp{pm} indicates the second
+half of the day. In this notation, 12 is the predecessor of 1:
+midnight is @samp{12am} while noon is @samp{12pm}.
+(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
+as opposed to the old tradition derived from Latin
+which uses @samp{12m} for noon and @samp{12pm} for midnight.)
+
address@hidden time zone correction
address@hidden minutes, time zone correction by
+The time may alternatively be followed by a time zone correction,
+expressed as @address@hidden@address@hidden, where @var{s} is @samp{+}
+or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
+of zone minutes. You can also separate @var{hh} from @var{mm} with a colon.
+When a time zone correction is given this way, it
+forces interpretation of the time relative to
+Coordinated Universal Time (@sc{utc}), overriding any previous
+specification for the time zone or the local time zone. For example,
address@hidden and @samp{+05:30} both stand for the time zone 5.5 hours
+ahead of @sc{utc} (e.g., India). The @var{minute}
+part of the time of day may not be elided when a time zone correction
+is used. This is the best way to specify a time zone correction by
+fractional parts of an hour.
+
+Either @samp{am}/@samp{pm} or a time zone correction may be specified,
+but not both.
+
+
address@hidden Time zone items
address@hidden Time zone items
+
address@hidden time zone item
+
+A @dfn{time zone item} specifies an international time zone, indicated
+by a small set of letters, e.g., @samp{UTC} or @samp{Z}
+for Coordinated Universal
+Time. Any included periods are ignored. By following a
+non-daylight-saving time zone by the string @samp{DST} in a separate
+word (that is, separated by some white space), the corresponding
+daylight saving time zone may be specified.
+Alternatively, a non-daylight-saving time zone can be followed by a
+time zone correction, to add the two values. This is normally done
+only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
address@hidden:30}.
+
+Time zone items other than @samp{UTC} and @samp{Z}
+are obsolescent and are not recommended, because they
+are ambiguous; for example, @samp{EST} has a different meaning in
+Australia than in the United States. Instead, it's better to use
+unambiguous numeric time zone corrections like @samp{-0500}, as
+described in the previous section.
+
+If neither a time zone item nor a time zone correction is supplied,
+time stamps are interpreted using the rules of the default time zone
+(@pxref{Specifying time zone rules}).
+
+
address@hidden Day of week items
address@hidden Day of week items
+
address@hidden day of week item
+
+The explicit mention of a day of the week will forward the date
+(only if necessary) to reach that day of the week in the future.
+
+Days of the week may be spelled out in full: @samp{Sunday},
address@hidden, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
address@hidden or @samp{Saturday}. Days may be abbreviated to their
+first three letters, optionally followed by a period. The special
+abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
address@hidden and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
+also allowed.
+
address@hidden next @var{day}
address@hidden last @var{day}
+A number may precede a day of the week item to move forward
+supplementary weeks. It is best used in expression like @samp{third
+monday}. In this context, @samp{last @var{day}} or @samp{next
address@hidden is also acceptable; they move one week before or after
+the day that @var{day} by itself would represent.
+
+A comma following a day of the week item is ignored.
+
+
address@hidden Relative items in date strings
address@hidden Relative items in date strings
+
address@hidden relative items in date strings
address@hidden displacement of dates
+
address@hidden items} adjust a date (or the current date if none) forward
+or backward. The effects of relative items accumulate. Here are some
+examples:
+
address@hidden
+1 year
+1 year ago
+3 years
+2 days
address@hidden example
+
address@hidden year @r{in date strings}
address@hidden month @r{in date strings}
address@hidden fortnight @r{in date strings}
address@hidden week @r{in date strings}
address@hidden day @r{in date strings}
address@hidden hour @r{in date strings}
address@hidden minute @r{in date strings}
+The unit of time displacement may be selected by the string @samp{year}
+or @samp{month} for moving by whole years or months. These are fuzzy
+units, as years and months are not all of equal duration. More precise
+units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
+days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
address@hidden or @samp{min} worth 60 seconds, and @samp{second} or
address@hidden worth one second. An @samp{s} suffix on these units is
+accepted and ignored.
+
address@hidden ago @r{in date strings}
+The unit of time may be preceded by a multiplier, given as an optionally
+signed number. Unsigned numbers are taken as positively signed. No
+number at all implies 1 for a multiplier. Following a relative item by
+the string @samp{ago} is equivalent to preceding the unit by a
+multiplier with value @math{-1}.
+
address@hidden day @r{in date strings}
address@hidden tomorrow @r{in date strings}
address@hidden yesterday @r{in date strings}
+The string @samp{tomorrow} is worth one day in the future (equivalent
+to @samp{day}), the string @samp{yesterday} is worth
+one day in the past (equivalent to @samp{day ago}).
+
address@hidden now @r{in date strings}
address@hidden today @r{in date strings}
address@hidden this @r{in date strings}
+The strings @samp{now} or @samp{today} are relative items corresponding
+to zero-valued time displacement, these strings come from the fact
+a zero-valued time displacement represents the current time when not
+otherwise changed by previous items. They may be used to stress other
+items, like in @samp{12:00 today}. The string @samp{this} also has
+the meaning of a zero-valued time displacement, but is preferred in
+date strings like @samp{this thursday}.
+
+When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time,
+the resulting date and time are adjusted accordingly.
+
+The fuzz in units can cause problems with relative items. For
+example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
+because 2003-06-31 is an invalid date. To determine the previous
+month more reliably, you can ask for the month before the 15th of the
+current month. For example:
+
address@hidden
+$ date -R
+Thu, 31 Jul 2003 13:02:39 -0700
+$ date --date='-1 month' +'Last month was %B?'
+Last month was July?
+$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+Last month was June!
address@hidden example
+
+Also, take care when manipulating dates around clock changes such as
+daylight saving leaps. In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the @env{TZ} environment variable to
address@hidden before embarking on calendrical calculations.
+
address@hidden Pure numbers in date strings
address@hidden Pure numbers in date strings
+
address@hidden pure numbers in date strings
+
+The precise interpretation of a pure decimal number depends
+on the context in the date string.
+
+If the decimal number is of the form @address@hidden@var{dd} and no
+other calendar date item (@pxref{Calendar date items}) appears before it
+in the date string, then @var{yyyy} is read as the year, @var{mm} as the
+month number and @var{dd} as the day of the month, for the specified
+calendar date.
+
+If the decimal number is of the form @address@hidden and no other time
+of day item appears before it in the date string, then @var{hh} is read
+as the hour of the day and @var{mm} as the minute of the hour, for the
+specified time of day. @var{mm} can also be omitted.
+
+If both a calendar date and a time of day appear to the left of a number
+in the date string, but no relative item, then the number overrides the
+year.
+
+
address@hidden Seconds since the Epoch
address@hidden Seconds since the Epoch
+
+If you precede a number with @samp{@@}, it represents an internal time
+stamp as a count of seconds. The number can contain an internal
+decimal point (either @samp{.} or @samp{,}); any excess precision not
+supported by the internal representation is truncated toward minus
+infinity. Such a number cannot be combined with any other date
+item, as it specifies a complete time stamp.
+
address@hidden beginning of time, for @acronym{POSIX}
address@hidden epoch, for @acronym{POSIX}
+Internally, computer times are represented as a count of seconds since
+an epoch---a well-defined point of time. On @acronym{GNU} and
address@hidden systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
address@hidden@@0} represents this time, @samp{@@1} represents 1970-01-01
+00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
address@hidden systems support such times as an extension
+to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
+represents 1969-12-31 23:59:59 @sc{utc}.
+
+Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
+of seconds with nanosecond subcounts, and can represent all the times
+in the known lifetime of the universe to a resolution of 1 nanosecond.
+
+On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts @samp{@@915148799} represents 1998-12-31
+23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
address@hidden, and there is no way to represent the intervening leap second
+1998-12-31 23:59:60 @sc{utc}.
+
address@hidden Specifying time zone rules
address@hidden Specifying time zone rules
+
address@hidden TZ
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the @env{TZ} environment
+variable, or by a system default if @env{TZ} is not set. To specify a
+different set of default time zone rules that apply just to one date,
+start the date with a string of the form @samp{TZ="@var{rule}"}. The
+two quote characters (@samp{"}) must be present in the date, and any
+quotes or backslashes within @var{rule} must be escaped by a
+backslash.
+
+For example, with the @acronym{GNU} @command{date} command you can
+answer the question ``What time is it in New York when a Paris clock
+shows 6:30am on October 31, 2004?'' by using a date beginning with
address@hidden"Europe/Paris"} as shown in the following shell transcript:
+
address@hidden
+$ export TZ="America/New_York"
+$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+Sun Oct 31 01:30:00 EDT 2004
address@hidden example
+
+In this example, the @option{--date} operand begins with its own
address@hidden setting, so the rest of that operand is processed according
+to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
+06:30} as if it were in Paris. However, since the output of the
address@hidden command is processed according to the overall time zone
+rules, it uses New York time. (Paris was normally six hours ahead of
+New York in 2004, but this example refers to a brief Halloween period
+when the gap was five hours.)
+
+A @env{TZ} value is a rule that typically names a location in the
address@hidden://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
+A recent catalog of location names appears in the
address@hidden://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
+Gateway}. A few address@hidden hosts require a colon before a
+location name in a @env{TZ} setting, e.g.,
address@hidden":America/New_York"}.
+
+The @samp{tz} database includes a wide variety of locations ranging
+from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
+if you are at sea and have your own private time zone, or if you are
+using a address@hidden host that does not support the @samp{tz}
+database, you may need to use a @acronym{POSIX} rule instead. Simple
address@hidden rules like @samp{UTC0} specify a time zone without
+daylight saving time; other rules can specify simple daylight saving
+regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
+libc, The GNU C Library}.
+
address@hidden Authors of get_date
address@hidden Authors of @code{get_date}
+
address@hidden authors of @code{get_date}
+
address@hidden Bellovin, Steven M.
address@hidden Salz, Rich
address@hidden Berets, Jim
address@hidden MacKenzie, David
address@hidden Meyering, Jim
address@hidden Eggert, Paul
address@hidden was originally implemented by Steven M. Bellovin
+(@email{smb@@research.att.com}) while at the University of North Carolina
+at Chapel Hill. The code was later tweaked by a couple of people on
+Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
+and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
+revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
+Paul Eggert and others.
+
address@hidden Pinard, F.
address@hidden Berry, K.
+This chapter was originally produced by Fran@,{c}ois Pinard
+(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
+and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
+
address@hidden Formats
address@hidden Controlling the Archive Format
+
address@hidden Tar archive formats
+Due to historical reasons, there are several formats of tar archives.
+All of them are based on the same principles, but have some subtle
+differences that often make them incompatible with each other.
+
+GNU tar is able to create and handle archives in a variety of formats.
+The most frequently used formats are (in alphabetical order):
+
address@hidden @asis
address@hidden gnu
+Format used by @acronym{GNU} @command{tar} versions up to 1.13.25. This
format derived
+from an early @acronym{POSIX} standard, adding some improvements such as
+sparse file handling and incremental archives. Unfortunately these
+features were implemented in a way incompatible with other archive
+formats.
+
+Archives in @samp{gnu} format are able to hold pathnames of unlimited
+length.
+
address@hidden oldgnu
+Format used by @acronym{GNU} @command{tar} of versions prior to 1.12.
+
address@hidden v7
+Archive format, compatible with the V7 implementation of tar. This
+format imposes a number of limitations. The most important of them
+are:
+
address@hidden
address@hidden The maximum length of a file name is limited to 99 characters.
address@hidden The maximum length of a symbolic link is limited to 99
characters.
address@hidden It is impossible to store special files (block and character
+devices, fifos etc.)
address@hidden Maximum value of user or group ID is limited to 2097151 (7777777
+octal)
address@hidden V7 archives do not contain symbolic ownership information (user
+and group name of the file owner).
address@hidden enumerate
+
+This format has traditionally been used by Automake when producing
+Makefiles. This practice will change in the future, in the meantime,
+however this means that projects containing filenames more than 99
+characters long will not be able to use @acronym{GNU} @command{tar} 1.15.92 and
+Automake prior to 1.9.
+
address@hidden ustar
+Archive format defined by @acronym{POSIX.1-1988} specification. It stores
+symbolic ownership information. It is also able to store
+special files. However, it imposes several restrictions as well:
+
address@hidden
address@hidden The maximum length of a file name is limited to 256 characters,
+provided that the filename can be split at directory separator in
+two parts, first of them being at most 155 bytes long. So, in most
+cases the maximum file name length will be shorter than 256
+characters.
address@hidden The maximum length of a symbolic link name is limited to
+100 characters.
address@hidden Maximum size of a file the archive is able to accomodate
+is 8GB
address@hidden Maximum value of UID/GID is 2097151.
address@hidden Maximum number of bits in device major and minor numbers is 21.
address@hidden enumerate
+
address@hidden star
+Format used by J@"org Schilling @command{star}
+implementation. @acronym{GNU} @command{tar} is able to read @samp{star}
archives but
+currently does not produce them.
+
address@hidden posix
+Archive format defined by @acronym{POSIX.1-2001} specification. This is the
+most flexible and feature-rich format. It does not impose any
+restrictions on file sizes or filename lengths. This format is quite
+recent, so not all tar implementations are able to handle it properly.
+However, this format is designed in such a way that any tar
+implementation able to read @samp{ustar} archives will be able to read
+most @samp{posix} archives as well, with the only exception that any
+additional information (such as long file names etc.) will in such
+case be extracted as plain text files along with the files it refers to.
+
+This archive format will be the default format for future versions
+of @acronym{GNU} @command{tar}.
+
address@hidden table
+
+The following table summarizes the limitations of each of these
+formats:
+
address@hidden @columnfractions .10 .20 .20 .20 .20
address@hidden Format @tab UID @tab File Size @tab Path Name @tab Devn
address@hidden gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
address@hidden oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
address@hidden v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
address@hidden ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
address@hidden posix @tab Unlimited @tab Unlimited @tab Unlimited @tab
Unlimited
address@hidden multitable
+
+The default format for @acronym{GNU} @command{tar} is defined at compilation
+time. You may check it by running @command{tar --help}, and examining
+the last lines of its output. Usually, @acronym{GNU} @command{tar} is
configured
+to create archives in @samp{gnu} format, however, future version will
+switch to @samp{posix}.
+
address@hidden
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making @command{tar} Archives More Portable
+* cpio:: Comparison of @command{tar} and @command{cpio}
address@hidden menu
+
address@hidden Compression
address@hidden Using Less Space through Compression
+
address@hidden
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
address@hidden menu
+
address@hidden gzip
address@hidden Creating and Reading Compressed Archives
address@hidden Compressed archives
address@hidden Storing archives in compressed format
+
address@hidden @command{tar} is able to create and read compressed archives.
It supports
address@hidden and @command{bzip2} compression programs. For backward
+compatibilty, 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 less
+effective than @command{gzip} and @command{bzip2}.
+
+Creating a compressed archive is simple: you just specify a
address@hidden 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, and
address@hidden (@option{--compress}) to use @command{compress} program.
+For example:
+
address@hidden
+$ @kbd{tar cfz archive.tar.gz .}
address@hidden smallexample
+
+Reading compressed archive is even simpler: you don't need to specify
+any additional options as @acronym{GNU} @command{tar} recognizes its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+
address@hidden
+# List the compressed archive
+$ @kbd{tar tf archive.tar.gz}
+# Extract the compressed archive
+$ @kbd{tar xf archive.tar.gz}
address@hidden smallexample
+
+The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case @acronym{GNU}
@command{tar}
+will indicate which option you should use. For example:
+
address@hidden
+$ @kbd{cat archive.tar.gz | tar tf -}
+tar: Archive is compressed. Use -z option
+tar: Error is not recoverable: exiting now
address@hidden smallexample
+
+If you see such diagnostics, just add the suggested option to the
+invocation of @acronym{GNU} @command{tar}:
+
address@hidden
+$ @kbd{cat archive.tar.gz | tar tfz -}
address@hidden smallexample
+
+Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e., you cannot update (@option{--update} (@option{-u})) them or
delete
+(@option{--delete}) members from them. Likewise, you cannot append
+another @command{tar} archive to a compressed archive using
address@hidden (@option{-r})). Secondly, multi-volume archives cannot be
+compressed.
+
+The following table summarizes compression options used by @acronym{GNU}
@command{tar}.
+
address@hidden @option
address@hidden gzip
address@hidden ungzip
address@hidden -z
address@hidden --gzip
address@hidden --ungzip
+Filter the archive through @command{gzip}.
+
+You can use @option{--gzip} and @option{--gunzip} on physical devices
+(tape drives, etc.) and remote files as well as on normal files; data
+to or from such devices or remote files is reblocked by another copy
+of the @command{tar} program to enforce the specified (or default) record
+size. The default compression parameters are used; if you need to
+override them, set @env{GZIP} environment variable, e.g.:
+
address@hidden
+$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
address@hidden smallexample
+
address@hidden
+Another way would be to avoid the @option{--gzip} (@option{--gunzip},
@option{--ungzip}, @option{-z}) option and run
address@hidden explicitly:
+
address@hidden
+$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
address@hidden smallexample
+
address@hidden corrupted archives
+About corrupted compressed archives: @command{gzip}'ed files have no
+redundancy, for maximum compression. The adaptive nature of the
+compression scheme means that the compression tables are implicitly
+spread all over the archive. If you lose a few blocks, the dynamic
+construction of the compression tables becomes unsynchronized, and there
+is little chance that you could recover later in the archive.
+
+There are pending suggestions for having a per-volume or per-file
+compression in @acronym{GNU} @command{tar}. This would allow for viewing the
+contents without decompression, and for resynchronizing decompression at
+every volume or file, in case of corrupted archives. Doing so, we might
+lose some compressibility. But this would have make recovering easier.
+So, there are pros and cons. We'll see!
+
address@hidden bzip2
address@hidden -j
address@hidden --bzip2
+Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
+
address@hidden compress
address@hidden uncompress
address@hidden -Z
address@hidden --compress
address@hidden --uncompress
+Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
+
+The @acronym{GNU} Project recommends you not use
address@hidden, because there is a patent covering the algorithm it
+uses. You could be sued for patent infringement merely by running
address@hidden
+
address@hidden use-compress-program
address@hidden address@hidden
+Use external compression program @var{prog}. Use this option if you
+have a compression program that @acronym{GNU} @command{tar} does not support.
There
+are two requirements to which @var{prog} should comply:
+
+First, when called without options, it should read data from standard
+input, compress it and output it on standard output.
+
+Secondly, if called with @option{-d} argument, it should do exactly
+the opposite, i.e., read the compressed data from the standard input
+and produce uncompressed data on the standard output.
address@hidden table
+
address@hidden gpg, using with tar
address@hidden gnupg, using with tar
address@hidden Using encrypted archives
+The @option{--use-compress-program} option, in particular, lets you
+implement your own filters, not necessarily dealing with
+compression/decomression. For example, suppose you wish to implement
+PGP encryption on top of compression, using @command{gpg} (@pxref{Top,
+gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard
+Manual}). The following script does that:
+
address@hidden
address@hidden
+#! /bin/sh
+case $1 in
+-d) gpg --decrypt - | gzip -d -c;;
+'') gzip -c | gpg -s ;;
+*) echo "Unknown option $1">&2; exit 1;;
+esac
address@hidden group
address@hidden smallexample
+
+Suppose you name it @file{gpgz} and save it somewhere in your
address@hidden Then the following command will create a commpressed
+archive signed with your private key:
+
address@hidden
+$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
address@hidden smallexample
+
address@hidden
+Likewise, the following command will list its contents:
+
address@hidden
+$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
address@hidden smallexample
+
+
address@hidden sparse
address@hidden Archiving Sparse Files
address@hidden Sparse Files
+
+Files in the file system occasionally have @dfn{holes}. A @dfn{hole}
+in a file is a section of the file's contents which was never written.
+The contents of a hole reads as all zeros. On many operating systems,
+actual disk storage is not allocated for holes, but they are counted
+in the length of the file. If you archive such a file, @command{tar}
+could create an archive longer than the original. To have @command{tar}
+attempt to recognize the holes in a file, use @option{--sparse}
+(@option{-S}). When you use this option, then, for any file using
+less disk space than would be expected from its length, @command{tar}
+searches the file for consecutive stretches of zeros. It then records
+in the archive for the file where the consecutive stretches of zeros
+are, and only archives the ``real contents'' of the file. On
+extraction (using @option{--sparse} is not needed on extraction) any
+such files have holes created wherever the continuous stretches of zeros
+were found. Thus, if you use @option{--sparse}, @command{tar} archives
+won't take more space than the original.
+
address@hidden @option
address@hidden sparse
address@hidden -S
address@hidden --sparse
+This option istructs @command{tar} to test each file for sparseness
+before attempting to archive it. If the file is found to be sparse it
+is treated specially, thus allowing to decrease the amount of space
+used by its image in the archive.
+
+This option is meaningful only when creating or updating archives. It
+has no effect on extraction.
address@hidden table
+
+Consider using @option{--sparse} when performing file system backups,
+to avoid archiving the expanded forms of files stored sparsely in the
+system.
+
+Even if your system has no sparse files currently, some may be
+created in the future. If you use @option{--sparse} while making file
+system backups as a matter of course, you can be assured the archive
+will never take more space on the media than the files take on disk
+(otherwise, archiving a disk filled with sparse files might take
+hundreds of tapes). @xref{Incremental Dumps}.
+
+However, be aware that @option{--sparse} option presents a serious
+drawback. Namely, in order to determine if the file is sparse
address@hidden has to read it before trying to archive it, so in total
+the file is read @strong{twice}. So, always bear in mind that the
+time needed to process all files with this option is roughly twice
+the time needed to archive them without it.
address@hidden
address@hidden
+
+
address@hidden sparse formats, defined
+When using @samp{POSIX} archive format, @acronym{GNU} @command{tar} is able to
store
+sparse files using in three distinct ways, called @dfn{sparse
+formats}. A sparse format is identified by its @dfn{number},
+consisting, as usual of two decimal numbers, delimited by a dot. By
+default, format @samp{1.0} is used. If, for some reason, you wish to
+use an earlier format, you can select it using
address@hidden option.
+
address@hidden @option
address@hidden sparse-version
address@hidden address@hidden
+
+Select the format to store sparse files in. Valid @var{version} values
+are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats},
+for a detailed description of each format.
address@hidden table
+
+Using @option{--sparse-format} option implies @option{--sparse}.
+
address@hidden Attributes
address@hidden Handling File Attributes
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+When @command{tar} reads files, it updates their access times. To
+avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either
+reset the access time retroactively or avoid changing it in the first
+place.
+
+Handling of file attributes
+
address@hidden @option
address@hidden atime-preserve
address@hidden --atime-preserve
address@hidden --atime-preserve=replace
address@hidden --atime-preserve=system
+Preserve the access times of files that are read. This works only for
+files that you own, unless you have superuser privileges.
+
address@hidden works on most systems, but it also
+restores the data modification time and updates the status change
+time. Hence it doesn't interact with incremental dumps nicely
+(@pxref{Incremental Dumps}), and it can set access or data modification times
+incorrectly if other programs access the file while @command{tar} is
+running.
+
address@hidden avoids changing the access time in
+the first place, if the operating system supports this.
+Unfortunately, this may or may not work on any given operating system
+or file system. If @command{tar} knows for sure it won't work, it
+complains right away.
+
+Currently @option{--atime-preserve} with no operand defaults to
address@hidden, but this is intended to change to
address@hidden when the latter is better-supported.
+
address@hidden touch
address@hidden -m
address@hidden --touch
+Do not extract data modification time.
+
+When this option is used, @command{tar} leaves the data modification times
+of the files it extracts as the times when the files were extracted,
+instead of setting it to the times recorded in the archive.
+
+This option is meaningless with @option{--list} (@option{-t}).
+
address@hidden same-owner
address@hidden --same-owner
+Create extracted files with the same ownership they have in the
+archive.
+
+This is the default behavior for the superuser,
+so this option is meaningful only for non-root users, when @command{tar}
+is executed on those systems able to give files away. This is
+considered as a security flaw by many people, at least because it
+makes quite difficult to correctly account users for the disk space
+they occupy. Also, the @code{suid} or @code{sgid} attributes of
+files are easily and silently lost when files are given away.
+
+When writing an archive, @command{tar} writes the user id and user name
+separately. If it can't find a user name (because the user id is not
+in @file{/etc/passwd}), then it does not write one. When restoring,
+it tries to look the name (if one was written) up in
address@hidden/etc/passwd}. If it fails, then it uses the user id stored in
+the archive instead.
+
address@hidden no-same-owner
address@hidden --no-same-owner
address@hidden -o
+Do not attempt to restore ownership when extracting. This is the
+default behavior for ordinary users, so this option has an effect
+only for the superuser.
+
address@hidden numeric-owner
address@hidden --numeric-owner
+The @option{--numeric-owner} option allows (ANSI) archives to be written
+without user/group name information or such information to be ignored
+when extracting. It effectively disables the generation and/or use
+of user/group name information. This option forces extraction using
+the numeric ids from the archive, ignoring the names.
+
+This is useful in certain circumstances, when restoring a backup from
+an emergency floppy with different passwd/group files for example.
+It is otherwise impossible to extract files with the right ownerships
+if the password file in use during the extraction does not match the
+one belonging to the file system(s) being extracted. This occurs,
+for example, if you are restoring your files after a major crash and
+had booted from an emergency floppy with no password file or put your
+disk into another machine to do the restore.
+
+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
+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.
+
+When making a @command{tar} file for distribution to other sites, it
+is sometimes cleaner to use a single owner for all files in the
+distribution, and nicer to specify the write permission bits of the
+files as stored in the archive independently of their actual value on
+the file system. The way to prepare a clean distribution is usually
+to have some Makefile rule creating a directory, copying all needed
+files in that directory, then setting ownership and permissions as
+wanted (there are a lot of possible schemes), and only then making a
address@hidden archive out of this directory, before cleaning
+everything out. Of course, we could add a lot of options to
address@hidden @command{tar} for fine tuning permissions and ownership.
+This is not the good way, I think. @acronym{GNU} @command{tar} is
+already crowded with options and moreover, the approach just explained
+gives you a great deal of control already.
+
address@hidden address@hidden, short description}
address@hidden address@hidden, short description}
address@hidden -p
address@hidden --same-permissions
address@hidden --preserve-permissions
+Extract all protection information.
+
+This option causes @command{tar} to set the modes (access permissions) of
+extracted files exactly as recorded in the archive. If this option
+is not used, the current @code{umask} setting limits the permissions
+on extracted files. This option is by default enabled when
address@hidden is executed by a superuser.
+
+
+This option is meaningless with @option{--list} (@option{-t}).
+
address@hidden preserve
address@hidden --preserve
+Same as both @option{--same-permissions} and @option{--same-order}.
+
+The @option{--preserve} option has no equivalent short option name.
+It is equivalent to @option{--same-permissions} plus @option{--same-order}.
+
address@hidden
address@hidden
+
+
address@hidden table
+
address@hidden Portability
address@hidden Making @command{tar} Archives More Portable
+
+Creating a @command{tar} archive on a particular system that is meant to be
+useful later on many other machines and with other versions of @command{tar}
+is more challenging than you might think. @command{tar} archive formats
+have been evolving since the first versions of Unix. Many such formats
+are around, and are not always compatible with each other. This section
+discusses a few problems, and gives some advice about making @command{tar}
+archives more portable.
+
+One golden rule is simplicity. For example, limit your @command{tar}
+archives to contain only regular files and directories, avoiding
+other kind of special files. Do not attempt to save sparse files or
+contiguous files as such. Let's discuss a few more problems, in turn.
+
address@hidden
address@hidden
+
+
address@hidden
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
address@hidden menu
+
address@hidden Portable Names
address@hidden Portable Names
+
+Use portable file and member names. A name is portable if it contains
+only ASCII letters and digits, @samp{/}, @samp{.}, @samp{_}, and
address@hidden; it cannot be empty, start with @samp{-} or @samp{//}, or
+contain @samp{/-}. Avoid deep directory nesting. For portability to
+old Unix hosts, limit your file name components to 14 characters or
+less.
+
+If you intend to have your @command{tar} archives to be read under
+MSDOS, you should not rely on case distinction for file names, and you
+might use the @acronym{GNU} @command{doschk} program for helping you
+further diagnosing illegal MSDOS names, which are even more limited
+than System V's.
+
address@hidden dereference
address@hidden Symbolic Links
address@hidden File names, using symbolic links
address@hidden Symbolic link as file name
+
address@hidden dereference
+Normally, when @command{tar} archives a symbolic link, it writes a
+block to the archive naming the target of the link. In that way, the
address@hidden archive is a faithful record of the file system contents.
address@hidden (@option{-h}) is used with @option{--create} (@option{-c}), and
causes
address@hidden to archive the files symbolic links point to, instead of
+the links themselves. When this option is used, when @command{tar}
+encounters a symbolic link, it will archive the linked-to file,
+instead of simply recording the presence of a symbolic link.
+
+The name under which the file is stored in the file system is not
+recorded in the archive. To record both the symbolic link name and
+the file name in the system, archive the file under both names. If
+all links were recorded automatically by @command{tar}, an extracted file
+might be linked to a file name that no longer exists in the file
+system.
+
+If a linked-to file is encountered again by @command{tar} while creating
+the same archive, an entire second copy of it will be stored. (This
address@hidden be considered a bug.)
+
+So, for portable archives, do not archive symbolic links as such,
+and use @option{--dereference} (@option{-h}): many systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
+
address@hidden old
address@hidden Old V7 Archives
address@hidden Format, old style
address@hidden Old style format
address@hidden Old style archives
address@hidden v7 archive format
+
+Certain old versions of @command{tar} cannot handle additional
+information recorded by newer @command{tar} programs. To create an
+archive in V7 format (not ANSI), which can be read by these old
+versions, specify the @option{--format=v7} option in
+conjunction with the @option{--create} (@option{-c}) (@command{tar} also
+accepts @option{--portability} or @option{--old-archive} for this
+option). When you specify it,
address@hidden leaves out information about directories, pipes, fifos,
+contiguous files, and device files, and specifies file ownership by
+group and user IDs instead of group and user names.
+
+When updating an archive, do not use @option{--format=v7}
+unless the archive was created using this option.
+
+In most cases, a @emph{new} format archive can be read by an @emph{old}
address@hidden program without serious trouble, so this option should
+seldom be needed. On the other hand, most modern @command{tar}s are
+able to read old format archives, so it might be safer for you to
+always use @option{--format=v7} for your distributions. Notice,
+however, that @samp{ustar} format is a better alternative, as it is
+free from many of @samp{v7}'s drawbacks.
+
address@hidden ustar
address@hidden Ustar Archive Format
+
address@hidden ustar archive format
+Archive format defined by @acronym{POSIX}.1-1988 specification is called
address@hidden Although it is more flexible than the V7 format, it
+still has many restrictions (@xref{Formats,ustar}, for the detailed
+description of @code{ustar} format). Along with V7 format,
address@hidden format is a good choice for archives intended to be read
+with other implementations of @command{tar}.
+
+To create archive in @code{ustar} format, use @option{--format=ustar}
+option in conjunction with the @option{--create} (@option{-c}).
+
address@hidden gnu
address@hidden @acronym{GNU} and old @acronym{GNU} @command{tar} format
+
address@hidden GNU archive format
address@hidden Old GNU archive format
address@hidden @command{tar} was based on an early draft of the
address@hidden 1003.1 @code{ustar} standard. @acronym{GNU} extensions to
address@hidden, such as the support for file names longer than 100
+characters, use portions of the @command{tar} header record which were
+specified in that @acronym{POSIX} draft as unused. Subsequent changes in
address@hidden have allocated the same parts of the header record for
+other purposes. As a result, @acronym{GNU} @command{tar} format is
+incompatible with the current @acronym{POSIX} specification, and with
address@hidden programs that follow it.
+
+In the majority of cases, @command{tar} will be configured to create
+this format by default. This will change in the future releases, since
+we plan to make @samp{POSIX} format the default.
+
+To force creation a @acronym{GNU} @command{tar} archive, use option
address@hidden
+
address@hidden posix
address@hidden @acronym{GNU} @command{tar} and @acronym{POSIX} @command{tar}
+
address@hidden POSIX archive format
address@hidden PAX archive format
+Starting from version 1.14 @acronym{GNU} @command{tar} features full support
for
address@hidden archives.
+
+A @acronym{POSIX} conformant archive will be created if @command{tar}
+was given @option{--format=posix} (@option{--format=pax}) option. No
+special option is required to read and extract from a @acronym{POSIX}
+archive.
+
address@hidden
+* PAX keywords:: Controlling Extended Header Keywords.
address@hidden menu
+
address@hidden PAX keywords
address@hidden Controlling Extended Header Keywords
+
address@hidden @option
address@hidden pax-option
address@hidden address@hidden
+Handle keywords in @acronym{PAX} extended headers. This option is
+equivalent to @option{-o} option of the @command{pax} utility.
address@hidden table
+
address@hidden is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+
address@hidden @code
address@hidden address@hidden
+When used with one of archive-creation commands,
+this option instructs @command{tar} to omit from extended header records
+that it produces any keywords matching the string @var{pattern}.
+
+When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given @var{pattern} in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in @acronym{POSIX 1003.2}, 3.13
+(@pxref{wildcards}). For example:
+
address@hidden
+--pax-option delete=security.*
address@hidden smallexample
+
+would suppress security-related information.
+
address@hidden address@hidden
+
+This keyword allows user control over the name that is written into the
+ustar header blocks for the extended headers. The name is obtained
+from @var{string} after making the following substitutions:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on the translated pathname.
address@hidden %f @tab The filename of the file, equivalent to the result
+of the @command{basename} utility on the translated pathname.
address@hidden %p @tab The process ID of the @command{tar} process.
address@hidden %% @tab A @samp{%} character.
address@hidden multitable
+
+Any other @samp{%} characters in @var{string} produce undefined
+results.
+
+If no option @samp{exthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
address@hidden
+%d/PaxHeaders.%p/%f
address@hidden smallexample
+
address@hidden address@hidden
+This keyword allows user control over the name that is written into
+the ustar header blocks for global extended header records. The name
+is obtained from the contents of @var{string}, after making
+the following substitutions:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %n @tab An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
address@hidden %p @tab The process ID of the @command{tar} process.
address@hidden %% @tab A @samp{%} character.
address@hidden multitable
+
+Any other @samp{%} characters in @var{string} produce undefined results.
+
+If no option @samp{globexthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
address@hidden
+$TMPDIR/GlobalHead.%p.%n
address@hidden smallexample
+
address@hidden
+where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
+environment variable. If @var{TMPDIR} is not set, @command{tar}
+uses @samp{/tmp}.
+
address@hidden @address@hidden
+When used with one of archive-creation commands, these keyword/value pairs
+will be included at the beginning of the archive in a global extended
+header record. When used with one of archive-reading commands,
address@hidden will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+
address@hidden @var{keyword}:address@hidden
+When used with one of archive-creation commands, these keyword/value pairs
+will be included as records at the beginning of an extended header for
+each file. This is effectively equivalent to @address@hidden
+form except that it creates no global extended header records.
+
+When used with one of archive-reading commands, @command{tar} will
+behave as if these keyword/value pairs were included as records at the
+end of each extended header; thus, they will override any global or
+file-specific extended header record keywords of the same names.
+For example, in the command:
+
address@hidden
+tar --format=posix --create \
+ --file archive --pax-option gname:=user .
address@hidden smallexample
+
+the group name will be forced to a new value for all files
+stored in the archive.
address@hidden table
+
address@hidden Checksumming
address@hidden Checksumming Problems
+
+SunOS and HP-UX @command{tar} fail to accept archives created using
address@hidden @command{tar} and containing non-ASCII file names, that
+is, file names having characters with the eight bit set, because they
+use signed checksums, while @acronym{GNU} @command{tar} uses unsigned
+checksums while creating archives, as per @acronym{POSIX} standards. On
+reading, @acronym{GNU} @command{tar} computes both checksums and
+accept any. It is somewhat worrying that a lot of people may go
+around doing backup of their files using faulty (or at least
+non-standard) software, not learning about it until it's time to
+restore their missing files with an incompatible file extractor, or
+vice versa.
+
address@hidden @command{tar} compute checksums both ways, and accept
+any on read, so @acronym{GNU} tar can read Sun tapes even with their
+wrong checksums. @acronym{GNU} @command{tar} produces the standard
+checksum, however, raising incompatibilities with Sun. That is to
+say, @acronym{GNU} @command{tar} has not been modified to
address@hidden incorrect archives to be read by buggy @command{tar}'s.
+I've been told that more recent Sun @command{tar} now read standard
+archives, so maybe Sun did a similar patch, after all?
+
+The story seems to be that when Sun first imported @command{tar}
+sources on their system, they recompiled it without realizing that
+the checksums were computed differently, because of a change in
+the default signing of @code{char}'s in their compiler. So they
+started computing checksums wrongly. When they later realized their
+mistake, they merely decided to stay compatible with it, and with
+themselves afterwards. Presumably, but I do not really know, HP-UX
+has chosen that their @command{tar} archives to be compatible with Sun's.
+The current standards do not favor Sun @command{tar} format. In any
+case, it now falls on the shoulders of SunOS and HP-UX users to get
+a @command{tar} able to read the good archives they receive.
+
address@hidden Large or Negative Values
address@hidden Large or Negative Values
address@hidden large values
address@hidden future time stamps
address@hidden negative time stamps
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+The above sections suggest to use @samp{oldest possible} archive
+format if in doubt. However, sometimes it is not possible. If you
+attempt to archive a file whose metadata cannot be represented using
+required format, @acronym{GNU} @command{tar} will print error message and
ignore such a
+file. You will than have to switch to a format that is able to
+handle such values. The format summary table (@pxref{Formats}) will
+help you to do so.
+
+In particular, when trying to archive files larger than 8GB or with
+timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
+12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and
address@hidden archive formats. When considering which format to
+choose, bear in mind that the @acronym{GNU} format uses
+two's-complement base-256 notation to store values that do not fit
+into standard @acronym{ustar} range. Such archives can generally be
+read only by a @acronym{GNU} @command{tar} implementation. Moreover, they
sometimes
+cannot be correctly restored on another hosts even by @acronym{GNU}
@command{tar}. For
+example, using two's complement representation for negative time
+stamps that assumes a signed 32-bit @code{time_t} generates archives
+that are not portable to hosts with differing @code{time_t}
+representations.
+
+On the other hand, @acronym{POSIX} archives, generally speaking, can
+be extracted by any tar implementation that understands older
address@hidden format. The only exception are files larger than 8GB.
+
address@hidden
address@hidden
+
+
address@hidden Other Tars
address@hidden How to Extract GNU-Specific Data Using Other @command{tar}
Implementations
+
+In previous sections you became acquainted with various quircks
+necessary to make your archives portable. Sometimes you may need to
+extract archives containing GNU-specific members using some
+third-party @command{tar} implementation or an older version of
address@hidden @command{tar}. Of course your best bet is to have @acronym{GNU}
@command{tar} installed,
+but if it is for some reason impossible, this section will explain
+how to cope without it.
+
+When we speak about @dfn{GNU-specific} members we mean two classes of
+them: members split between the volumes of a multi-volume archive and
+sparse members. You will be able to always recover such members if
+the archive is in PAX format. In addition split members can be
+recovered from archives in old GNU format. The following subsections
+describe the required procedures in detail.
+
address@hidden
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
address@hidden menu
+
address@hidden Split Recovery
address@hidden Extracting Members Split Between Volumes
+
address@hidden Mutli-volume archives, extracting using non-GNU tars
+If a member is split between several volumes of an old GNU format archive
+most third party @command{tar} implementation will fail to extract
+it. To extract it, use @command{tarcat} program (@pxref{Tarcat}).
+This program is available from
address@hidden://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html,
@acronym{GNU} @command{tar}
+home page}. It concatenates several archive volumes into a single
+valid archive. For example, if you have three volumes named from
address@hidden to @file{vol-2.tar}, you can do the following to
+extract them using a third-party @command{tar}:
+
address@hidden
+$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -}
address@hidden smallexample
+
address@hidden Mutli-volume archives in PAX format, extracting using non-GNU
tars
+You could use this approach for many (although not all) PAX
+format archives as well. However, extracting split members from a PAX
+archive is a much easier task, because PAX volumes are constructed in
+such a way that each part of a split member is extracted as a
+different file by @command{tar} implementations that are not aware of
+GNU extensions. More specifically, the very first part retains its
+original name, and all subsequent parts are named using the pattern:
+
address@hidden
+%d/GNUFileParts.%p/%f.%n
address@hidden smallexample
+
address@hidden
+where symbols preceeded by @samp{%} are @dfn{macro characters} that
+have the following meaning:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on its full name.
address@hidden %f @tab The file name of the file, equivalent to the result
+of the @command{basename} utility on its full name.
address@hidden %p @tab The process ID of the @command{tar} process that
+created the archive.
address@hidden %n @tab Ordinal number of this particular part.
address@hidden multitable
+
+For example, if, a file @file{var/longfile} was split during archive
+creation between three volumes, and the creator @command{tar} process
+had process ID @samp{27962}, then the member names will be:
+
address@hidden
+var/longfile
+var/GNUFileParts.27962/longfile.1
+var/GNUFileParts.27962/longfile.2
address@hidden smallexample
+
+When you extract your archive using a third-party @command{tar}, these
+files will be created on your disk, and the only thing you will need
+to do to restore your file in its original form is concatenate them in
+the proper order, for example:
+
address@hidden
address@hidden
+$ @kbd{cd var}
+$ @kbd{cat GNUFileParts.27962/longfile.1 \
+ GNUFileParts.27962/longfile.2 >> longfile}
+$ rm -f GNUFileParts.27962
address@hidden group
address@hidden smallexample
+
+Notice, that if the @command{tar} implementation you use supports PAX
+format archives, it will probably emit warnings about unknown keywords
+during extraction. They will lool like this:
+
address@hidden
address@hidden
+Tar file too small
+Unknown extended header keyword 'GNU.volume.filename' ignored.
+Unknown extended header keyword 'GNU.volume.size' ignored.
+Unknown extended header keyword 'GNU.volume.offset' ignored.
address@hidden group
address@hidden smallexample
+
address@hidden
+You can safely ignore these warnings.
+
+If your @command{tar} implementation is not PAX-aware, you will get
+more warnigns and more files generated on your disk, e.g.:
+
address@hidden
address@hidden
+$ @kbd{tar xf vol-1.tar}
+var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
+normal file
+Unexpected EOF in archive
+$ @kbd{tar xf vol-2.tar}
+tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
+GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
+'x', extracted as normal file
address@hidden group
address@hidden smallexample
+
+Ignore these warnings. The @file{PaxHeaders.*} directories created
+will contain files with @dfn{extended header keywords} describing the
+extracted files. You can delete them, unless they describe sparse
+members. Read further to learn more about them.
+
address@hidden Sparse Recovery
address@hidden Extracting Sparse Members
+
address@hidden sparse files, extracting with non-GNU tars
+Any @command{tar} implementation will be able to extract sparse members from a
+PAX archive. However, the extracted files will be @dfn{condensed},
+i.e. any zero blocks will be removed from them. When we restore such
+a condensed file to its original form, by adding zero bloks (or
address@hidden) back to their original locations, we call this process
address@hidden a compressed sparse file.
+
address@hidden xsparse
+To expand a file, you will need a simple auxiliary program called
address@hidden It is available in source form from
address@hidden://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html,
@acronym{GNU} @command{tar}
+home page}.
+
address@hidden sparse files v.1.0, extracting with non-GNU tars
+Let's begin with archive members in @dfn{sparse format
+version address@hidden@xref{PAX 1}.}, which are the easiest to expand.
+The condensed file will contain both file map and file data, so no
+additional data will be needed to restore it. If the original file
+name was @address@hidden/@var{name}}, then the condensed file will be
+named @address@hidden/@/address@hidden/@/@var{name}}, where
address@hidden is a decimal address@hidden speaking, @var{n} is a
address@hidden ID} of the @command{tar} process which created the
+archive (@pxref{PAX keywords}).}.
+
+To expand a version 1.0 file, run @command{xsparse} as follows:
+
address@hidden
+$ @kbd{xsparse @file{cond-file}}
address@hidden smallexample
+
address@hidden
+where @file{cond-file} is the name of the condensed file. The utility
+will deduce the name for the resulting expanded file using the
+following algorithm:
+
address@hidden 1
address@hidden If @file{cond-file} does not contain any directories,
address@hidden/cond-file} will be used;
+
address@hidden If @file{cond-file} has the form
address@hidden@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name}
+are simple names, with no @samp{/} characters in them, the output file
+name will be @address@hidden/@var{name}}.
+
address@hidden Otherwise, if @file{cond-file} has the form
address@hidden@var{dir}/@var{name}}, the output file name will be
address@hidden@var{name}}.
address@hidden enumerate
+
+In the unlikely case when this algorithm does not suite your needs,
+you can explicitely specify output file name as a second argument to
+the command:
+
address@hidden
+$ @kbd{xsparse @file{cond-file}}
address@hidden smallexample
+
+It is often a good idea to run @command{xsparse} in @dfn{dry run} mode
+first. In this mode, the command does not actually expand the file,
+but verbosely lists all actions it would be taking to do so. The dry
+run mode is enabled by @option{-n} command line argument:
+
address@hidden
address@hidden
+$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Finished dry run
address@hidden group
address@hidden smallexample
+
+To actually expand the file, you would run:
+
address@hidden
+$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile}
address@hidden smallexample
+
address@hidden
+The program behaves the same way all UNIX utilities do: it will keep
+quiet unless it has simething important to tell you (e.g. an error
+condition or something). If you wish it to produce verbose output,
+similar to that from the dry run mode, give it @option{-v} option:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
+Additionally, if your @command{tar} implementation has extracted the
address@hidden headers} for this file, you can instruct @command{xstar}
+to use them in order to verify the integrity of the expanded file.
+The option @option{-x} sets the name of the extended header file to
+use. Continuing our example:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
+ /home/gray/GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.major = 1
+Found variable GNU.sparse.minor = 0
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.realsize = 217481216
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
address@hidden sparse v.0.x}
address@hidden sparse files v.0.1, extracting with non-GNU tars
address@hidden sparse files v.0.0, extracting with non-GNU tars
+An @dfn{extended header} is a special @command{tar} archive header
+that precedes an archive member and contains a set of
address@hidden, describing the member properties that cannot be
+stored in the standard @code{ustar} header. While optional for
+expanding sparse version 1.0 members, use of extended headers is
+mandatory when expanding sparse members in older sparse formats: v.0.0
+and v.0.1 (The sparse formats are described in detail in @pxref{Sparse
+Formats}). So, for this format, the question is: how to obtain
+extended headers from the archive?
+
+If you use a @command{tar} implementation that does not support PAX
+format, extended headers for each member will be extracted as a
+separate file. If we represent the member name as
address@hidden@var{dir}/@var{name}}, then the extended header file will be
+named @address@hidden/@/address@hidden/@/@var{name}}, where
address@hidden is an integer number.
+
+Things become more difficult if your @command{tar} implementation
+does support PAX headers, because in this case you will have to
+manually extract the headers. We recommend the following algorithm:
+
address@hidden 1
address@hidden
+Consult the documentation for your @command{tar} implementation for an
+option that will print @dfn{block numbers} along with the archive
+listing (analogous to @acronym{GNU} @command{tar}'s @option{-R} option). For
example,
address@hidden has @option{-block-number}.
+
address@hidden
+Obtain the verbose listing using the @samp{block number} option, and
+find the position of the sparse member in question and the member
+immediately following it. For example, running @command{star} on our
+archive we obtain:
+
address@hidden
address@hidden
+$ @kbd{star -t -v -block-number -f arc.tar}
address@hidden
+star: Unknown extended header keyword 'GNU.sparse.size' ignored.
+star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
+star: Unknown extended header keyword 'GNU.sparse.name' ignored.
+star: Unknown extended header keyword 'GNU.sparse.map' ignored.
+block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006
GNUSparseFile.28124/sparsefile
+block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
address@hidden
address@hidden group
address@hidden smallexample
+
address@hidden
+(as usual, ignore the warnings about unknown keywords.)
+
address@hidden
+Let @var{size} be the size of the sparse member, @var{Bs} be its block number
+and @var{Bn} be the block number of the next member.
+Compute:
+
address@hidden
address@hidden = @var{Bs} - @var{Bn} - @var{size}/512 - 2
address@hidden smallexample
+
address@hidden
+This number gives the size of the extended header part in tar @dfn{blocks}.
+In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2
+= 7}.
+
address@hidden
+Use @command{dd} to extract the headers:
+
address@hidden
address@hidden address@hidden address@hidden bs=512 address@hidden
address@hidden
address@hidden smallexample
+
address@hidden
+where @var{archive} is the archive name, @var{hname} is a name of the
+file to store the extended header in, @var{Bs} and @var{N} are
+computed in previous steps.
+
+In our example, this command will be
+
address@hidden
+$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7}
address@hidden smallexample
address@hidden enumerate
+
+Finally, you can expand the condensed file, using the obtained header:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.size = 217481216
+Found variable GNU.sparse.numblocks = 208
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
+Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
address@hidden cpio
address@hidden Comparison of @command{tar} and @command{cpio}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
+The @command{cpio} archive formats, like @command{tar}, do have maximum
+pathname lengths. The binary and old ASCII formats have a max path
+length of 256, and the new ASCII and CRC ASCII formats have a max
+path length of 1024. @acronym{GNU} @command{cpio} can read and write archives
+with arbitrary pathname lengths, but other @command{cpio} implementations
+may crash unexplainedly trying to read them.
+
address@hidden handles symbolic links in the form in which it comes in BSD;
address@hidden doesn't handle symbolic links in the form in which it comes
+in System V prior to SVR4, and some vendors may have added symlinks
+to their system without enhancing @command{cpio} to know about them.
+Others may have enhanced it in a way other than the way I did it
+at Sun, and which was adopted by AT&T (and which is, I think, also
+present in the @command{cpio} that Berkeley picked up from AT&T and put
+into a later BSD release---I think I gave them my changes).
+
+(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio}
+can handle @command{tar} format input, and write it on output, and it
+probably handles symbolic links. They may not have bothered doing
+anything to enhance @command{tar} as a result.)
+
address@hidden handles special files; traditional @command{tar} doesn't.
+
address@hidden comes with V7, System III, System V, and BSD source;
address@hidden comes only with System III, System V, and later BSD
+(4.3-tahoe and later).
+
address@hidden's way of handling multiple hard links to a file can handle
+file systems that support 32-bit inumbers (e.g., the BSD file system);
address@hidden way requires you to play some games (in its "binary"
+format, i-numbers are only 16 bits, and in its "portable ASCII" format,
+they're 18 bits---it would have to play games with the "file system ID"
+field of the header to make sure that the file system ID/i-number pairs
+of different files were always different), and I don't know which
address@hidden, if any, play those games. Those that don't might get
+confused and think two files are the same file when they're not, and
+make hard links between them.
+
address@hidden way of handling multiple hard links to a file places only
+one copy of the link on the tape, but the name attached to that copy
+is the @emph{only} one you can use to retrieve the file; @command{cpio}s
+way puts one copy for every link, but you can retrieve it using any
+of the names.
+
address@hidden
+What type of check sum (if any) is used, and how is this calculated.
address@hidden quotation
+
+See the attached manual pages for @command{tar} and @command{cpio} format.
address@hidden uses a checksum which is the sum of all the bytes in the
address@hidden header for a file; @command{cpio} uses no checksum.
+
address@hidden
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene,
address@hidden quotation
+
+It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no
+generally-available version of UNIX had @command{tar} at the time. I don't
+know whether any version that was generally available @emph{within AT&T}
+had @command{tar}, or, if so, whether the people within AT&T who did
address@hidden knew about it.
+
+On restore, if there is a corruption on a tape @command{tar} will stop at
+that point, while @command{cpio} will skip over it and try to restore the
+rest of the files.
+
+The main difference is just in the command syntax and header format.
+
address@hidden is a little more tape-oriented in that everything is blocked
+to start on a record boundary.
+
address@hidden
+Is there any differences between the ability to recover crashed
+archives between the two of them. (Is there any chance of recovering
+crashed archives at all.)
address@hidden quotation
+
+Theoretically it should be easier under @command{tar} since the blocking
+lets you find a header with some variation of @samp{dd address@hidden
+However, modern @command{cpio}'s and variations have an option to just
+search for the next file header after an error with a reasonable chance
+of resyncing. However, lots of tape driver software won't allow you to
+continue past a media error which should be the only reason for getting
+out of sync unless a file changed sizes while you were writing the
+archive.
+
address@hidden
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene, please tell me about this too.
address@hidden quotation
+
+Probably because it is more media efficient (by not blocking everything
+and using only the space needed for the headers where @command{tar}
+always uses 512 bytes per file header) and it knows how to archive
+special files.
+
+You might want to look at the freely available alternatives. The
+major ones are @command{afio}, @acronym{GNU} @command{tar}, and
address@hidden, each of which have their own extensions with some
+backwards compatibility.
+
+Sparse files were @command{tar}red as sparse files (which you can
+easily test, because the resulting archive gets smaller, and
address@hidden @command{cpio} can no longer read it).
+
address@hidden Media
address@hidden Tapes and Other Archive Media
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+A few special cases about tape handling warrant more detailed
+description. These special cases are discussed below.
+
+Many complexities surround the use of @command{tar} on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of @command{tar}, it contains many features making
+such manipulation easier.
+
+Archives are usually written on dismountable media---tape cartridges,
+mag tapes, or floppy disks.
+
+The amount of data a tape or disk holds depends not only on its size,
+but also on how it is formatted. A 2400 foot long reel of mag tape
+holds 40 megabytes of data when formatted at 1600 bits per inch. The
+physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
+
+Magnetic media are re-usable---once the archive on a tape is no longer
+needed, the archive can be erased and the tape or disk used over.
+Media quality does deteriorate with use, however. Most tapes or disks
+should be discarded when they begin to produce data errors. EXABYTE
+tape cartridges should be discarded when they generate an @dfn{error
+count} (number of non-usable bits) of more than 10k.
+
+Magnetic media are written and erased using magnetic fields, and
+should be protected from such fields to avoid damage to stored data.
+Sticking a floppy disk to a filing cabinet using a magnet is probably
+not a good idea.
+
address@hidden
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
address@hidden menu
+
address@hidden Device
address@hidden Device Selection and Switching
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @option
address@hidden -f address@hidden:address@hidden
address@hidden address@hidden:address@hidden
+Use archive file or device @var{file} on @var{hostname}.
address@hidden table
+
+This option is used to specify the file name of the archive @command{tar}
+works on.
+
+If the file name is @samp{-}, @command{tar} reads the archive from standard
+input (when listing or extracting), or writes it to standard output
+(when creating). If the @samp{-} file name is given when updating an
+archive, @command{tar} will read the original archive from its standard
+input, and will write the entire new archive to its standard output.
+
+If the file name contains a @samp{:}, it is interpreted as
address@hidden:file name}. If the @var{hostname} contains an @dfn{at}
+sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In
+either case, @command{tar} will invoke the command @command{rsh} (or
address@hidden) 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
address@hidden
+Naturally, the remote machine must have an executable
address@hidden/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 @address@hidden/libexec/rmt}, where @var{prefix} stands for
+your installation prefix. This location may also be overridden at
+runtime by using @address@hidden 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}
+used a default archive name (which was picked when @command{tar} was
+compiled). The default is normally set up to be the @dfn{first} tape
+drive or other transportable I/O medium on the system.
+
+Starting with version 1.11.5, @acronym{GNU} @command{tar} uses
+standard input and standard output as the default device, and I will
+not try anymore supporting automatic device detection at installation
+time. This was failing really in too many cases, it was hopeless.
+This is now completely left to the installer to override standard
+input and standard output for default device, if this seems
+preferable. Further, I think @emph{most} actual usages of
address@hidden are done with pipes or disks, not really tapes,
+cartridges or diskettes.
+
+Some users think that using standard input and output is running
+after trouble. This could lead to a nasty surprise on your screen if
+you forget to specify an output file name---especially if you are going
+through a network or terminal server capable of buffering large amounts
+of output. We had so many bug reports in that area of configuring
+default tapes automatically, and so many contradicting requests, that
+we finally consider the problem to be portably intractable. We could
+of course use something like @samp{/dev/tape} as a default, but this
+is @emph{also} running after various kind of trouble, going from hung
+processes to accidental destruction of real tapes. After having seen
+all this mess, using standard input and output as a default really
+sounds like the only clean choice left, and a very useful one too.
+
address@hidden @command{tar} reads and writes archive in records, I
+suspect this is the main reason why block devices are preferred over
+character devices. Most probably, block devices are more efficient
+too. The installer could also check for @samp{DEFTAPE} in
address@hidden<sys/mtio.h>}.
+
address@hidden @option
address@hidden address@hidden, short description}
address@hidden --force-local
+Archive file is local even if it contains a colon.
+
address@hidden rsh-command
address@hidden address@hidden
+Use remote @var{command} instead of @command{rsh}. This option exists
+so that people who use something other than the standard @command{rsh}
+(e.g., a Kerberized @command{rsh}) can access a remote device.
+
+When this command is not used, the shell command found when
+the @command{tar} program was installed is used instead. This is
+the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh},
address@hidden/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}.
+The installer may have overridden this by defining the environment
+variable @env{RSH} @emph{at installation time}.
+
address@hidden -[0-7][lmh]
+Specify drive and density.
+
address@hidden address@hidden, short description}
address@hidden -M
address@hidden --multi-volume
+Create/list/extract multi-volume archive.
+
+This option causes @command{tar} to write a @dfn{multi-volume} archive---one
+that may be larger than will fit on the medium used to hold it.
address@hidden Archives}.
+
address@hidden address@hidden, short description}
address@hidden -L @var{num}
address@hidden address@hidden
+Change tape after writing @var{num} x 1024 bytes.
+
+This option might be useful when your tape drivers do not properly
+detect end of physical tapes. By being slightly conservative on the
+maximum tape length, you might avoid the problem entirely.
+
address@hidden address@hidden, short description}
address@hidden address@hidden, short description}
address@hidden -F @var{file}
address@hidden address@hidden
address@hidden address@hidden
+Execute @file{file} at end of each tape. This implies
address@hidden (@option{-M}). @xref{info-script}, for a detailed
+description of this option.
address@hidden table
+
address@hidden Remote Tape Server
address@hidden The Remote Tape Server
+
address@hidden remote tape drive
address@hidden 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
address@hidden@var{prefix}/libexec/rmt} on any machine whose tape drive you
+want to use. @command{tar} calls @command{rmt} by running an
address@hidden or @command{remsh} to the remote machine, optionally
+using a different login name if one is supplied.
+
+A copy of the source for the remote tape server is provided. It is
+Copyright @copyright{} 1983 by the Regents of the University of
+California, but can be freely distributed. It is compiled and
+installed by default.
+
address@hidden absolute file names
+Unless you use the @option{--absolute-names} (@option{-P}) option,
address@hidden @command{tar} will not allow you to create an archive that
contains
+absolute file names (a file name beginning with @samp{/}.) If you try,
address@hidden will automatically remove the leading @samp{/} from the
+file names it stores in the archive. It will also type a warning
+message telling you what it is doing.
+
+When reading an archive that was created with a different
address@hidden program, @acronym{GNU} @command{tar} automatically
+extracts entries in the archive which have absolute file names as if
+the file names were not absolute. This is an important feature. A
+visitor here once gave a @command{tar} tape to an operator to restore;
+the operator used Sun @command{tar} instead of @acronym{GNU} @command{tar},
+and the result was that it replaced large portions of
+our @file{/bin} and friends with versions from the tape; needless to
+say, we were unhappy about having to recover the file system from
+backup tapes.
+
+For example, if the archive contained a file @file{/usr/bin/computoy},
address@hidden @command{tar} would extract the file to @file{usr/bin/computoy},
+relative to the current directory. If you want to extract the files in
+an archive to the same absolute names that they had when the archive
+was created, you should do a @samp{cd /} before extracting the files
+from the archive, or you should either use the @option{--absolute-names}
+option, or use the command @samp{tar -C / @dots{}}.
+
address@hidden Ultrix 3.1 and write failure
+Some versions of Unix (Ultrix 3.1 is known to have this problem),
+can claim that a short write near the end of a tape succeeded,
+when it actually failed. This will result in the -M option not
+working correctly. The best workaround at the moment is to use a
+significantly larger blocking factor than the default 20.
+
+In order to update an archive, @command{tar} must be able to backspace the
+archive in order to reread or rewrite a record that was just read (or
+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}.
+
+This means that the @option{--append}, @option{--concatenate}, and
address@hidden commands will not work on any other kind of file.
+Some media simply cannot be backspaced, which means these commands and
+options will never be able to work on them. These non-backspacing
+media include pipes and cartridge tape drives.
+
+Some other media can be backspaced, and @command{tar} will work on them
+once @command{tar} is modified to do so.
+
+Archives created with the @option{--multi-volume}, @option{--label}, and
address@hidden (@option{-G}) options may not be readable by other version
+of @command{tar}. In particular, restoring a file that was split over
+a volume boundary will require some careful work with @command{dd}, if
+it can be done at all. Other versions of @command{tar} may also create
+an empty file whose name is that of the volume header. Some versions
+of @command{tar} may create normal files instead of directories archived
+with the @option{--incremental} (@option{-G}) option.
+
address@hidden Common Problems and Solutions
address@hidden Some Common Problems and their Solutions
+
+
address@hidden
+errors from system:
+permission denied
+no such file or directory
+not owner
+
+errors from @command{tar}:
+directory checksum error
+header format error
+
+errors from media/system:
+i/o error
+device busy
address@hidden format
+
+
address@hidden Blocking
address@hidden Blocking
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden and @dfn{record} terminology is rather confused, and it
+is also confusing to the expert reader. On the other hand, readers
+who are new to the field have a fresh mind, and they may safely skip
+the next two paragraphs, as the remainder of this manual uses those
+two terms in a quite consistent way.
+
+John Gilmore, the writer of the public domain @command{tar} from which
address@hidden @command{tar} was originally derived, wrote (June 1995):
+
address@hidden
+The nomenclature of tape drives comes from IBM, where I believe
+they were invented for the IBM 650 or so. On IBM mainframes, what
+is recorded on tape are tape blocks. The logical organization of
+data is into records. There are various ways of putting records into
+blocks, including @code{F} (fixed sized records), @code{V} (variable
+sized records), @code{FB} (fixed blocked: fixed size records, @var{n}
+to a block), @code{VB} (variable size records, @var{n} to a block),
address@hidden (variable spanned blocked: variable sized records that can
+occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=}
+parameter specified this to the operating system.
+
+The Unix man page on @command{tar} was totally confused about this.
+When I wrote @code{PD TAR}, I used the historically correct terminology
+(@command{tar} writes data records, which are grouped into blocks).
+It appears that the bogus terminology made it into @acronym{POSIX} (no surprise
+here), and now Fran@,{c}ois has migrated that terminology back
+into the source code too.
address@hidden quotation
+
+The term @dfn{physical block} means the basic transfer chunk from or
+to a device, after which reading or writing may stop without anything
+being lost. In this manual, the term @dfn{block} usually refers to
+a disk physical block, @emph{assuming} that each disk block is 512
+bytes in length. It is true that some disk devices have different
+physical blocks, but @command{tar} ignore these differences in its own
+format, which is meant to be portable, so a @command{tar} block is always
+512 bytes in length, and @dfn{block} always mean a @command{tar} block.
+The term @dfn{logical block} often represents the basic chunk of
+allocation of many disk blocks as a single entity, which the operating
+system treats somewhat atomically; this concept is only barely used
+in @acronym{GNU} @command{tar}.
+
+The term @dfn{physical record} is another way to speak of a physical
+block, those two terms are somewhat interchangeable. In this manual,
+the term @dfn{record} usually refers to a tape physical block,
address@hidden that the @command{tar} archive is kept on magnetic tape.
+It is true that archives may be put on disk or used with pipes,
+but nevertheless, @command{tar} tries to read and write the archive one
address@hidden at a time, whatever the medium in use. One record is made
+up of an integral number of blocks, and this operation of putting many
+disk blocks into a single tape block is called @dfn{reblocking}, or
+more simply, @dfn{blocking}. The term @dfn{logical record} refers to
+the logical organization of many characters into something meaningful
+to the application. The term @dfn{unit record} describes a small set
+of characters which are transmitted whole to or by the application,
+and often refers to a line of text. Those two last terms are unrelated
+to what we call a @dfn{record} in @acronym{GNU} @command{tar}.
+
+When writing to tapes, @command{tar} writes the contents of the archive
+in chunks known as @dfn{records}. To change the default blocking
+factor, use the @address@hidden (@option{-b
address@hidden) option. Each record will then be composed of
address@hidden blocks. (Each @command{tar} block is 512 bytes.
address@hidden) Each file written to the archive uses at least one
+full record. As a result, using a larger record size can result in
+more wasted space for small files. On the other hand, a larger record
+size can often be read and written much more efficiently.
+
+Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger record size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+When reading an archive, @command{tar} can usually figure out the
+record size on itself. When this is the case, and a non-standard
+record size was used when the archive was created, @command{tar} will
+print a message about a non-standard blocking factor, and then operate
+normally. On some tape devices, however, @command{tar} cannot figure
+out the record size itself. On most of those, you can specify a
+blocking factor (with @option{--blocking-factor}) larger than the
+actual blocking factor, and then use the @option{--read-full-records}
+(@option{-B}) option. (If you specify a blocking factor with
address@hidden and don't use the
address@hidden option, then @command{tar} will not
+attempt to figure out the recording size itself.) On some devices,
+you must always specify the record size exactly with
address@hidden when reading, because @command{tar} cannot
+figure it out. In any case, use @option{--list} (@option{-t}) before
+doing any extractions to see whether @command{tar} is reading the archive
+correctly.
+
address@hidden blocks are all fixed size (512 bytes), and its scheme for
+putting them into records is to put a whole number of them (one or
+more) into each record. @command{tar} records are all the same size;
+at the end of the file there's a block containing all zeros, which
+is how you tell that the remainder of the last record(s) are garbage.
+
+In a standard @command{tar} file (no options), the block size is 512
+and the record size is 10240, for a blocking factor of 20. What the
address@hidden option does is sets the blocking factor,
+changing the record size while leaving the block size at 512 bytes.
+20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives;
+most tape drives these days prefer much bigger records in order to
+stream and not waste tape. When writing tapes for myself, some tend
+to use a factor of the order of 2048, say, giving a record size of
+around one megabyte.
+
+If you use a blocking factor larger than 20, older @command{tar}
+programs might not be able to read the archive, so we recommend this
+as a limit to use in practice. @acronym{GNU} @command{tar}, however,
+will support arbitrarily large record sizes, limited only by the
+amount of virtual memory or the physical characteristics of the tape
+device.
+
address@hidden
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
address@hidden menu
+
address@hidden Format Variations
address@hidden Format Variations
address@hidden Format Parameters
address@hidden Format Options
address@hidden Options, archive format specifying
address@hidden Options, format specifying
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Format parameters specify how an archive is written on the archive
+media. The best choice of format parameters will vary depending on
+the type and number of files being archived, and on the media used to
+store the archive.
+
+To specify format parameters when accessing or creating an archive,
+you can use the options described in the following sections.
+If you do not specify any format parameters, @command{tar} uses
+default parameters. You cannot modify a compressed archive.
+If you create an archive with the @option{--blocking-factor} option
+specified (@pxref{Blocking Factor}), you must specify that
+blocking-factor when operating on the archive. @xref{Formats}, for other
+examples of format parameter considerations.
+
address@hidden Blocking Factor
address@hidden The Blocking Factor of an Archive
address@hidden Blocking Factor
address@hidden Record Size
address@hidden Number of blocks per record
address@hidden Number of bytes per record
address@hidden Bytes per record
address@hidden Blocks per record
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden blocking-factor
+The data in an archive is grouped into blocks, which are 512 bytes.
+Blocks are read and written in whole number multiples called
address@hidden The number of blocks in a record (i.e. the size of a
+record in units of 512 bytes) is called the @dfn{blocking factor}.
+The @address@hidden (@option{-b
address@hidden) option specifies the blocking factor of an archive.
+The default blocking factor is typically 20 (i.e., 10240 bytes), but
+can be specified at installation. To find out the blocking factor of
+an existing archive, use @samp{tar --list address@hidden
+This may not work on some devices.
+
+Records are separated by gaps, which waste space on the archive media.
+If you are archiving on magnetic tape, using a larger blocking factor
+(and therefore larger records) provides faster throughput and allows you
+to fit more data on a tape (because there are fewer gaps). If you are
+archiving on cartridge, a very large blocking factor (say 126 or more)
+greatly increases performance. A smaller blocking factor, on the other
+hand, may be useful when archiving small files, to avoid archiving lots
+of nulls as @command{tar} fills out the archive to the end of the record.
+In general, the ideal record size depends on the size of the
+inter-record gaps on the tape you are using, and the average size of the
+files you are archiving. @xref{create}, for information on
+writing archives.
+
address@hidden
address@hidden
+
+
+Archives with blocking factors larger than 20 cannot be read
+by very old versions of @command{tar}, or by some newer versions
+of @command{tar} running on old machines with small address spaces.
+With @acronym{GNU} @command{tar}, the blocking factor of an archive is limited
+only by the maximum record size of the device containing the archive,
+or by the amount of available virtual memory.
+
+Also, on some systems, not using adequate blocking factors, as sometimes
+imposed by the device drivers, may yield unexpected diagnostics. For
+example, this has been reported:
+
address@hidden
+Cannot write to /dev/dlt: Invalid argument
address@hidden smallexample
+
address@hidden
+In such cases, it sometimes happen that the @command{tar} bundled by
+the system is aware of block size idiosyncrasies, while @acronym{GNU}
@command{tar}
+requires an explicit specification for the block size,
+which it cannot guess. This yields some people to consider
address@hidden @command{tar} is misbehaving, because by comparison,
address@hidden bundle @command{tar} works OK}. Adding @address@hidden 256}},
+for example, might resolve the problem.
+
+If you use a non-default blocking factor when you create an archive, you
+must specify the same blocking factor when you modify that archive. Some
+archive devices will also require you to specify the blocking factor when
+reading that archive, however this is not typically the case. Usually, you
+can use @option{--list} (@option{-t}) without specifying a blocking
address@hidden
+reports a non-default record size and then lists the archive members as
+it would normally. To extract files from an archive with a non-standard
+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}.
address@hidden, for more information on the @option{--list} (@option{-t})
+operation. @xref{Reading}, for a more detailed explanation of that option.
+
address@hidden @option
address@hidden address@hidden
address@hidden -b @var{number}
+Specifies the blocking factor of an archive. Can be used with any
+operation, but is usually not necessary with @option{--list} (@option{-t}).
address@hidden table
+
+Device blocking
+
address@hidden @option
address@hidden -b @var{blocks}
address@hidden address@hidden
+Set record size to @address@hidden * 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
+of the archive in records of @address@hidden bytes. This is true
+even when the archive is compressed. Some devices requires that all
+write operations be a multiple of a certain size, and so, @command{tar}
+pads the archive out to the next record boundary.
+
+The default blocking factor is set when @command{tar} is compiled, and is
+typically 20. Blocking factors larger than 20 cannot be read by very
+old versions of @command{tar}, or by some newer versions of @command{tar}
+running on old machines with small address spaces.
+
+With a magnetic tape, larger records give faster throughput and fit
+more data on a tape (because there are fewer inter-record gaps).
+If the archive is in a disk file or a pipe, you may want to specify
+a smaller blocking factor, since a large one will result in a large
+number of null bytes at the end of the archive.
+
+When writing cartridge or other streaming tapes, a much larger
+blocking factor (say 126 or more) will greatly increase performance.
+However, you must specify the same blocking factor when reading or
+updating the archive.
+
+Apparently, Exabyte drives have a physical block size of 8K bytes.
+If we choose our blocksize as a multiple of 8k bytes, then the problem
+seems to disappear. Id est, we are using block size of 112 right
+now, and we haven't had the problem since we address@hidden
+
+With @acronym{GNU} @command{tar} the blocking factor is limited only
+by the maximum record size of the device containing the archive, or by
+the amount of available virtual memory.
+
+However, deblocking or reblocking is virtually avoided in a special
+case which often occurs in practice, but which requires all the
+following conditions to be simultaneously true:
address@hidden @bullet
address@hidden
+the archive is subject to a compression option,
address@hidden
+the archive is not handled through standard input or output, nor
+redirected nor piped,
address@hidden
+the archive is directly handled to a local disk, instead of any special
+device,
address@hidden
address@hidden is not explicitly specified on the @command{tar}
+invocation.
address@hidden itemize
+
+If the output goes directly to a local disk, and not through
+stdout, then the last write is not extended to a full record size.
+Otherwise, reblocking occurs. Here are a few other remarks on this
+topic:
+
address@hidden @bullet
+
address@hidden
address@hidden will complain about trailing garbage if asked to
+uncompress a compressed archive on tape, there is an option to turn
+the message off, but it breaks the regularity of simply having to use
address@hidden@var{prog} -d} for decompression. It would be nice if gzip was
+silently ignoring any number of trailing zeros. I'll ask Jean-loup
+Gailly, by sending a copy of this message to him.
+
address@hidden
address@hidden does not show this problem, but as Jean-loup pointed
+out to Michael, @samp{compress -d} silently adds garbage after
+the result of decompression, which tar ignores because it already
+recognized its end-of-file indicator. So this bug may be safely
+ignored.
+
address@hidden
address@hidden -d -q} will be silent about the trailing zeros indeed,
+but will still return an exit status of 2 which tar reports in turn.
address@hidden might ignore the exit status returned, but I hate doing
+that, as it weakens the protection @command{tar} offers users against
+other possible problems at decompression time. If @command{gzip} was
+silently skipping trailing zeros @emph{and} also avoiding setting the
+exit status in this innocuous case, that would solve this situation.
+
address@hidden
address@hidden should become more solid at not stopping to read a pipe at
+the first null block encountered. This inelegantly breaks the pipe.
address@hidden should rather drain the pipe out before exiting itself.
address@hidden itemize
+
address@hidden address@hidden, short description}
address@hidden -i
address@hidden --ignore-zeros
+Ignore blocks of zeros in archive (means EOF).
+
+The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to
ignore blocks
+of zeros in the archive. Normally a block of zeros indicates the
+end of the archive, but when reading a damaged archive, or one which
+was created by concatenating several archives together, this option
+allows @command{tar} to read the entire archive. This option is not on
+by default because many versions of @command{tar} write garbage after
+the zeroed blocks.
+
+Note that this option causes @command{tar} to read to the end of the
+archive file, which may sometimes avoid problems when multiple files
+are stored on a single physical tape.
+
address@hidden address@hidden, short description}
address@hidden -B
address@hidden --read-full-records
+Reblock as we read (for reading 4.2BSD pipes).
+
+If @option{--read-full-records} is used, @command{tar}
+will not panic if an attempt to read a record from the archive does
+not return a full record. Instead, @command{tar} will keep reading
+until it has obtained a full
+record.
+
+This option is turned on by default when @command{tar} is reading
+an archive from standard input, or from a remote machine. This is
+because on BSD Unix systems, a read of a pipe will return however
+much happens to be in the pipe, even if it is less than @command{tar}
+requested. If this option was not used, @command{tar} would fail as
+soon as it read an incomplete record from the pipe.
+
+This option is also useful with the commands for updating an archive.
+
address@hidden table
+
+Tape blocking
+
address@hidden
address@hidden
+
+
address@hidden blocking factor
address@hidden tape blocking
+
+When handling various tapes or cartridges, you have to take care of
+selecting a proper blocking, that is, the number of disk blocks you
+put together as a single tape block on the tape, without intervening
+tape gaps. A @dfn{tape gap} is a small landing area on the tape
+with no information on it, used for decelerating the tape to a
+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.
+
address@hidden Exabyte blocking
address@hidden DAT blocking
+Using higher blocking (putting more disk blocks per tape block) will use
+the tape more efficiently as there will be less tape gaps. But reading
+such tapes may be more difficult for the system, as more memory will be
+required to receive at once the whole record. Further, if there is a
+reading error on a huge record, this is less likely that the system will
+succeed in recovering the information. So, blocking should not be too
+low, nor it should be too high. @command{tar} uses by default a blocking of
+20 for historical reasons, and it does not really matter when reading or
+writing to disk. Current tape technology would easily accommodate higher
+blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs.
+We were told that for some DLT drives, the blocking should be a multiple
+of 4Kb, preferably 64Kb (@address@hidden 128}}) or 256 for decent performance.
+Other manufacturers may use different recommendations for the same tapes.
+This might also depends of the buffering techniques used inside modern
+tape controllers. Some imposes a minimum blocking, or a maximum blocking.
+Others request blocking to be some exponent of two.
+
+So, there is no fixed rule for blocking. But blocking at read time
+should ideally be the same as blocking used at write time. At one place
+I know, with a wide variety of equipment, they found it best to use a
+blocking of 32 to guarantee that their tapes are fully interchangeable.
+
+I was also told that, for recycled tapes, prior erasure (by the same
+drive unit that will be used to create the archives) sometimes lowers
+the error rates observed at rewriting time.
+
+I might also use @option{--number-blocks} instead of
address@hidden, so @option{--block} will then expand to
address@hidden unambiguously.
+
address@hidden Many
address@hidden Many Archives on One Tape
+
address@hidden
address@hidden
+
+
address@hidden ntape @r{device}
+Most tape devices have two entries in the @file{/dev} directory, or
+entries that come in pairs, which differ only in the minor number for
+this device. Let's take for example @file{/dev/tape}, which often
+points to the only or usual tape device of a given system. There might
+be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler
+name is the @emph{rewinding} version of the device, while the name
+having @samp{nr} in it is the @emph{no rewinding} version of the same
+device.
+
+A rewinding tape device will bring back the tape to its beginning point
+automatically when this device is opened or closed. Since @command{tar}
+opens the archive file before using it and closes it afterwards, this
+means that a simple:
+
address@hidden
+$ @kbd{tar cf /dev/tape @var{directory}}
address@hidden smallexample
+
address@hidden
+will reposition the tape to its beginning both prior and after saving
address@hidden contents to it, thus erasing prior tape contents and
+making it so that any subsequent write operation will destroy what has
+just been saved.
+
address@hidden tape positioning
+So, a rewinding device is normally meant to hold one and only one file.
+If you want to put more than one @command{tar} archive on a given tape, you
+will need to avoid using the rewinding version of the tape device. You
+will also have to pay special attention to tape positioning. Errors in
+positioning may overwrite the valuable data already on your tape. Many
+people, burnt by past experiences, will only use rewinding devices and
+limit themselves to one file per tape, precisely to avoid the risk of
+such errors. Be fully aware that writing at the wrong position on a
+tape loses all information past this point and most probably until the
+end of the tape, and this destroyed information @emph{cannot} be
+recovered.
+
+To save @var{directory-1} as a first archive at the beginning of a
+tape, and leave that tape ready for a second archive, you should use:
+
address@hidden
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{tar cf /dev/nrtape @var{directory-1}}
address@hidden smallexample
+
address@hidden tape marks
address@hidden marks} are special magnetic patterns written on the tape
+media, which are later recognizable by the reading hardware. These
+marks are used after each file, when there are many on a single tape.
+An empty file (that is to say, two tape marks in a row) signal the
+logical end of the tape, after which no file exist. Usually,
+non-rewinding tape device drivers will react to the close request issued
+by @command{tar} by first writing two tape marks after your archive, and by
+backspacing over one of these. So, if you remove the tape at that time
+from the tape drive, it is properly terminated. But if you write
+another file at the current position, the second tape mark will be
+erased by the new information, leaving only one tape mark between files.
+
+So, you may now save @var{directory-2} as a second archive after the
+first on the same tape by issuing the command:
+
address@hidden
+$ @kbd{tar cf /dev/nrtape @var{directory-2}}
address@hidden smallexample
+
address@hidden
+and so on for all the archives you want to put on the same tape.
+
+Another usual case is that you do not write all the archives the same
+day, and you need to remove and store the tape between two archive
+sessions. In general, you must remember how many files are already
+saved on your tape. Suppose your tape already has 16 files on it, and
+that you are ready to write the 17th. You have to take care of skipping
+the first 16 tape marks before saving @var{directory-17}, say, by using
+these commands:
+
address@hidden
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{mt -f /dev/nrtape fsf 16}
+$ @kbd{tar cf /dev/nrtape @var{directory-17}}
address@hidden smallexample
+
+In all the previous examples, we put aside blocking considerations, but
+you should do the proper things for that as well. @xref{Blocking}.
+
address@hidden
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
address@hidden menu
+
address@hidden Tape Positioning
address@hidden Tape Positions and Tape Marks
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Just as archives can store more than one file from the file system,
+tapes can store more than one archive file. To keep track of where
+archive files (or any other type of file stored on tape) begin and
+end, tape archive devices write magnetic @dfn{tape marks} on the
+archive media. Tape drives write one tape mark between files,
+two at the end of all the file entries.
+
+If you think of data as a series of records "rrrr"'s, and tape marks as
+"*"'s, a tape might look like the following:
+
address@hidden
+rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
address@hidden smallexample
+
+Tape devices read and write tapes using a read/write @dfn{tape
+head}---a physical part of the device which can only access one
+point on the tape at a time. When you use @command{tar} to read or
+write archive data from a tape device, the device will begin reading
+or writing from wherever on the tape the tape head happens to be,
+regardless of which archive or what part of the archive the tape
+head is on. Before writing an archive, you should make sure that no
+data on the tape will be overwritten (unless it is no longer needed).
+Before reading an archive, you should make sure the tape head is at
+the beginning of the archive you want to read. You can do it manually
+via @code{mt} utility (@pxref{mt}). The @code{restore} script does
+that automatically (@pxref{Scripted Restoration}).
+
+If you want to add new archive file entries to a tape, you should
+advance the tape to the end of the existing file entries, backspace
+over the last tape mark, and write the new archive file. If you were
+to add two archives to the example above, the tape might look like the
+following:
+
address@hidden
+rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
address@hidden smallexample
+
address@hidden mt
address@hidden The @command{mt} Utility
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
address@hidden Factor}.
+
+You can use the @command{mt} utility to advance or rewind a tape past a
+specified number of archive files on the tape. This will allow you
+to move to the beginning of an archive before extracting or reading
+it, or to the end of all the archives before writing a new one.
address@hidden
address@hidden
+
+
+The syntax of the @command{mt} command is:
+
address@hidden
address@hidden [-f @var{tapename}] @var{operation} address@hidden
address@hidden smallexample
+
+where @var{tapename} is the name of the tape device, @var{number} is
+the number of times an operation is performed (with a default of one),
+and @var{operation} is one of the following:
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden eof
address@hidden weof
+Writes @var{number} tape marks at the current position on the tape.
+
address@hidden fsf
+Moves tape position forward @var{number} files.
+
address@hidden bsf
+Moves tape position back @var{number} files.
+
address@hidden rewind
+Rewinds the tape. (Ignores @var{number}).
+
address@hidden offline
address@hidden rewoff1
+Rewinds the tape and takes the tape device off-line. (Ignores @var{number}).
+
address@hidden status
+Prints status information about the tape unit.
+
address@hidden table
+
address@hidden
address@hidden
+
+
+If you don't specify a @var{tapename}, @command{mt} uses the environment
+variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
+the default device specified in your @file{sys/mtio.h} file
+(@code{DEFTAPE} variable). If this is not defined, the program will
+display a descriptive error message and exit with code 1.
+
address@hidden returns a 0 exit status when the operation(s) were
+successful, 1 if the command was unrecognized, and 2 if an operation
+failed.
+
address@hidden Using Multiple Tapes
address@hidden Using Multiple Tapes
+
+Often you might want to write a large archive, one larger than will fit
+on the actual tape you are using. In such a case, you can run multiple
address@hidden commands, but this can be inconvenient, particularly if you
+are using options like @address@hidden or dumping entire file systems.
+Therefore, @command{tar} provides a special mode for creating
+multi-volume archives.
+
address@hidden archive is a single @command{tar} archive, stored
+on several media volumes of fixed size. Although in this section we will
+often call @samp{volume} a @dfn{tape}, there is absolutely no
+requirement for multi-volume archives to be stored on tapes. Instead,
+they can use whatever media type the user finds convenient, they can
+even be located on files.
+
+When creating a multi-volume arvhive, @acronym{GNU} @command{tar} continues to
fill
+current volume until it runs out of space, then it switches to
+next volume (usually the operator is queried to replace the tape on
+this point), and continues working on the new volume. This operation
+continues untill all requested files are dumped. If @acronym{GNU}
@command{tar} detects
+end of media while dumping a file, such a file is archived in split
+form. Some very big files can even be split across several volumes.
+
+Each volume is itself a valid @acronym{GNU} @command{tar} archive, so it can
be read
+without any special options. Consequently any file member residing
+entirely on one volume can be extracted or otherwise operated upon
+without needing the other volume. Sure enough, to extract a split
+member you would need all volumes its parts reside on.
+
+Multi-volume archives suffer from several limitations. In particular,
+they cannot be compressed.
+
address@hidden @command{tar} is able to create multi-volume archives of two
formats
+(@pxref{Formats}): @samp{GNU} and @samp{POSIX}.
+
address@hidden
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
address@hidden menu
+
address@hidden Multi-Volume Archives
address@hidden Archives Longer than One Tape or Disk
address@hidden Multi-volume archives
+
address@hidden multi-volume
+To create an archive that is larger than will fit on a single unit of
+the media, use the @option{--multi-volume} (@option{-M}) option in conjunction
with
+the @option{--create} option (@pxref{create}). A @dfn{multi-volume}
+archive can be manipulated like any other archive (provided the
address@hidden option is specified), but is stored on more
+than one tape or disk.
+
+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
+the end of the media (when writing). Instead, it prompts you to load
+a new storage volume. If the archive is on a magnetic tape, you
+should change tapes when you see the prompt; if the archive is on a
+floppy disk, you should change disks; etc.
+
address@hidden @option
address@hidden --multi-volume
address@hidden -M
+Creates a multi-volume archive, when used in conjunction with
address@hidden (@option{-c}). To perform any other operation on a multi-volume
+archive, specify @option{--multi-volume} in conjunction with that
+operation.
+For example:
+
address@hidden
+$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}}
address@hidden smallexample
address@hidden table
+
+The method @command{tar} uses to detect end of tape is not perfect, and
+fails on some operating systems or on some devices. If @command{tar}
+cannot detect the end of the tape itself, you can use
address@hidden option to inform it about the capacity of the
+tape:
+
address@hidden
address@hidden @option
address@hidden tape-length
address@hidden address@hidden
address@hidden -L @var{size}
+Set maximum length of a volume. The @var{size} argument should then
+be the usable size of the tape in units of 1024 bytes. This option
+selects @option{--multi-volume} automatically. For example:
+
address@hidden
+$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}}
address@hidden smallexample
address@hidden table
+
address@hidden volume prompt}
+When @acronym{GNU} @command{tar} comes to the end of a storage media, it asks
you to
+change the volume. The built-in prompt for POSIX locale
address@hidden you run @acronym{GNU} @command{tar} under a different locale, the
+translation to the locale's language will be used.}:
+
address@hidden
+Prepare volume address@hidden for address@hidden' and hit return:
address@hidden smallexample
+
address@hidden
+where @var{n} is the ordinal number of the volume to be created and
address@hidden is archive file or device name.
+
+When prompting for a new tape, @command{tar} accepts any of the following
+responses:
+
address@hidden @kbd
address@hidden ?
+Request @command{tar} to explain possible responses
address@hidden q
+Request @command{tar} to exit immediately.
address@hidden n @var{file-name}
+Request @command{tar} to write the next volume on the file @var{file-name}.
address@hidden !
+Request @command{tar} to run a subshell. This option can be disabled
+by giving @option{--restrict} command line option to
address@hidden@address@hidden, for more information about
+this option}.
address@hidden y
+Request @command{tar} to begin writing the next volume.
address@hidden table
+
+(You should only type @samp{y} after you have changed the tape;
+otherwise @command{tar} will write over the volume it just finished.)
+
address@hidden Volume number file
address@hidden volno file
address@hidden
address@hidden volno-file
+The volume number used by @command{tar} in its tape-changing prompt
+can be changed; if you give the
address@hidden@var{file-of-number}} option, then
address@hidden should be an unexisting file to be created, or
+else, a file already containing a decimal number. That number will be
+used as the volume number of the first volume written. When
address@hidden is finished, it will rewrite the file with the
+now-current volume number. (This does not change the volume number
+written on a tape label, as per @ref{label}, it @emph{only} affects
+the number used in the prompt.)
+
address@hidden End-of-archive info script
address@hidden Info script
address@hidden
address@hidden info-script
address@hidden new-volume-script
+If you want more elaborate behavior than this, you can write a special
address@hidden volume script}, that will be responsible for changing the
+volume, and instruct @command{tar} to use it instead of its normal
+prompting procedure:
+
address@hidden @option
address@hidden address@hidden
address@hidden address@hidden
address@hidden -F @var{script-name}
+Specify the full name of the volume script to use. The script can be
+used to eject cassettes, or to broadcast messages such as
address@hidden please come change my tape} when performing unattended
+backups.
address@hidden table
+
+The @var{script-name} is executed without any command line
+arguments. It inherits @command{tar}'s shell environment.
+Additional data is passed to it via the following
+environment variables:
+
address@hidden @env
address@hidden TAR_VERSION, info script environment variable
address@hidden TAR_VERSION
address@hidden @command{tar} version number.
+
address@hidden TAR_ARCHIVE, info script environment variable
address@hidden TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
address@hidden TAR_VOLUME, info script environment variable
address@hidden TAR_VOLUME
+Ordinal number of the volume @command{tar} is about to start.
+
address@hidden TAR_SUBCOMMAND, info script environment variable
address@hidden TAR_SUBCOMMAND
+Short option describing the operation @command{tar} is executing
address@hidden, for a complete list of subcommand options.
+
address@hidden TAR_FORMAT, info script environment variable
address@hidden TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
address@hidden table
+
+The volume script can instruct @command{tar} to use new archive name,
+by writing in to file descriptor 3 (see below for an example).
+
+If the info script fails, @command{tar} exits; otherwise, it begins
+writing the next volume.
+
+If you want @command{tar} to cycle through a series of files or tape
+drives, there are three approaches to choose from. First of all, you
+can give @command{tar} multiple @option{--file} options. In this case
+the specified files will be used, in sequence, as the successive
+volumes of the archive. Only when the first one in the sequence needs
+to be used again will @command{tar} prompt for a tape change (or run
+the info script). For example, suppose someone has two tape drives on
+a system named @file{/dev/tape0} and @file{/dev/tape1}. For having
address@hidden @command{tar} to switch to the second drive when it needs to
write the
+second tape, and then back to the first tape, etc., just do either of:
+
address@hidden
+$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1
@var{files}}
+$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
address@hidden smallexample
+
+The second method is to use the @samp{n} response to the tape-change
+prompt.
+
+Finally, the most flexible approach is to use a volume script, that
+writes new archive name to the file descriptor #3. For example, the
+following volume script will create a series of archive files, named
address@hidden@address@hidden, where @var{archive} is the name of the
+archive being created (as given by @option{--file} option) and
address@hidden is the ordinal number of the archive being created:
+
address@hidden
address@hidden
+#! /bin/sh
+echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+
+name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+case $TAR_SUBCOMMAND in
+-c) ;;
+-d|-x|-t) test -r address@hidden:address@hidden || exit 1
+ ;;
+*) exit 1
+esac
+
+echo address@hidden:address@hidden >&3
address@hidden group
address@hidden smallexample
+
+The same script cant be used while listing, comparing or extracting
+from the created archive. For example:
+
address@hidden
address@hidden
+# @r{Create a multi-volume archive:}
+$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .}
+# @r{Extract from the created archive:}
+$ @kbd{tar -x -f archive.tar -F new-volume .}
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that the first command had to use @option{-L} option, since
+otherwise @acronym{GNU} @command{tar} will end up writing everything to file
address@hidden
+
+You can read each individual volume of a multi-volume archive as if it
+were an archive by itself. For example, to list the contents of one
+volume, use @option{--list}, without @option{--multi-volume} specified.
+To extract an archive member from one volume (assuming it is described
+that volume), use @option{--extract}, again without
address@hidden
+
+If an archive member is split across volumes (i.e. its entry begins on
+one volume of the media and ends on another), you need to specify
address@hidden to extract it successfully. In this case, you
+should load the volume where the archive member starts, and use
address@hidden --extract address@hidden will prompt for later
+volumes as it needs them. @xref{extracting archives}, for more
+information about extracting archives.
+
+Multi-volume archives can be modified like any other archive. To add
+files to a multi-volume archive, you need to only mount the last
+volume of the archive media (and new volumes, if needed). For all
+other operations, you need to use the entire archive.
+
+If a multi-volume archive was labeled using
address@hidden@var{archive-label}} (@pxref{label}) when it was
+created, @command{tar} will not automatically label volumes which are
+added later. To label subsequent volumes, specify
address@hidden@var{archive-label}} again in conjunction with the
address@hidden, @option{--update} or @option{--concatenate} operation.
+
+Notice that multi-volume support is a GNU extension and the archives
+created in this mode should be read only using @acronym{GNU} @command{tar}.
If you
+absolutely have to process such archives using a third-party @command{tar}
+implementation, read @ref{Split Recovery}.
+
address@hidden Tape Files
address@hidden Tape Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+To give the archive a name which will be recorded in it, use the
address@hidden@var{volume-label}} (@option{-V @var{volume-label}})
+option. This will write a special block identifying
address@hidden as the name of the archive to the front of the
+archive which will be displayed when the archive is listed with
address@hidden If you are creating a multi-volume archive with
address@hidden (@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 @address@hidden) option when
+reading an archive, it checks to make sure the label on the tape
+matches the one you give. @xref{label}.
+
+When @command{tar} writes an archive to tape, it creates a single
+tape file. If multiple archives are written to the same tape, one
+after the other, they each get written as separate tape files. When
+extracting, it is necessary to position the tape at the right place
+before running @command{tar}. To do this, use the @command{mt} command.
+For more information on the @command{mt} command and on the organization
+of tapes into a sequence of tape files, see @ref{mt}.
+
+People seem to often do:
+
address@hidden
address@hidden"@var{some-prefix} `date address@hidden"}
address@hidden smallexample
+
+or such, for pushing a common date in all volumes or an archive set.
+
address@hidden Tarcat
address@hidden Concatenate Volumes into a Single Archive
+
address@hidden tarcat
+ Sometimes it is necessary to convert existing @acronym{GNU} @command{tar}
multi-volume
+archive to a single @command{tar} archive. Simply concatenating all
+volumes into one will not work, since each volume carries an additional
+information at the beginning. @acronym{GNU} @command{tar} is shipped with the
shell
+script @command{tarcat} designed for this purpose.
+
+ The script takes a list of files comprising a multi-volume archive
+and creates the resulting archive at the standard output. For example:
+
address@hidden
address@hidden vol.1 vol.2 vol.3 | tar tf -}
address@hidden smallexample
+
+ The script implements a simple heuristics to determine the format of
+the first volume file and to decide how to process the rest of the
+files. However, it makes no attempt to verify whether the files are
+given in order or even if they are valid @command{tar} archives.
+It uses @command{dd} and does not filter its standard error, so you
+will usually see lots of spurious messages.
+
address@hidden
address@hidden
+
+
address@hidden label
address@hidden Including a Label in the Archive
address@hidden Labeling an archive
address@hidden Labels on the archive media
address@hidden Labeling multi-volume archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden label
+ To avoid problems caused by misplaced paper labels on the archive
+media, you can include a @dfn{label} entry---an archive member which
+contains the name of the archive---in the archive itself. Use the
address@hidden@var{archive-label}} (@option{-V @var{archive-label}})
+option in conjunction with the @option{--create} operation to include
+a label entry in the archive as it is being created.
+
address@hidden @option
address@hidden address@hidden
address@hidden -V @var{archive-label}
+Includes an @dfn{archive-label} at the beginning of the archive when
+the archive is being created, when used in conjunction with the
address@hidden operation. Checks to make sure the archive label
+matches the one specified (when used in conjunction with any other
+operation.
address@hidden table
+
+ If you create an archive using both
address@hidden@var{archive-label}} (@option{-V @var{archive-label}})
+and @option{--multi-volume} (@option{-M}), each volume of the archive
+will have an archive label of the form @address@hidden
+Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
+next, and so on. @xref{Using Multiple Tapes}, for information on
+creating multiple volume archives.
+
address@hidden Volume label, listing
address@hidden Listing volume label
+ The volume label will be displayed by @option{--list} along with
+the file contents. If verbose display is requested, it will also be
+explicitely marked as in the example below:
+
address@hidden
address@hidden
+$ @kbd{tar --verbose --list --file=iamanarchive}
+V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
address@hidden group
address@hidden smallexample
+
address@hidden test-label
address@hidden option}
+ However, @option{--list} option will cause listing entire
+contents of the archive, which may be undesirable (for example, if the
+archive is stored on a tape). You can request checking only the volume
+by specifying @option{--test-label} option. This option reads only the
+first block of an archive, so it can be used with slow storage
+devices. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --test-label --file=iamanarchive}
+iamalabel
address@hidden group
address@hidden smallexample
+
+ If @option{--test-label} is used with a single command line
+argument, @command{tar} compares the volume label with the
+argument. It exits with code 0 if the two strings match, and with code
+2 otherwise. In this case no output is displayed. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
address@hidden 0
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
address@hidden 1
address@hidden group
address@hidden smallexample
+
+ If you request any operation, other than @option{--create}, along
+with using @option{--label} option, @command{tar} will first check if
+the archive label matches the one specified and will refuse to proceed
+if it does not. Use this as a safety precaution to avoid accidentally
+overwriting existing archives. For example, if you wish to add files
+to @file{archive}, presumably labelled with string @samp{My volume},
+you will get:
+
address@hidden
address@hidden
+$ @kbd{tar -rf archive --label 'My volume' .}
+tar: Archive not labeled to match `My volume'
address@hidden group
address@hidden smallexample
+
address@hidden
+in case its label does not match. This will work even if
address@hidden is not labelled at all.
+
+ Similarly, @command{tar} will refuse to list or extract the
+archive if its label doesn't match the @var{archive-label}
+specified. In those cases, @var{archive-label} argument is interpreted
+as a globbing-style pattern which must match the actual magnetic
+volume label. @xref{exclude}, for a precise description of how match
+is address@hidden versions of @command{tar} used full
+regular expression matching, or before that, only exact string
+matching, instead of wildcard matchers. We decided for the sake of
+simplicity to use a uniform matching device through
address@hidden If the switch @option{--multi-volume} (@option{-M}) is being
used,
+the volume label matcher will also suffix @var{archive-label} by
address@hidden@samp{ Volume [1-9]*}} if the initial match fails, before giving
+up. Since the volume numbering is automatically added in labels at
+creation time, it sounded logical to equally help the user taking care
+of it when the archive is being read.
+
+ The @option{--label} was once called @option{--volume}, but is not
+available under that name anymore.
+
+ You can also use @option{--label} to get a common information on
+all tapes of a series. For having this information different in each
+series created through a single script used on a regular basis, just
+manage to get some date string as part of the label. For example:
+
address@hidden
address@hidden
+$ @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`"}
address@hidden group
address@hidden smallexample
+
+ Also note that each label has its own date and time, which corresponds
+to when @acronym{GNU} @command{tar} initially attempted to write it,
+often soon after the operator launches @command{tar} or types the
+carriage return telling that the next tape is ready. Comparing date
+labels does give an idea of tape throughput only if the delays for
+rewinding tapes and the operator switching them were negligible, which
+is usually not the case.
+
address@hidden verify
address@hidden Verifying Data as It is Stored
address@hidden Verifying a write operation
address@hidden Double-checking a write operation
+
address@hidden @option
address@hidden -W
address@hidden --verify
address@hidden verify, short description
+Attempt to verify the archive after writing.
address@hidden table
+
+This option causes @command{tar} to verify the archive after writing it.
+Each volume is checked after it is written, and any discrepancies
+are recorded on the standard error output.
+
+Verification requires that the archive be on a back-space-able medium.
+This means pipes, some cartridge tape drives, and some other devices
+cannot be verified.
+
+You can insure the accuracy of an archive by comparing files in the
+system with archive members. @command{tar} can compare an archive to the
+file system as the archive is being written, to verify a write
+operation, or can compare a previously written archive, to insure that
+it is up to date.
+
address@hidden address@hidden, using with @option{--create}}
address@hidden address@hidden, using with @option{--verify}}
+To check for discrepancies in an archive immediately after it is
+written, use the @option{--verify} (@option{-W}) option in conjunction with
+the @option{--create} operation. When this option is
+specified, @command{tar} checks archive members against their counterparts
+in the file system, and reports discrepancies on the standard error.
+
+To verify an archive, you must be able to read it from before the end
+of the last written entry. This option is useful for detecting data
+errors on some tapes. Archives written to pipes, some cartridge tape
+drives, and some other devices cannot be verified.
+
+One can explicitly compare an already made archive with the file
+system by using the @option{--compare} (@option{--diff}, @option{-d})
+option, instead of using the more automatic @option{--verify} option.
address@hidden
+
+Note that these two options have a slightly different intent. The
address@hidden option checks how identical are the logical contents of some
+archive with what is on your disks, while the @option{--verify} option is
+really for checking if the physical contents agree and if the recording
+media itself is of dependable quality. So, for the @option{--verify}
+operation, @command{tar} tries to defeat all in-memory cache pertaining to
+the archive, while it lets the speed optimization undisturbed for the
address@hidden option. If you nevertheless use @option{--compare} for
+media verification, you may have to defeat the in-memory cache yourself,
+maybe by opening and reclosing the door latch of your recording unit,
+forcing some doubt in your operating system about the fact this is really
+the same volume as the one just written or read.
+
+The @option{--verify} option would not be necessary if drivers were indeed
+able to detect dependably all write failures. This sometimes require many
+magnetic heads, some able to read after the writes occurred. One would
+not say that drivers unable to detect all cases are necessarily flawed,
+as long as programming is concerned.
+
+The @option{--verify} (@option{-W}) option will not work in
+conjunction with the @option{--multi-volume} (@option{-M}) option or
+the @option{--append} (@option{-r}), @option{--update} (@option{-u})
+and @option{--delete} operations. @xref{Operations}, for more
+information on these operations.
+
+Also, since @command{tar} normally strips leading @samp{/} from file
+names (@pxref{absolute}), a command like @samp{tar --verify -cf
+/tmp/foo.tar /etc} will work as desired only if the working directory is
address@hidden/}, as @command{tar} uses the archive's relative member names
+(e.g., @file{etc/motd}) when verifying the archive.
+
address@hidden Write Protection
address@hidden Write Protection
+
+Almost all tapes and diskettes, and in a few rare cases, even disks can
+be @dfn{write protected}, to protect data on them from being changed.
+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).
+
+The write protection device itself is usually an integral part of the
+physical media, and can be a two position (write enabled/write
+disabled) switch, a notch which can be popped out or covered, a ring
+which can be removed from the center of a tape reel, or some other
+changeable feature.
+
address@hidden Changes
address@hidden Changes
+
+This appendix lists some important user-visible changes between
+version @acronym{GNU} @command{tar} 1.15.92 and previous versions. An
up-to-date
+version of this document is available at
address@hidden://www.gnu.org/@/software/@/tar/manual/changes.html,the
address@hidden @command{tar} documentation page}.
+
address@hidden @asis
address@hidden Use of globbing patterns when listing and extracting.
+
+Previous versions of GNU tar assumed shell-style globbing when
+extracting from or listing an archive. For example:
+
address@hidden
+$ @kbd{tar xf foo.tar '*.c'}
address@hidden smallexample
+
+would extract all files whose names end in @samp{.c}. This behavior
+was not documented and was incompatible with traditional tar
+implementations. Therefore, starting from version 1.15.91, GNU tar
+no longer uses globbing by default. For example, the above invocation
+is now interpreted as a request to extract from the archive the file
+named @file{*.c}.
+
+To facilitate transition to the new behavior for those users who got
+used to the previous incorrect one, @command{tar} will print a warning
+if it finds out that a requested member was not found in the archive
+and its name looks like a globbing pattern. For example:
+
address@hidden
+$ @kbd{tar xf foo.tar '*.c'}
+tar: Pattern matching characters used in file names. Please,
+tar: use --wildcards to enable pattern matching, or --no-wildcards to
+tar: suppress this warning.
+tar: *.c: Not found in archive
+tar: Error exit delayed from previous errors
address@hidden smallexample
+
+To treat member names as globbing patterns, use --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.
+
address@hidden, for the detailed discussion of the use of globbing
+patterns by @acronym{GNU} @command{tar}.
+
address@hidden Use of short option @option{-o}.
+
+Earlier versions of @acronym{GNU} @command{tar} understood @option{-o} command
line
+option as a synonym for @option{--old-archive}.
+
address@hidden @command{tar} starting from version 1.13.90 understands this
option as
+a synonym for @option{--no-same-owner}. This is compatible with
+UNIX98 @command{tar} implementations.
+
+However, to facilitate transition, @option{-o} option retains its
+old semantics when it is used with one of archive-creation commands.
+Users are encouraged to use @option{--format=oldgnu} instead.
+
+It is especially important, since versions of @acronym{GNU} Automake
+up to and including 1.8.4 invoke tar with this option to produce
+distribution tarballs. @xref{Formats,v7}, for the detailed discussion
+of this issue and its implications.
+
address@hidden
address@hidden
+.
address@hidden, tar-v7, Changing Automake's Behavior,
+automake, GNU Automake}, for a description on how to use various
+archive formats with @command{automake}.
+
+Future versions of @acronym{GNU} @command{tar} will understand @option{-o}
only as a
+synonym for @option{--no-same-owner}.
+
address@hidden Use of short option @option{-l}
+
+Earlier versions of @acronym{GNU} @command{tar} 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,
+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.
+
address@hidden Use of options @option{--portability} and @option{--old-archive}
+
+These options are deprecated. Please use @option{--format=v7} instead.
+
address@hidden Use of option @option{--posix}
+
+This option is deprecated. Please use @option{--format=posix} instead.
address@hidden table
+
address@hidden Configuring Help Summary
address@hidden Configuring Help Summary
+
+Running @kbd{tar --help} displays the short @command{tar} option
+summary (@pxref{help}). This summary is organised by @dfn{groups} of
+semantically close options. The options within each group are printed
+in the following order: a short option, eventually followed by a list
+of corresponding long option names, followed by a short description of
+the option. For example, here is an excerpt from the actual @kbd{tar
+--help} output:
+
address@hidden
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to an archive
+ -c, --create create a new archive
+ -d, --diff, --compare find differences between archive and
+ file system
+ --delete delete from the archive
address@hidden verbatim
+
address@hidden ARGP_HELP_FMT, environment variable
+The exact visual representation of the help output is configurable via
address@hidden environment variable. The value of this variable
+is a comma-separated list of @dfn{format variable} assignments. There
+are two kinds of format variables. An @dfn{offset variable} keeps the
+offset of some part of help output text from the leftmost column on
+the screen. A @dfn{boolean} variable is a flag that toggles some
+output feature on or off. Depending on the type of the corresponding
+variable, there are two kinds of assignments:
+
address@hidden @asis
address@hidden Offset assignment
+
+The assignment to an offset variable has the following syntax:
+
address@hidden
address@hidden@var{value}
address@hidden smallexample
+
address@hidden
+where @var{variable} is the variable name, and @var{value} is a
+numeric value to be assigned to the variable.
+
address@hidden Boolean assignment
+
+To assign @code{true} value to a variable, simply put this variable name. To
+assign @code{false} value, prefix the variable name with @samp{no-}. For
+example:
+
address@hidden
address@hidden
+# Assign @code{true} value:
+dup-args
+# Assign @code{false} value:
+no-dup-args
address@hidden group
address@hidden smallexample
address@hidden table
+
+Following variables are declared:
+
address@hidden {Help Output} boolean dup-args
+If true, arguments for an option are shown with both short and long
+options, even when a given option has both forms, for example:
+
address@hidden
+ -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden smallexample
+
+If false, then if an option has both short and long forms, the
+argument is only shown with the long one, for example:
+
address@hidden
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden smallexample
+
address@hidden
+and a message indicating that the argument is applicable to both
+forms is printed below the options. This message can be disabled
+using @code{dup-args-note} (see below).
+
+The default is false.
address@hidden deftypevr
+
address@hidden {Help Output} boolean dup-args-note
+If this variable is true, which is the default, the following notice
+is displayed at the end of the help output:
+
address@hidden
+Mandatory or optional arguments to long options are also mandatory or
+optional for any corresponding short options.
address@hidden quotation
+
+Setting @code{no-dup-args-note} inhibits this message. Normally, only one of
+variables @code{dup-args} or @code{dup-args-note} should be set.
address@hidden deftypevr
+
address@hidden {Help Output} offset short-opt-col
+Column in which short options start. Default is 2.
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset long-opt-col
+Column in which long options start. Default is 6. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset doc-opt-col
+Column in which @dfn{doc options} start. A doc option isn't actually
+an option, but rather an arbitrary piece of documentation that is
+displayed in much the same manner as the options. For example, in
+the description of @option{--format} option:
+
address@hidden
address@hidden
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
address@hidden group
address@hidden smallexample
+
address@hidden
+the format names are doc options. Thus, if you set
address@hidden the above part of the help output
+will look as follows:
+
address@hidden
address@hidden
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset opt-doc-col
+Column in which option description starts. Default is 29.
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE
+ use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that the description starts on a separate line if
address@hidden value is too small.
address@hidden deftypevr
+
address@hidden {Help Output} offset header-col
+Column in which @dfn{group headers} are printed. A group header is a
+descriptive text preceding an option group. For example, in the
+following text:
+
address@hidden
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to
+ an archive
+ -c, --create create a new archive
address@hidden verbatim
address@hidden
address@hidden operation mode:} is the group header.
+
+The default value is 1.
address@hidden deftypevr
+
address@hidden {Help Output} offset usage-indent
+Indentation of wrapped usage lines. Affects @option{--usage}
+output. Default is 12.
address@hidden deftypevr
+
address@hidden {Help Output} offset rmargin
+Right margin of the text output. Used for wrapping.
address@hidden deftypevr
+
address@hidden Tar Internals
address@hidden Tar Internals
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
address@hidden menu
+
address@hidden Standard
address@hidden Basic Tar Format
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+While an archive may contain many files, the archive itself is a
+single ordinary file. Like any other file, an archive file can be
+written to a storage device such as a tape or disk, sent through a
+pipe or over a network, saved on the active file system, or even
+stored in another archive. An archive file is not easy to read or
+manipulate without using the @command{tar} utility or Tar mode in
address@hidden Emacs.
+
+Physically, an archive consists of a series of file entries terminated
+by an end-of-archive entry, which consists of two 512 blocks of zero
+bytes. A file
+entry usually describes one of the files in the archive (an
address@hidden member}), and consists of a file header and the contents
+of the file. File headers contain file names and statistics, checksum
+information which @command{tar} uses to detect file corruption, and
+information about file types.
+
+Archives are permitted to have more than one member with the same
+member name. One way this situation can occur is if more than one
+version of a file has been stored in the archive. For information
+about adding new versions of a file to an archive, see @ref{update}.
address@hidden
+
+In addition to entries describing archive members, an archive may
+contain entries which @command{tar} itself uses to store information.
address@hidden, for an example of such an archive entry.
+
+A @command{tar} archive file contains a series of blocks. Each block
+contains @code{BLOCKSIZE} bytes. Although this format may be thought
+of as being on magnetic tape, other media are often used.
+
+Each file archived is represented by a header block which describes
+the file, followed by zero or more blocks which give the contents
+of the file. At the end of the archive file there are two 512-byte blocks
+filled with binary zeros as an end-of-file marker. A reasonable system
+should write such end-of-file marker at the end of an archive, but
+must not assume that such a block exists when reading an archive. In
+particular @acronym{GNU} @command{tar} always issues a warning if it does not
encounter it.
+
+The blocks may be @dfn{blocked} for physical I/O operations.
+Each record of @var{n} blocks (where @var{n} is set by the
address@hidden@var{512-size}} (@option{-b @var{512-size}}) option to
@command{tar}) is written with a single
address@hidden@samp{write ()}} operation. On magnetic tapes, the result of
+such a write is a single record. When writing an archive,
+the last record of blocks should be written at the full size, with
+blocks after the zero block containing all zeros. When reading
+an archive, a reasonable system should properly handle an archive
+whose last record is shorter than the rest, or which contains garbage
+records after a zero block.
+
+The header block is defined in C as follows. In the @acronym{GNU}
@command{tar}
+distribution, this is part of file @file{src/tar.h}:
+
address@hidden
address@hidden GNU tar Archive Format description.
address@hidden
address@hidden Copyright (C) 1988, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
1997,
address@hidden 2000, 2001, 2003, 2004, 2005, 2006 Free Software Foundation,
Inc.
address@hidden
address@hidden This program is free software; you can redistribute it and/or
modify it
address@hidden under the terms of the GNU General Public License as published
by the
address@hidden Free Software Foundation; either version 2, or (at your
option) any later
address@hidden version.
address@hidden
address@hidden This program is distributed in the hope that it will be
useful, but
address@hidden WITHOUT ANY WARRANTY; without even the implied warranty of
address@hidden MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General
address@hidden Public License for more details.
address@hidden
address@hidden You should have received a copy of the GNU General Public
License along
address@hidden with this program; if not, write to the Free Software
Foundation, Inc.,
address@hidden 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+/address@hidden tar Header Block, from POSIX 1003.1-1990. }*/
+
+/address@hidden POSIX header. }*/
+
+struct posix_header
address@hidden /address@hidden byte offset }*/
+ char name[100]; /address@hidden 0 }*/
+ char mode[8]; /address@hidden 100 }*/
+ char uid[8]; /address@hidden 108 }*/
+ char gid[8]; /address@hidden 116 }*/
+ char size[12]; /address@hidden 124 }*/
+ char mtime[12]; /address@hidden 136 }*/
+ char chksum[8]; /address@hidden 148 }*/
+ char typeflag; /address@hidden 156 }*/
+ char linkname[100]; /address@hidden 157 }*/
+ char magic[6]; /address@hidden 257 }*/
+ char version[2]; /address@hidden 263 }*/
+ char uname[32]; /address@hidden 265 }*/
+ char gname[32]; /address@hidden 297 }*/
+ char devmajor[8]; /address@hidden 329 }*/
+ char devminor[8]; /address@hidden 337 }*/
+ char prefix[155]; /address@hidden 345 }*/
+ /address@hidden 500 }*/
address@hidden;
+
+#define TMAGIC "ustar" /address@hidden ustar and a null }*/
+#define TMAGLEN 6
+#define TVERSION "00" /address@hidden 00 and no null }*/
+#define TVERSLEN 2
+
+/address@hidden Values used in typeflag field. }*/
+#define REGTYPE '0' /address@hidden regular file }*/
+#define AREGTYPE '\0' /address@hidden regular file }*/
+#define LNKTYPE '1' /address@hidden link }*/
+#define SYMTYPE '2' /address@hidden reserved }*/
+#define CHRTYPE '3' /address@hidden character special }*/
+#define BLKTYPE '4' /address@hidden block special }*/
+#define DIRTYPE '5' /address@hidden directory }*/
+#define FIFOTYPE '6' /address@hidden FIFO special }*/
+#define CONTTYPE '7' /address@hidden reserved }*/
+
+#define XHDTYPE 'x' /address@hidden Extended header referring to
the
+ next file in the archive }*/
+#define XGLTYPE 'g' /address@hidden Global extended header }*/
+
+/address@hidden Bits used in the mode field, values in octal. }*/
+#define TSUID 04000 /address@hidden set UID on execution }*/
+#define TSGID 02000 /address@hidden set GID on execution }*/
+#define TSVTX 01000 /address@hidden reserved }*/
+ /address@hidden file permissions }*/
+#define TUREAD 00400 /address@hidden read by owner }*/
+#define TUWRITE 00200 /address@hidden write by owner }*/
+#define TUEXEC 00100 /address@hidden execute/search by owner }*/
+#define TGREAD 00040 /address@hidden read by group }*/
+#define TGWRITE 00020 /address@hidden write by group }*/
+#define TGEXEC 00010 /address@hidden execute/search by group }*/
+#define TOREAD 00004 /address@hidden read by other }*/
+#define TOWRITE 00002 /address@hidden write by other }*/
+#define TOEXEC 00001 /address@hidden execute/search by other }*/
+
+/address@hidden tar Header Block, GNU extensions. }*/
+
+/address@hidden In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is
for
+ contiguous files, so maybe disobeying the `reserved' comment in POSIX
+ header description. I suspect these were meant to be used this way, and
+ should not have really been `reserved' in the published standards. }*/
+
+/address@hidden *BEWARE* *BEWARE* *BEWARE* that the following information is
still
+ boiling, and may change. Even if the OLDGNU format description should be
+ accurate, the so-called GNU format is not yet fully decided. It is
+ surely meant to use only extensions allowed by POSIX, but the sketch
+ below repeats some ugliness from the OLDGNU format, which should rather
+ go away. Sparse files should be saved in such a way that they do *not*
+ require two passes at archive creation time. Huge files get some POSIX
+ fields to overflow, alternate solutions have to be sought for this. }*/
+
+/address@hidden Descriptor for a single file hole. }*/
+
+struct sparse
address@hidden /address@hidden byte offset }*/
+ char offset[12]; /address@hidden 0 }*/
+ char numbytes[12]; /address@hidden 12 }*/
+ /address@hidden 24 }*/
address@hidden;
+
+/address@hidden Sparse files are not supported in POSIX ustar format. For
sparse files
+ with a POSIX header, a GNU extra header is provided which holds overall
+ sparse information and a few sparse descriptors. When an old GNU header
+ replaces both the POSIX header and the GNU extra header, it holds some
+ sparse descriptors too. Whether POSIX or not, if more sparse descriptors
+ are still needed, they are put into as many successive sparse headers as
+ necessary. The following constants tell how many sparse descriptors fit
+ in each kind of header able to hold them. }*/
+
+#define SPARSES_IN_EXTRA_HEADER 16
+#define SPARSES_IN_OLDGNU_HEADER 4
+#define SPARSES_IN_SPARSE_HEADER 21
+
+/address@hidden Extension header for sparse files, used immediately after the
GNU extra
+ header, and used only if all sparse information cannot fit into that
+ extra header. There might even be many such extension headers, one after
+ the other, until all sparse information has been recorded. }*/
+
+struct sparse_header
address@hidden /address@hidden byte offset }*/
+ struct sparse sp[SPARSES_IN_SPARSE_HEADER];
+ /address@hidden 0 }*/
+ char isextended; /address@hidden 504 }*/
+ /address@hidden 505 }*/
address@hidden;
+
+/address@hidden The old GNU format header conflicts with POSIX format in such
a way that
+ POSIX archives may fool old GNU tar's, and POSIX tar's might well be
+ fooled by old GNU tar archives. An old GNU format header uses the space
+ used by the prefix field in a POSIX header, and cumulates information
+ normally found in a GNU extra header. With an old GNU tar header, we
+ never see any POSIX header nor GNU extra header. Supplementary sparse
+ headers are allowed, however. }*/
+
+struct oldgnu_header
address@hidden /address@hidden byte offset }*/
+ char unused_pad1[345]; /address@hidden 0 }*/
+ char atime[12]; /address@hidden 345 Incr. archive: atime of
the file }*/
+ char ctime[12]; /address@hidden 357 Incr. archive: ctime of
the file }*/
+ char offset[12]; /address@hidden 369 Multivolume archive: the
offset of
+ the start of this volume }*/
+ char longnames[4]; /address@hidden 381 Not used }*/
+ char unused_pad2; /address@hidden 385 }*/
+ struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
+ /address@hidden 386 }*/
+ char isextended; /address@hidden 482 Sparse file: Extension
sparse header
+ follows }*/
+ char realsize[12]; /address@hidden 483 Sparse file: Real size}*/
+ /address@hidden 495 }*/
address@hidden;
+
+/address@hidden OLDGNU_MAGIC uses both magic and version fields, which are
contiguous.
+ Found in an archive, it indicates an old GNU header format, which will be
+ hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are
+ valid, though the header is not truly POSIX conforming. }*/
+#define OLDGNU_MAGIC "ustar " /address@hidden 7 chars and a null }*/
+
+/address@hidden The standards committee allows only capital A through capital
Z for
+ user-defined expansion. Other letters in use include:
+
+ 'A' Solaris Access Control List
+ 'E' Solaris Extended Attribute File
+ 'I' Inode only, as in 'star'
+ 'X' POSIX 1003.1-2001 eXtended (VU version) }*/
+
+/address@hidden This is a dir entry that contains the names of files that were
in the
+ dir at the time the dump was made. }*/
+#define GNUTYPE_DUMPDIR 'D'
+
+/address@hidden Identifies the *next* file on the tape as having a long
linkname. }*/
+#define GNUTYPE_LONGLINK 'K'
+
+/address@hidden Identifies the *next* file on the tape as having a long name.
}*/
+#define GNUTYPE_LONGNAME 'L'
+
+/address@hidden This is the continuation of a file that began on another
volume. }*/
+#define GNUTYPE_MULTIVOL 'M'
+
+/address@hidden For storing filenames that do not fit into the main header.
}*/
+#define GNUTYPE_NAMES 'N'
+
+/address@hidden This is for sparse files. }*/
+#define GNUTYPE_SPARSE 'S'
+
+/address@hidden This file is a tape/volume header. Ignore it on extraction.
}*/
+#define GNUTYPE_VOLHDR 'V'
+
+/address@hidden Solaris extended header }*/
+#define SOLARIS_XHDTYPE 'X'
+
+/address@hidden J@"org Schilling star header }*/
+
+struct star_header
address@hidden /address@hidden byte offset }*/
+ char name[100]; /address@hidden 0 }*/
+ char mode[8]; /address@hidden 100 }*/
+ char uid[8]; /address@hidden 108 }*/
+ char gid[8]; /address@hidden 116 }*/
+ char size[12]; /address@hidden 124 }*/
+ char mtime[12]; /address@hidden 136 }*/
+ char chksum[8]; /address@hidden 148 }*/
+ char typeflag; /address@hidden 156 }*/
+ char linkname[100]; /address@hidden 157 }*/
+ char magic[6]; /address@hidden 257 }*/
+ char version[2]; /address@hidden 263 }*/
+ char uname[32]; /address@hidden 265 }*/
+ char gname[32]; /address@hidden 297 }*/
+ char devmajor[8]; /address@hidden 329 }*/
+ char devminor[8]; /address@hidden 337 }*/
+ char prefix[131]; /address@hidden 345 }*/
+ char atime[12]; /address@hidden 476 }*/
+ char ctime[12]; /address@hidden 488 }*/
+ /address@hidden 500 }*/
address@hidden;
+
+#define SPARSES_IN_STAR_HEADER 4
+#define SPARSES_IN_STAR_EXT_HEADER 21
+
+struct star_in_header
address@hidden
+ char fill[345]; /address@hidden 0 Everything that is before
t_prefix }*/
+ char prefix[1]; /address@hidden 345 t_name prefix }*/
+ char fill2; /address@hidden 346 }*/
+ char fill3[8]; /address@hidden 347 }*/
+ char isextended; /address@hidden 355 }*/
+ struct sparse sp[SPARSES_IN_STAR_HEADER]; /address@hidden 356 }*/
+ char realsize[12]; /address@hidden 452 Actual size of the file }*/
+ char offset[12]; /address@hidden 464 Offset of multivolume contents }*/
+ char atime[12]; /address@hidden 476 }*/
+ char ctime[12]; /address@hidden 488 }*/
+ char mfill[8]; /address@hidden 500 }*/
+ char xmagic[4]; /address@hidden 508 "tar" }*/
address@hidden;
+
+struct star_ext_header
address@hidden
+ struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
+ char isextended;
address@hidden;
+
address@hidden smallexample
+
+All characters in header blocks are represented by using 8-bit
+characters in the local variant of ASCII. Each field within the
+structure is contiguous; that is, there is no padding used within
+the structure. Each character on the archive medium is stored
+contiguously.
+
+Bytes representing the contents of files (after the header block
+of each file) are not translated in any way and are not constrained
+to represent characters in any character set. The @command{tar} format
+does not distinguish text files from binary files, and no translation
+of file contents is performed.
+
+The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
address@hidden are null-terminated character strings. All other fields
+are zero-filled octal numbers in ASCII. Each numeric field of width
address@hidden contains @var{w} minus 1 digits, and a null.
+
+The @code{name} field is the file name of the file, with directory names
+(if any) preceding the file name, separated by slashes.
+
address@hidden
address@hidden
+
+
+The @code{mode} field provides nine bits specifying file permissions
+and three bits to specify the Set UID, Set GID, and Save Text
+(@dfn{sticky}) modes. Values for these bits are defined above.
+When special permissions are required to create a file with a given
+mode, and the user restoring files from the archive does not hold such
+permissions, the mode bit(s) specifying those special permissions
+are ignored. Modes which are not supported by the operating system
+restoring files from the archive will be ignored. Unsupported modes
+should be faked up when creating or updating an archive; e.g., the
+group permission could be copied from the @emph{other} permission.
+
+The @code{uid} and @code{gid} fields are the numeric user and group
+ID of the file owners, respectively. If the operating system does
+not support numeric user or group IDs, these fields should be ignored.
+
+The @code{size} field is the size of the file in bytes; linked files
+are archived with this field specified as zero. @quote-arg
+
+The @code{mtime} field is the data modification time of the file at
+the time it was archived. It is the ASCII representation of the octal
+value of the last time the file's contents were modified, represented
+as an integer number of
+seconds since January 1, 1970, 00:00 Coordinated Universal Time.
+
+The @code{chksum} field is the ASCII representation of the octal value
+of the simple sum of all bytes in the header block. Each 8-bit
+byte in the header is added to an unsigned integer, initialized to
+zero, the precision of which shall be no less than seventeen bits.
+When calculating the checksum, the @code{chksum} field is treated as
+if it were all blanks.
+
+The @code{typeflag} field specifies the type of file archived. If a
+particular implementation does not recognize or permit the specified
+type, the file will be extracted as if it were a regular file. As this
+action occurs, @command{tar} issues a warning to the standard error.
+
+The @code{atime} and @code{ctime} fields are used in making incremental
+backups; they store, respectively, the particular file's access and
+status change times.
+
+The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option,
when
+making a multi-volume archive. The offset is number of bytes into
+the file that we need to restart at to continue the file on the next
+tape, i.e., where we store the location that a continued file is
+continued at.
+
+The following fields were added to deal with sparse files. A file
+is @dfn{sparse} if it takes in unallocated blocks which end up being
+represented as zeros, i.e., no useful data. A test to see if a file
+is sparse is to look at the number blocks allocated for it versus the
+number of characters in the file; if there are fewer blocks allocated
+for the file than would normally be allocated for a file of that
+size, then the file is sparse. This is the method @command{tar} uses to
+detect a sparse file, and once such a file is detected, it is treated
+differently from non-sparse files.
+
+Sparse files are often @code{dbm} files, or other database-type files
+which have data at some points and emptiness in the greater part of
+the file. Such files can appear to be very large when an @samp{ls
+-l} is done on them, when in truth, there may be a very small amount
+of important data contained in the file. It is thus undesirable
+to have @command{tar} think that it must back up this entire file, as
+great quantities of room are wasted on empty blocks, which can lead
+to running out of room on a tape far earlier than is necessary.
+Thus, sparse files are dealt with so that these empty blocks are
+not written to the tape. Instead, what is written to the tape is a
+description, of sorts, of the sparse file: where the holes are, how
+big the holes are, and how much data is found at the end of the hole.
+This way, the file takes up potentially far less room on the tape,
+and when the file is extracted later on, it will look exactly the way
+it looked beforehand. The following is a description of the fields
+used to handle a sparse file:
+
+The @code{sp} is an array of @code{struct sparse}. Each @code{struct
+sparse} contains two 12-character strings which represent an offset
+into the file and a number of bytes to be written at that offset.
+The offset is absolute, and not relative to the offset in preceding
+array element.
+
+The header can hold four of these @code{struct sparse} at the moment;
+if more are needed, they are not stored in the header.
+
+The @code{isextended} flag is set when an @code{extended_header}
+is needed to deal with a file. Note that this means that this flag
+can only be set when dealing with a sparse file, and it is only set
+in the event that the description of the file will not fit in the
+allotted room for sparse structures in the header. In other words,
+an extended_header is needed.
+
+The @code{extended_header} structure is used for sparse files which
+need more sparse structures than can fit in the header. The header can
+fit 4 such structures; if more are needed, the flag @code{isextended}
+gets set and the next block is an @code{extended_header}.
+
+Each @code{extended_header} structure contains an array of 21
+sparse structures, along with a similar @code{isextended} flag
+that the header had. There can be an indeterminate number of such
address@hidden to describe a sparse file.
+
address@hidden @asis
+
address@hidden @code{REGTYPE}
address@hidden @code{AREGTYPE}
+These flags represent a regular file. In order to be compatible
+with older versions of @command{tar}, a @code{typeflag} value of
address@hidden should be silently recognized as a regular file.
+New archives should be created using @code{REGTYPE}. Also, for
+backward compatibility, @command{tar} treats a regular file whose name
+ends with a slash as a directory.
+
address@hidden @code{LNKTYPE}
+This flag represents a file linked to another file, of any type,
+previously archived. Such files are identified in Unix by each
+file having the same device and inode number. The linked-to name is
+specified in the @code{linkname} field with a trailing null.
+
address@hidden @code{SYMTYPE}
+This represents a symbolic link to another file. The linked-to name
+is specified in the @code{linkname} field with a trailing null.
+
address@hidden @code{CHRTYPE}
address@hidden @code{BLKTYPE}
+These represent character special files and block special files
+respectively. In this case the @code{devmajor} and @code{devminor}
+fields will contain the major and minor device numbers respectively.
+Operating systems may map the device specifications to their own
+local specification, or may ignore the entry.
+
address@hidden @code{DIRTYPE}
+This flag specifies a directory or sub-directory. The directory
+name in the @code{name} field should end with a slash. On systems where
+disk allocation is performed on a directory basis, the @code{size} field
+will contain the maximum number of bytes (which may be rounded to
+the nearest disk block allocation unit) which the directory may
+hold. A @code{size} field of zero indicates no such limiting. Systems
+which do not support limiting in this manner should ignore the
address@hidden field.
+
address@hidden @code{FIFOTYPE}
+This specifies a FIFO special file. Note that the archiving of a
+FIFO file archives the existence of this file and not its contents.
+
address@hidden @code{CONTTYPE}
+This specifies a contiguous file, which is the same as a normal
+file except that, in operating systems which support it, all its
+space is allocated contiguously on the disk. Operating systems
+which do not allow contiguous allocation should silently treat this
+type as a normal file.
+
address@hidden @code{A} @dots{} @code{Z}
+These are reserved for custom implementations. Some of these are
+used in the @acronym{GNU} modified format, as described below.
+
address@hidden table
+
+Other values are reserved for specification in future revisions of
+the P1003 standard, and should not be used by any @command{tar} program.
+
+The @code{magic} field indicates that this archive was output in
+the P1003 archive format. If this field contains @code{TMAGIC},
+the @code{uname} and @code{gname} fields will contain the ASCII
+representation of the owner and group of the file respectively.
+If found, the user and group IDs are used rather than the values in
+the @code{uid} and @code{gid} fields.
+
+For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
+169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
+IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
+(section E.4.48) for @cite{pax - Portable archive interchange}.
+
address@hidden Extensions
address@hidden @acronym{GNU} Extensions to the Archive Format
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+The @acronym{GNU} format uses additional file types to describe new types of
+files in an archive. These are listed below.
+
address@hidden @code
address@hidden GNUTYPE_DUMPDIR
address@hidden 'D'
+This represents a directory and a list of files created by the
address@hidden (@option{-G}) option. The @code{size} field gives the total
+size of the associated list of files. Each file name is preceded by
+either a @samp{Y} (the file should be in this archive) or an @samp{N}.
+(The file is a directory, or is not stored in the archive.) Each file
+name is terminated by a null. There is an additional null after the
+last file name.
+
address@hidden GNUTYPE_MULTIVOL
address@hidden 'M'
+This represents a file continued from another volume of a multi-volume
+archive created with the @option{--multi-volume} (@option{-M}) option. The
original
+type of the file is not given here. The @code{size} field gives the
+maximum size of this piece of the file (assuming the volume does
+not end before the file is written out). The @code{offset} field
+gives the offset from the beginning of the file where this part of
+the file begins. Thus @code{size} plus @code{offset} should equal
+the original size of the file.
+
address@hidden GNUTYPE_SPARSE
address@hidden 'S'
+This flag indicates that we are dealing with a sparse file. Note
+that archiving a sparse file requires special operations to find
+holes in the file, which mark the positions of these holes, along
+with the number of bytes of data to be found after the hole.
+
address@hidden GNUTYPE_VOLHDR
address@hidden 'V'
+This file type is used to mark the volume header that was given with
+the @address@hidden (@option{-V @var{archive-label}}) option when the archive
was created. The @code{name}
+field contains the @code{name} given after the @address@hidden (@option{-V
@var{archive-label}}) option.
+The @code{size} field is zero. Only the first file in each volume
+of an archive should have this type.
+
address@hidden table
+
+You may have trouble reading a @acronym{GNU} format archive on a
address@hidden system if the options @option{--incremental} (@option{-G}),
address@hidden (@option{-M}), @option{--sparse} (@option{-S}), or
@address@hidden (@option{-V @var{archive-label}}) were
+used when writing the archive. In general, if @command{tar} does not
+use the @acronym{GNU}-added fields of the header, other versions of
address@hidden should be able to read the archive. Otherwise, the
address@hidden program will give an error, the most likely one being a
+checksum error.
+
address@hidden Sparse Formats
address@hidden Storing Sparse Files
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden sparse formats
address@hidden sparse versions
+The notion of sparse file, and the ways of handling it from the point
+of view of @acronym{GNU} @command{tar} user have been described in detail in
address@hidden This chapter describes the internal format @acronym{GNU}
@command{tar}
+uses to store such files.
+
+The support for sparse files in @acronym{GNU} @command{tar} has a long
history. The
+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
address@hidden GNU} sparse format and in spite of the fact that its design
+contained many flaws, it was the only format @acronym{GNU} @command{tar}
supported
+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
+improved in versions 1.15.2 (November, 2005) and 1.15.92 (June,
+2006).
+
+In addition to GNU sparse format, @acronym{GNU} @command{tar} is able to read
and
+extract sparse files archived by @command{star}.
+
+The following subsections describe each format in detail.
+
address@hidden
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
address@hidden menu
+
address@hidden Old GNU Format
address@hidden Old GNU Format
+
address@hidden sparse formats, Old GNU
address@hidden Old GNU sparse format
+The format introduced some time around 1990 (v. 1.09). It was
+designed on top of standard @code{ustar} headers in such an
+unfortunate way that some of its fields overwrote fields required by
+POSIX.
+
+An old GNU sparse header is designated by type @samp{S}
+(@code{GNUTYPE_SPARSE}) and has the following layout:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.20 0.40
address@hidden Offset @tab Size @tab Name @tab Data type @tab Contents
address@hidden 0 @tab 345 @tab @tab N/A @tab Not used.
address@hidden 345 @tab 12 @tab atime @tab Number @tab
@code{atime} of the file.
address@hidden 357 @tab 12 @tab ctime @tab Number @tab
@code{ctime} of the file .
address@hidden 369 @tab 12 @tab offset @tab Number @tab For
+multivolume archives: the offset of the start of this volume.
address@hidden 381 @tab 4 @tab @tab N/A @tab Not used.
address@hidden 385 @tab 1 @tab @tab N/A @tab Not used.
address@hidden 386 @tab 96 @tab sp @tab @code{sparse_header} @tab
(4 entries) File map.
address@hidden 482 @tab 1 @tab isextended @tab Bool @tab
@code{1} if an
+extension sparse header follows, @code{0} otherwise.
address@hidden 483 @tab 12 @tab realsize @tab Number @tab Real
size of the file.
address@hidden multitable
+
+Each of @code{sparse_header} object at offset 386 describes a single
+data chunk. It has the following structure:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.60
address@hidden Offset @tab Size @tab Data type @tab Contents
address@hidden 0 @tab 12 @tab Number @tab Offset of the
+beginning of the chunk.
address@hidden 12 @tab 12 @tab Number @tab Size of the chunk.
address@hidden multitable
+
+If the member contains more than four chunks, the @code{isextended}
+field of the header has the value @code{1} and the main header is
+followed by one or more @dfn{extension headers}. Each such header has
+the following structure:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.20 0.40
address@hidden Offset @tab Size @tab Name @tab Data type @tab Contents
address@hidden 0 @tab 21 @tab sp @tab @code{sparse_header} @tab
+(21 entires) File map.
address@hidden 504 @tab 1 @tab isextended @tab Bool @tab @code{1}
if an
+extension sparse header follows, or @code{0} otherwise.
address@hidden multitable
+
+A header with @code{isextended=0} ends the map.
+
address@hidden PAX 0
address@hidden PAX Format, Versions 0.0 and 0.1
+
address@hidden sparse formats, v.0.0
+There are two formats available in this branch. The version @code{0.0}
+is the initial version of sparse format used by @command{tar}
+versions 1.14--1.15.1. The sparse file map is kept in extended
+(@code{x}) PAX header variables:
+
address@hidden @code
address@hidden GNU.sparse.size, extended header variable
address@hidden GNU.sparse.size
+Real size of the stored file
+
address@hidden GNU.sparse.numblocks
address@hidden GNU.sparse.numblocks, extended header variable
+Number of blocks in the sparse map
+
address@hidden GNU.sparse.offset
address@hidden GNU.sparse.offset, extended header variable
+Offset of the data block
+
address@hidden GNU.sparse.numbytes
address@hidden GNU.sparse.numbytes, extended header variable
+Size of the data block
address@hidden table
+
+The latter two variables repeat for each data block, so the overall
+structure is like this:
+
address@hidden
address@hidden
address@hidden
address@hidden
+repeat @var{numblocks} times
+ address@hidden
+ address@hidden
+end repeat
address@hidden group
address@hidden smallexample
+
+This format presented the following two problems:
+
address@hidden 1
address@hidden
+Whereas the POSIX specification allows a variable to appear multiple
+times in a header, it requires that only the last occurrence be
+meaningful. Thus, multiple ocurrences of @code{GNU.sparse.offset} and
address@hidden are conficting with the POSIX specs.
+
address@hidden
+Attempting to extract such archives using a third-party @command{tar}s
+results in extraction of sparse files in @emph{compressed 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
+state. However, posix-aware @command{tar}s will usually ignore the
+unknown variables, which makes restoring the file more
+difficult. @xref{extracting sparse v.0.x, Extraction of sparse
+members in v.0.0 format}, for the detailed description of how to
+restore such members using non-GNU @command{tar}s.
address@hidden enumerate
+
address@hidden sparse formats, v.0.1
address@hidden @command{tar} 1.15.2 introduced sparse format version
@code{0.1}, which
+attempted to solve these problems. As its predecessor, this format
+stores sparse map in the extended POSIX header. It retains
address@hidden and @code{GNU.sparse.numblocks} variables, but
+instead of @code{GNU.sparse.offset}/@code{GNU.sparse.numbytes} pairs
+it uses a single variable:
+
address@hidden @code
address@hidden GNU.sparse.map
address@hidden 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}...]"
address@hidden table
+
+To address the 2nd problem, the @code{name} field in @code{ustar}
+is replaced with a special name, constructed using the following pattern:
+
address@hidden
+%d/GNUSparseFile.%p/%f
address@hidden smallexample
+
address@hidden GNU.sparse.name, extended header variable
+The real name of the sparse file is stored in the variable
address@hidden Thus, those @command{tar} implementations
+that are not aware of GNU extensions will at least extract the files
+into separate directories, giving the user a possibility to expand it
+afterwards. @xref{extracting sparse v.0.x, Extraction of sparse
+members in v.0.1 format}, for the detailed description of how to
+restore such members using non-GNU @command{tar}s.
+
+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.
+
address@hidden PAX 1
address@hidden PAX Format, Version 1.0
+
address@hidden sparse formats, v.1.0
+The version @code{1.0} of sparse format was introduced with @acronym{GNU}
@command{tar}
+1.15.92. Its main objective was to make the resulting file
+extractable with little effort even by non-posix aware @command{tar}
+implementations. Starting from this version, the extended header
+preceding a sparse member always contains the following variables that
+identify the format being used:
+
address@hidden @code
address@hidden GNU.sparse.major
address@hidden GNU.sparse.major, extended header variable
+Major version
+
address@hidden GNU.sparse.minor
address@hidden GNU.sparse.minor, extended header variable
+Minor version
address@hidden table
+
+The @code{name} field in @code{ustar} header contains a special name,
+constructed using the following pattern:
+
address@hidden
+%d/GNUSparseFile.%p/%f
address@hidden smallexample
+
address@hidden GNU.sparse.name, extended header variable, in v.1.0
address@hidden GNU.sparse.realsize, extended header variable
+The real name of the sparse file is stored in the variable
address@hidden The real size of the file is stored in the
+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
+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
+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 @acronym{GNU}
@command{tar}.
address@hidden Recovery}, for the detailed information on how to extract
+sparse members without @acronym{GNU} @command{tar}.
+
+
address@hidden Snapshot Files
address@hidden Format of the Incremental Snapshot Files
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2005 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
+ A @dfn{snapshot file} (or @dfn{directory file}) is created during
+incremental backups (@pxref{Incremental Dumps}). It
+contains the status of the filesystem at the time of the dump and is
+used to determine which files were modified since the last backup.
+
+ @acronym{GNU} @command{tar} version 1.15.92 supports two snapshot file
+formats. The first format, called @dfn{format 0}, is the one used by
address@hidden @command{tar} versions up to 1.15.1. The second format, called
@dfn{format
+1} is an extended version of this format, that contains more metadata
+and allows for further extensions.
+
+ @samp{Format 0} snapshot file begins with a line containing a
+decimal number that represents the UNIX timestamp of the beginning of
+the last archivation. This line is followed by directory metadata
+descriptions, one per line. Each description has the following format:
+
address@hidden
address@hidden@var{dev} @var{inode} @var{name}
address@hidden smallexample
+
address@hidden
+where optional @var{nfs} is a single plus character (@samp{+}) if this
+directory is located on an NFS-mounted partition, @var{dev} and
address@hidden are the device and inode numbers of the directory, and
address@hidden is the directory name.
+
+ @samp{Format 1} snapshot file begins with a line specifying the
+format of the file. This line has the following structure:
+
address@hidden
address@hidden address@hidden@address@hidden
address@hidden smallexample
+
address@hidden
+where @var{tar-version} is the version of @acronym{GNU} @command{tar}
implementation
+that created this snapshot, and @var{incr-format-version} is the
+version number of the snapshot format (in this case @samp{1}).
+
+ The following line contains two decimal numbers, representing the
+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.
+
+ Following lines contain directory metadate, one line per
+directory. The line format is:
+
address@hidden
address@hidden@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
address@hidden smallexample
+
address@hidden
+where @var{mtime-sec} and @var{mtime-nsec} represent the last
+modification time of this directory with nanosecond precision;
address@hidden, @var{dev}, @var{inode} and @var{name} have the same meaning
+as with @samp{format 0}.
+
+
address@hidden End of snapshot.texi
+
+
+
address@hidden Dumpdir
address@hidden Dumpdir
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
+ Incremental archives keep information about contents of each
+dumped directory in special data blocks called @dfn{dumpdirs}.
+
+ Dumpdir is a sequence of entries of the following form:
+
address@hidden
address@hidden @var{filename} \0
address@hidden smallexample
+
address@hidden
+where @var{C} is one of the @dfn{control codes} described below,
address@hidden is the name of the file @var{C} operates upon, and
address@hidden represents a nul character (ASCII 0). The white space
+characters were added for readability, real dumpdirs do not contain
+them.
+
+ Each dumpdir ends with a single nul character.
+
+ The following table describes control codes and their meanings:
+
address@hidden @samp
address@hidden Y
address@hidden is contained in the archive.
+
address@hidden N
address@hidden was present in the directory at the time the archive
+was made, yet it was not dumped to the archive, because it had not
+changed since the last backup.
+
address@hidden D
address@hidden is a directory.
+
address@hidden R
+This code requests renaming of the @var{filename} to the name
+specified with the following @samp{T} command.
+
address@hidden T
+Specify target file name for @samp{R} command (see below).
+
address@hidden X
+Specify @dfn{temporary directory} name for a rename operation (see below).
address@hidden table
+
+ Codes @samp{Y}, @samp{N} and @samp{D} require @var{filename} argument
+to be a relative file name to the directory this dumpdir describes,
+whereas codes @samp{R}, @samp{T} and @samp{X} require their argument
+to be an absolute file name.
+
+ The three codes @samp{R}, @samp{T} and @samp{X} specify a
address@hidden operation}. In the simplest case it is:
+
address@hidden
address@hidden@file{dest}\0
address@hidden smallexample
+
address@hidden
+which means ``rename file @file{source} to file @file{dest}''.
+
+ However, there are cases that require using a @dfn{temporary
+directory}. For example, consider the following scenario:
+
address@hidden 1
address@hidden
+Previous run dumped a directory @file{foo} which contained the
+following three directories:
+
address@hidden
+a
+b
+c
address@hidden smallexample
+
address@hidden
+They were renamed @emph{cyclically}, so that:
+
address@hidden
address@hidden became @file{b}
address@hidden became @file{c}
address@hidden became @file{a}
address@hidden example
+
address@hidden
+New incremental dump was made.
address@hidden enumerate
+
+ This case cannot be handled by three successive renames, since
+renaming @file{a} to @file{b} will destroy existing directory.
+To handle such case a temporary directory is required. @acronym{GNU}
@command{tar}
+will create the following dumpdir (newlines have been added for
+readability):
+
address@hidden
address@hidden
+Xfoo\0
+Rfoo/a\0T\0
+Rfoo/b\0Tfoo/c\0
+Rfoo/c\0Tfoo/a\0
+R\0Tfoo/a\0
address@hidden group
address@hidden smallexample
+
+ The first command, @samp{Xfoo\0}, instructs the extractor to create a
+temporary directory in the directory @file{foo}. Second command,
address@hidden/aT\0}, says ``rename file @file{foo/a} to the temporary
+directory that has just been created'' (empty file name after a
+command means use temporary directory). Third and fourth commands
+work as usual, and, finally, the last command, @samp{R\0Tfoo/a\0}
+tells tar to rename the temporary directory to @file{foo/a}.
+
+ The exact placement of a dumpdir in the archive depends on the
+archive format (@pxref{Formats}):
+
address@hidden
address@hidden PAX archives
+
+In PAX archives, dumpdir is stored in the extended header of the
+corresponding directory, in variable @code{GNU.dumpdir}.
+
address@hidden GNU and old GNU archives
+
+These formats implement special header type @samp{D}, which is similar
+to ustar header @samp{5} (directory), except that it preceeds a data
+block containing the dumpdir.
address@hidden itemize
+
address@hidden End of dumpdir.texi
+
+
address@hidden Genfile
address@hidden Genfile
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2005, 2006 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden genfile
+ This appendix describes @command{genfile}, an auxiliary program
+used in the GNU tar testsuite. If you are not interested in developing
+GNU tar, skip this appendix.
+
+ Initially, @command{genfile} was used to generate data files for
+the testsuite, hence its name. However, new operation modes were being
+implemented as the testsuite grew more sophisticated, and now
address@hidden is a multi-purpose instrument.
+
+ There are three basic operation modes:
+
address@hidden @asis
address@hidden File Generation
+ This is the default mode. In this mode, @command{genfile}
+generates data files.
+
address@hidden File Status
+ In this mode @command{genfile} displays status of specified files.
+
address@hidden Synchronous Execution.
+ In this mode @command{genfile} executes the given program with
address@hidden option and executes a set of actions when
+specified checkpoints are reached.
address@hidden table
+
address@hidden
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
address@hidden menu
+
address@hidden Generate Mode
address@hidden Generate Mode
+
address@hidden Generate Mode, @command{genfile}
address@hidden @command{genfile}, generate mode
address@hidden @command{genfile}, create file
+ In this mode @command{genfile} creates a data file for the test
+suite. The size of the file is given with the @option{--length}
+(@option{-l}) option. By default the file contents is written to the
+standard output, this can be changed using @option{--file}
+(@option{-f}) command line option. Thus, the following two commands
+are equivalent:
+
address@hidden
address@hidden
+genfile --length 100 > outfile
+genfile --length 100 --file outfile
address@hidden group
address@hidden smallexample
+
+ If @option{--length} is not given, @command{genfile} will
+generate an empty (zero-length) file.
+
address@hidden @command{genfile}, reading a list of file names
+ You can instruct @command{genfile} to create several files at one
+go, by giving it @option{--files-from} (@option{-T}) option followed
+by a name of file containing a list of file names. Using dash
+(@samp{-}) instead of the file name causes @command{genfile} to read
+file list from the standard input. For example:
+
address@hidden
address@hidden
+# Read file names from file @file{file.list}
+genfile --files-from file.list
+# Read file names from standard input
+genfile --files-from -
address@hidden group
address@hidden smallexample
+
address@hidden File lists separated by NUL characters
+ The list file is supposed to contain one file name per line. To
+use file lists separated by ASCII NUL character, use @option{--null}
+(@option{-0}) command line option:
+
address@hidden
+genfile --null --files-from file.list
address@hidden smallexample
+
address@hidden pattern, @command{genfile}
+ The default data pattern for filling the generated file consists
+of first 256 letters of ASCII code, repeated enough times to fill the
+entire file. This behavior can be changed with @option{--pattern}
+option. This option takes a mandatory argument, specifying pattern
+name to use. Currently two patterns are implemented:
+
address@hidden @option
address@hidden --pattern=default
+ The default pattern as described above.
+
address@hidden --pattern=zero
+ Fills the file with zeroes.
address@hidden table
+
+ If no file name was given, the program exits with the code
address@hidden Otherwise, it exits with @code{0} only if it was able to
+create a file of the specified length.
+
address@hidden Sparse files, creating using @command{genfile}
address@hidden @command{genfile}, creating sparse files
+ Special option @option{--sparse} (@option{-s}) instructs
address@hidden to create a sparse file. Sparse files consist of
address@hidden fragments}, separated by @dfn{holes} or blocks of zeros. On
+many operating systems, actual disk storage is not allocated for
+holes, but they are counted in the length of the file. To create a
+sparse file, @command{genfile} should know where to put data fragments,
+and what data to use to fill them. So, when @option{--sparse} is given
+the rest of the command line specifies a so-called @dfn{file map}.
+
+ The file map consists of any number of @dfn{fragment
+descriptors}. Each descriptor is composed of two values: a number,
+specifying fragment offset from the end of the previous fragment or,
+for the very first fragment, from the beginning of the file, and
address@hidden string}, i.e. a string of characters, specifying the
+pattern to fill the fragment with. File offset can be suffixed with
+the following quantifiers:
+
address@hidden @samp
address@hidden k
address@hidden K
+The number is expressed in kilobytes.
address@hidden m
address@hidden M
+The number is expressed in megabytes.
address@hidden g
address@hidden G
+The number is expressed in gigabytes.
address@hidden table
+
+ For each letter in contents string @command{genfile} will generate
+a @dfn{block} of data, filled with this letter and will write it to
+the fragment. The size of block is given by @option{--block-size}
+option. It defaults to 512. Thus, if the string consists of @var{n}
+characters, the resulting file fragment will contain
address@hidden@address@hidden of data.
+
+ Last fragment descriptor can have only file offset part. In this
+case @command{genfile} will create a hole at the end of the file up to
+the given offset.
+
+ For example, consider the following invocation:
+
address@hidden
+genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
address@hidden smallexample
+
address@hidden
+It will create 3101184-bytes long file of the following structure:
+
address@hidden @columnfractions .35 .20 .45
address@hidden Offset @tab Length @tab Contents
address@hidden 0 @tab 4*512=2048 @tab Four 512-byte blocks, filled with
+letters @samp{A}, @samp{B}, @samp{C} and @samp{D}.
address@hidden 2048 @tab 1046528 @tab Zero bytes
address@hidden 1050624 @tab 5*512=2560 @tab Five blocks, filled with letters
address@hidden, @samp{F}, @samp{G}, @samp{H}, @samp{I}.
address@hidden 1053184 @tab 2048000 @tab Zero bytes
address@hidden multitable
+
+ The exit code of @command{genfile --status} command is @code{0}
+only if created file is actually sparse.
+
address@hidden Status Mode
address@hidden Status Mode
+
+ In status mode, @command{genfile} prints file system status for
+each file specified in the command line. This mode is toggled by
address@hidden (@option{-S}) command line option. An optional argument to this
+option specifies output @dfn{format}: a comma-separated list of
address@hidden stat} fields to be displayed. This list can contain
+following identifiers @allow-recursion
address@hidden
+:
+
address@hidden @asis
address@hidden name
+ The file name.
+
address@hidden dev
address@hidden st_dev
+ Device number in decimal.
+
address@hidden ino
address@hidden st_ino
+ Inode number.
+
address@hidden address@hidden
address@hidden address@hidden
+ File mode in octal. Optional @var{number} specifies octal mask to
+be applied to the mode before outputting. For example, @code{--stat
+mode.777} will preserve lower nine bits of it. Notice, that you can
+use any punctuation caracter in place of @samp{.}.
+
address@hidden nlink
address@hidden st_nlink
+ Number of hard links.
+
address@hidden uid
address@hidden st_uid
+ User ID of owner.
+
address@hidden gid
address@hidden st_gid
+ Group ID of owner.
+
address@hidden size
address@hidden st_size
+ File size in decimal.
+
address@hidden blksize
address@hidden st_blksize
+ The size in bytes of each file block.
+
address@hidden blocks
address@hidden st_blocks
+ Number of blocks allocated.
+
address@hidden atime
address@hidden st_atime
+ Time of last access.
+
address@hidden mtime
address@hidden st_mtime
+ Time of last modification
+
address@hidden ctime
address@hidden st_ctime
+ Time of last status change
+
address@hidden sparse
+ A boolean value indicating whether the file is @samp{sparse}.
address@hidden table
+
+ Modification times are displayed in @acronym{UTC} as
address@hidden timestamps, unless suffixed with @samp{H} (for
+``human-readable''), as in @samp{ctimeH}, in which case usual
address@hidden tv} output format is used.
+
+ The default output format is: @samp{name,dev,ino,mode,
+nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}.
+
+ For example, the following command will display file names and
+corresponding times of last access for each file in the current working
+directory:
+
address@hidden
+genfile --stat=name,atime *
address@hidden smallexample
+
address@hidden Exec Mode
address@hidden Exec Mode
+
address@hidden Exec Mode, @command{genfile}
+ This mode is designed for testing the behavior of @code{paxutils}
+commands when some of the files change during archiving. It is an
+experimental mode.
+
+ The @samp{Exec Mode} is toggled by @option{--run} command line
+option (or its alias @option{-r}). The argument to this option gives
+the command line to be executed. The actual command line is
+constructed by inserting @option{--checkpoint} option between the
+command name and its first argument (if any). Due to this, the
+argument to @option{--run} may not use traditional @command{tar}
+option syntax, i.e. the following is wrong:
+
address@hidden
+# Wrong!
+genfile --run 'tar cf foo bar'
address@hidden smallexample
+
address@hidden
+
+Use the following syntax instead:
+
address@hidden
+genfile --run 'tar -cf foo bar'
address@hidden smallexample
+
+ The rest of command line after @option{--run} or its equivalent
+specifies checkpoint values and actions to be executed upon reaching
+them. Checkpoint values are introduced with @option{--checkpoint}
+command line option. Argument to this option is the number of
+checkpoint in decimal.
+
+ Any number of @dfn{actions} may be specified after a
+checkpoint. Available actions are
+
address@hidden @option
address@hidden --cut @var{file}
address@hidden --truncate @var{file}
+ Truncate @var{file} to the size specified by previous
address@hidden option (or 0, if it is not given).
+
address@hidden --append @var{file}
+ Append data to @var{file}. The size of data and its pattern are
+given by previous @option{--length} and @option{pattern} options.
+
address@hidden --touch @var{file}
+ Update the access and modification times of @var{file}. These
+timestamps are changed to the current time, unless @option{--date}
+option was given, in which case they are changed to the specified
+time. Argument to @option{--date} option is a date specification in
+an almost arbitrary format (@pxref{Date input formats}).
+
address@hidden --exec @var{command}
+ Execute given shell command.
+
address@hidden table
+
+ Option @option{--verbose} instructs @command{genfile} to print on
+standard output notifications about checkpoints being executed and to
+verbosely describe exit status of the command.
+
+ While the command is being executed its standard output remains
+connected to descriptor 1. All messages it prints to file descriptor
+2, except checkpoint notifications, are forwarded to standard
+error.
+
+ @command{Genfile} exits with the exit status of the executed command.
+
address@hidden Free Software Needs Free Documentation
address@hidden Free Software Needs Free Documentation
address@hidden free documentation
+
+The biggest deficiency in the free software community today is not in
+the software---it is the lack of good free documentation that we can
+include with the free software. Many of our most important
+programs do not come with free reference manuals and free introductory
+texts. Documentation is an essential part of any software package;
+when an important free software package does not come with a free
+manual and a free tutorial, that is a major gap. We have many such
+gaps today.
+
+Consider Perl, for instance. The tutorial manuals that people
+normally use are non-free. How did this come about? Because the
+authors of those manuals published them with restrictive terms---no
+copying, no modification, source files not available---which exclude
+them from the free software world.
+
+That wasn't the first time this sort of thing happened, and it was far
+from the last. Many times we have heard a GNU user eagerly describe a
+manual that he is writing, his intended contribution to the community,
+only to learn that he had ruined everything by signing a publication
+contract to make it non-free.
+
+Free documentation, like free software, is a matter of freedom, not
+price. The problem with the non-free manual is not that publishers
+charge a price for printed copies---that in itself is fine. (The Free
+Software Foundation sells printed copies of manuals, too.) The
+problem is the restrictions on the use of the manual. Free manuals
+are available in source code form, and give you permission to copy and
+modify. Non-free manuals do not allow this.
+
+The criteria of freedom for a free manual are roughly the same as for
+free software. Redistribution (including the normal kinds of
+commercial redistribution) must be permitted, so that the manual can
+accompany every copy of the program, both on-line and on paper.
+
+Permission for modification of the technical content is crucial too.
+When people modify the software, adding or changing features, if they
+are conscientious they will change the manual too---so they can
+provide accurate and clear documentation for the modified program. A
+manual that leaves you no choice but to write a new manual to document
+a changed version of the program is not really available to our
+community.
+
+Some kinds of limits on the way modification is handled are
+acceptable. For example, requirements to preserve the original
+author's copyright notice, the distribution terms, or the list of
+authors, are ok. It is also no problem to require modified versions
+to include notice that they were modified. Even entire sections that
+may not be deleted or changed are acceptable, as long as they deal
+with nontechnical topics (like this one). These kinds of restrictions
+are acceptable because they don't obstruct the community's normal use
+of the manual.
+
+However, it must be possible to modify all the @emph{technical}
+content of the manual, and then distribute the result in all the usual
+media, through all the usual channels. Otherwise, the restrictions
+obstruct the use of the manual, it is not free, and we need another
+manual to replace it.
+
+Please spread the word about this issue. Our community continues to
+lose manuals to proprietary publishing. If we spread the word that
+free software needs free reference manuals and free tutorials, perhaps
+the next person who wants to contribute by writing documentation will
+realize, before it is too late, that only free manuals contribute to
+the free software community.
+
+If you are writing documentation, please insist on publishing it under
+the GNU Free Documentation License or another free documentation
+license. Remember that this decision requires your approval---you
+don't have to let the publisher decide. Some commercial publishers
+will use a free license if you insist, but they will not propose the
+option; it is up to you to raise the issue and say firmly that this is
+what you want. If the publisher you are dealing with refuses, please
+try other publishers. If you're not sure whether a proposed license
+is free, write to @email{licensing@@gnu.org}.
+
+You can encourage commercial publishers to sell more free, copylefted
+manuals and tutorials by buying them, and particularly by buying
+copies from the publishers that paid for their writing or for major
+improvements. Meanwhile, try to avoid buying non-free documentation
+at all. Check the distribution terms of a manual before you buy it,
+and insist that whoever seeks your business must respect your freedom.
+Check the history of the book, and try reward the publishers that have
+paid or pay the authors to work on it.
+
+The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
address@hidden://www.fsf.org/doc/other-free-books.html}.
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.2, November 2002
+
address@hidden
+Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
+51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
address@hidden Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
address@hidden for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
address@hidden
+Preserve any Warranty Disclaimers.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with...Texts.'' line with this:
+
address@hidden
address@hidden
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
address@hidden Index of Command Line Options
address@hidden Index of Command Line Options
+
+This appendix contains an index of all @acronym{GNU} @command{tar} long
command line
+options. The options are listed without the preceeding double-dash.
+For a cross-reference of short command line options, @ref{Short Option
Summary}.
+
address@hidden op
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
address@hidden
address@hidden
Index: res_all/texi_tar/tar.texi.first
===================================================================
RCS file: res_all/texi_tar/tar.texi.first
diff -N res_all/texi_tar/tar.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_all/texi_tar/tar.texi.first 2 Aug 2009 13:46:14 -0000 1.1
@@ -0,0 +1,13572 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden tar.info
address@hidden UPDATED 26 June 2006
address@hidden UPDATED-MONTH June 2006
address@hidden EDITION 1.15.92
address@hidden VERSION 1.15.92
address@hidden GNU tar 1.15.92
address@hidden odd
+
address@hidden
+
address@hidden
address@hidden %**end of header
+
address@hidden Maintenance notes:
address@hidden 1. Pay attention to @FIXME{}s and @UNREVISED{}s
address@hidden 2. Before creating final variant:
address@hidden 2.1. Run `make check-options' to make sure all options are
properly
address@hidden documented;
address@hidden 2.2. Run `make master-menu' (see comment before the master
menu).
+
address@hidden This is part of GNU tar manual.
address@hidden Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
address@hidden 2003, 2004, 2006 Free Software Foundation, Inc.
address@hidden See file tar.texi for copying conditions.
+
address@hidden This file contains support for 'renditions' by Fran@,{c}ois
Pinard
address@hidden I extended it by adding a FIXME_FOOTNOTE variable, which controls
address@hidden whether FIXME information should be placed in footnotes or
address@hidden inlined. --gray
+
address@hidden
======================================================================
address@hidden This document has three levels of rendition: PUBLISH, DISTRIB or
PROOF,
address@hidden as decided by @set symbols. The PUBLISH rendition does not show
address@hidden notes or marks asking for revision. Most users will prefer
having more
address@hidden information, even if this information is not fully revised for
adequacy,
address@hidden so DISTRIB is the default for distributions. The PROOF rendition
address@hidden show all marks to the point of ugliness, but is nevertheless
useful to
address@hidden those working on the manual itself.
address@hidden
======================================================================
+
address@hidden Set this symbol if you wish FIXMEs to appear in footnotes,
instead
address@hidden of being inserted into the text.
address@hidden @set PROOF_FOOTNOTED
+
address@hidden DISTRIB
+
+
address@hidden RENDITION FTP release, version
+
+
address@hidden Output marks for nodes needing revision, but not in PUBLISH
rendition.
+
address@hidden UNREVISED
address@hidden PUBLISH
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden ifclear
address@hidden macro
+
address@hidden Output various FIXME information only in PROOF rendition.
+
address@hidden FIXME{string}
address@hidden
address@hidden
address@hidden PROOF
address@hidden PROOF_FOOTNOTED
address@hidden@strong{FIXME:} \string\}
address@hidden ifset
address@hidden PROOF_FOOTNOTED
address@hidden
address@hidden<FIXME>} \string\ @strong{</>}
address@hidden cartouche
address@hidden ifclear
address@hidden ifset
+
address@hidden macro
+
address@hidden FIXME-ref{string}
address@hidden
address@hidden PROOF
address@hidden<REF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden FIXME-pxref{string}
address@hidden
address@hidden PROOF
address@hidden<PXREF>} \string\ @strong{</>}
address@hidden ifset
+
address@hidden macro
+
address@hidden FIXME-xref{string}
address@hidden
address@hidden PROOF
address@hidden<XREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden End of rendition.texi
address@hidden This is part of GNU tar manual.
address@hidden Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
address@hidden 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
address@hidden See file tar.texi for copying conditions.
+
address@hidden GNUTAR
address@hidden @command{tar}
address@hidden macro
+
address@hidden xopindex{option,text}
address@hidden address@hidden, \text\}
address@hidden macro
+
address@hidden opsummary{option}
address@hidden ANCHOR--\option\
address@hidden ANCHOR--\option\ 1
address@hidden
address@hidden ifclear
address@hidden, summary}
address@hidden macro
+
+
+
address@hidden op
+
address@hidden Put everything in one index (arbitrarily chosen to be the
concept index).
address@hidden fn cp
address@hidden ky cp
address@hidden pg cp
address@hidden vr cp
+
+
address@hidden Archiving
address@hidden
+* Tar: (tar). Making tape (or disk) archives.
address@hidden direntry
+
address@hidden Individual utilities
address@hidden
+* tar: (tar)tar invocation. Invoking @acronym{GNU}
@command{tar}.
address@hidden direntry
+
address@hidden @acronym{GNU} @command{tar}
+
+
address@hidden Top
address@hidden @acronym{GNU} tar: an archiver tool
+
address@hidden
+
address@hidden file archival
address@hidden archiving files
+
+The first part of this master menu lists the major nodes in this Info
+document. The rest of the menu lists all the lower level nodes.
+
address@hidden The master menu goes here.
address@hidden
address@hidden NOTE: To update it from within Emacs, make sure mastermenu.el is
address@hidden loaded and run texinfo-master-menu.
address@hidden To update it from the command line, run
address@hidden
address@hidden make master-menu
+
address@hidden
+* Introduction::
+* Tutorial::
+* tar invocation::
+* operations::
+* Backups::
+* Choosing::
+* Date input formats::
+* Formats::
+* Media::
+
+Appendices
+
+* Changes::
+* Configuring Help Summary::
+* Tar Internals::
+* Genfile::
+* Free Software Needs Free Documentation::
+* Copying This Manual::
+* Index of Command Line Options::
+* Index::
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @acronym{GNU} @command{tar} Authors
+* Reports:: Reporting bugs or suggestions
+
+Tutorial Introduction to @command{tar}
+
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
+
+Two Frequently Used Options
+
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
+
+How to Create Archives
+
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+
+How to List Archives
+
+* list dir::
+
+How to Extract Members from an Archive
+
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
+
+Invoking @acronym{GNU} @command{tar}
+
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
+
+The Three Option Styles
+
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
+
+All @command{tar} Options
+
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+
address@hidden @command{tar} Operations
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+Advanced @acronym{GNU} @command{tar} Operations
+
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+
+How to Add Files to Existing Archives: @option{--append}
+
+* appending files:: Appending Files to an Archive
+* multiple::
+
+Updating an Archive
+
+* how to update::
+
+Options Used by @option{--create}
+
+* override:: Overriding File Metadata.
+* Ignore Failed Read::
+
+Options Used by @option{--extract}
+
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+
+Options to Help Read Archives
+
+* read full records::
+* Ignore Zeros::
+
+Changing How @command{tar} Writes Files
+
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+
+Coping with Scarce Resources
+
+* Starting File::
+* Same Order::
+
+Performing Backups and Restoring Files
+
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental
Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+
+Setting Parameters for Backups and Restoration
+
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+
+Choosing Files and Names for @command{tar}
+
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+
+Reading Names from a File
+
+* nul::
+
+Excluding Some Files
+
+* problems with exclude::
+
+Wildcards Patterns and Matching
+
+* controlling pattern-matching::
+
+Crossing File System Boundaries
+
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+
+Date input formats
+
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
+
+Controlling the Archive Format
+
+* Portability:: Making @command{tar} Archives More Portable
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* cpio:: Comparison of @command{tar} and @command{cpio}
+
+Making @command{tar} Archives More Portable
+
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
+
address@hidden @command{tar} and @acronym{POSIX} @command{tar}
+
+* PAX keywords:: Controlling Extended Header Keywords.
+
+How to Extract GNU-Specific Data Using Other @command{tar} Implementations
+
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
+
+Using Less Space through Compression
+
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+
+Tapes and Other Archive Media
+
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+
+Blocking
+
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+
+Many Archives on One Tape
+
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
+
+Using Multiple Tapes
+
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
+
+Tar Internals
+
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
+
+Storing Sparse Files
+
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
+
+Genfile
+
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
address@hidden detailmenu
address@hidden menu
+
address@hidden Introduction
address@hidden Introduction
+
address@hidden @command{tar} creates
+and manipulates @dfn{archives} which are actually collections of
+many other files; the program provides users with an organized and
+systematic method for controlling a large amount of data.
+The name ``tar'' originally came from the phrase ``Tape ARchive'', but
+archives need not (and these days, typically do not) reside on tapes.
+
address@hidden
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @acronym{GNU} @command{tar} Authors
+* Reports:: Reporting bugs or suggestions
address@hidden menu
+
address@hidden Book Contents
address@hidden What this Book Contains
+
+The first part of this chapter introduces you to various terms that will
+recur throughout the book. It also tells you who has worked on @acronym{GNU}
@command{tar}
+and its documentation, and where you should send bug reports
+or comments.
+
+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
+chapters to make sense. It moves from topic to topic in a logical,
+progressive order, building on information already explained.
+
+Although the tutorial is paced and structured to allow beginners to
+learn how to use @command{tar}, it is not intended solely for beginners.
+The tutorial explains how to use the three most frequently used
+operations (@samp{create}, @samp{list}, and @samp{extract}) as well as
+two frequently used options (@samp{file} and @samp{verbose}). The other
+chapters do not refer to the tutorial frequently; however, if a section
+discusses something which is a complex variant of a basic concept, there
+may be a cross reference to that basic concept. (The entire book,
+including the tutorial, assumes that the reader understands some basic
+concepts of using a Unix-type operating system; @pxref{Tutorial}.)
+
+The third chapter presents the remaining five operations, and
+information about using @command{tar} options and option syntax.
+
address@hidden
address@hidden
+ The other chapters are meant to be used as a
+reference. Each chapter presents everything that needs to be said
+about a specific topic.
+
+One of the chapters (@pxref{Date input formats}) exists in its
+entirety in other @acronym{GNU} manuals, and is mostly self-contained.
+In addition, one section of this manual (@pxref{Standard}) contains a
+big quote which is taken directly from @command{tar} sources.
+
+In general, we give both long and short (abbreviated) option names
+at least once in each section where the relevant option is covered, so
+that novice readers will become familiar with both styles. (A few
+options have no short versions, and the relevant sections will
+indicate this.)
+
address@hidden Definitions
address@hidden Some Definitions
+
address@hidden archive
address@hidden tar archive
+The @command{tar} program is used to create and manipulate @command{tar}
+archives. An @dfn{archive} is a single file which contains the contents
+of many files, while still identifying the names of the files, their
+owner(s), and so forth. (In addition, archives record access
+permissions, user and group, size in bytes, and data modification time.
+Some archives also record the file names in each archived directory, as
+well as other file and directory information.) You can use @command{tar}
+to @dfn{create} a new archive in a specified directory.
+
address@hidden member
address@hidden archive member
address@hidden file name
address@hidden member name
+The files inside an archive are called @dfn{members}. Within this
+manual, we use the term @dfn{file} to refer only to files accessible in
+the normal ways (by @command{ls}, @command{cat}, and so forth), and the term
address@hidden to refer only to the members of an archive. Similarly, a
address@hidden name} is the name of a file, as it resides in the file system,
+and a @dfn{member name} is the name of an archive member within the
+archive.
+
address@hidden extraction
address@hidden unpacking
+The term @dfn{extraction} refers to the process of copying an archive
+member (or multiple members) into a file in the file system. Extracting
+all the members of an archive is often called @dfn{extracting the
+archive}. The term @dfn{unpack} can also be used to refer to the
+extraction of many or all the members of an archive. Extracting an
+archive does not destroy the archive's structure, just as creating an
+archive does not destroy the copies of the files that exist outside of
+the archive. You may also @dfn{list} the members in a given archive
+(this is often thought of as ``printing'' them to the standard output,
+or the command line), or @dfn{append} members to a pre-existing archive.
+All of these operations can be performed using @command{tar}.
+
address@hidden What tar Does
address@hidden What @command{tar} Does
+
address@hidden tar
+The @command{tar} program provides the ability to create @command{tar}
+archives, as well as various other kinds of manipulation. For example,
+you can use @command{tar} on previously created archives to extract files,
+to store additional files, or to update or list files which were already
+stored.
+
+Initially, @command{tar} archives were used to store files conveniently on
+magnetic tape. The name @command{tar} comes from this use; it stands for
address@hidden @code{ar}chiver. Despite the utility's name, @command{tar} can
+direct its output to available devices, files, or other programs (using
+pipes). @command{tar} may even access remote devices or files (as archives).
+
+You can use @command{tar} archives in many ways. We want to stress a few
+of them: storage, backup, and transportation.
+
address@hidden
address@hidden
+
address@hidden @asis
address@hidden Storage
+Often, @command{tar} archives are used to store related files for
+convenient file transfer over a network. For example, the
address@hidden Project distributes its software bundled into
address@hidden archives, so that all the files relating to a particular
+program (or set of related programs) can be transferred as a single
+unit.
+
+A magnetic tape can store several files in sequence. However, the tape
+has no names for these files; it only knows their relative position on
+the tape. One way to store several files on one tape and retain their
+names is by creating a @command{tar} archive. Even when the basic transfer
+mechanism can keep track of names, as FTP can, the nuisance of handling
+multiple files, directories, and multiple links makes @command{tar}
+archives useful.
+
+Archive files are also used for long-term storage. You can think of
+this as transportation from the present into the future. (It is a
+science-fiction idiom that you can move through time as well as in
+space; the idea here is that @command{tar} can be used to move archives in
+all dimensions, even time!)
+
address@hidden Backup
+Because the archive created by @command{tar} is capable of preserving
+file information and directory structure, @command{tar} is commonly
+used for performing full and incremental backups of disks. A backup
+puts a collection of files (possibly pertaining to many users and
+projects) together on a disk or a tape. This guards against
+accidental destruction of the information in those files.
address@hidden @command{tar} has special features that allow it to be
+used to make incremental and full dumps of all the files in a
+file system.
+
address@hidden Transportation
+You can create an archive on one system, transfer it to another system,
+and extract the contents there. This allows you to transport a group of
+files from one system to another.
address@hidden table
+
address@hidden Naming tar Archives
address@hidden How @command{tar} Archives are Named
+
+Conventionally, @command{tar} archives are given names ending with
address@hidden This is not necessary for @command{tar} to operate properly,
+but this manual follows that convention in order to accustom readers to
+it and to make examples more clear.
+
address@hidden tar file
address@hidden entry
address@hidden tar entry
+Often, people refer to @command{tar} archives as address@hidden files,'' and
+archive members as ``files'' or ``entries''. For people familiar with
+the operation of @command{tar}, this causes no difficulty. However, in
+this manual, we consistently refer to ``archives'' and ``archive
+members'' to make learning to use @command{tar} easier for novice users.
+
address@hidden Authors
address@hidden @acronym{GNU} @command{tar} Authors
+
address@hidden @command{tar} was originally written by John Gilmore,
+and modified by many people. The @acronym{GNU} enhancements were
+written by Jay Fenlason, then Joy Kendall, and the whole package has
+been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois
+Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
+numerous and kind users.
+
+We wish to stress that @command{tar} is a collective work, and owes much to
+all those people who reported problems, offered solutions and other
+insights, or shared their thoughts and suggestions. An impressive, yet
+partial list of those contributors can be found in the @file{THANKS}
+file from the @acronym{GNU} @command{tar} distribution.
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
+Jay Fenlason put together a draft of a @acronym{GNU} @command{tar}
+manual, borrowing notes from the original man page from John Gilmore.
+This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy
+Gorin worked on a tutorial and manual for @acronym{GNU} @command{tar}.
+Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
+taking information from all these sources and merging them. Melissa
+Weisshaus finally edited and redesigned the book to create version
+1.12. The book for versions from 1.14 up to 1.15.92 were edited
+by the current maintainer, Sergey Poznyakoff.
+
+For version 1.12, Daniel Hagerty contributed a great deal of technical
+consulting. In particular, he is the primary author of @ref{Backups}.
+
+In July, 2003 @acronym{GNU} @command{tar} was put on CVS at savannah.gnu.org
+(see @url{http://savannah.gnu.org/projects/tar}), and
+active development and maintenance work has started
+again. Currently @acronym{GNU} @command{tar} is being maintained by Paul
Eggert, Sergey
+Poznyakoff and Jeff Bailey.
+
+Support for @acronym{POSIX} archives was added by Sergey Poznyakoff.
+
address@hidden Reports
address@hidden Reporting bugs or suggestions
+
address@hidden bug reports
address@hidden reporting bugs
+If you find problems or have suggestions about this program or manual,
+please report them to @file{bug-tar@@gnu.org}.
+
+When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it. @allow-recursion
address@hidden
+.
+
address@hidden Tutorial
address@hidden Tutorial Introduction to @command{tar}
+
+This chapter guides you through some basic examples of three @command{tar}
+operations: @option{--create}, @option{--list}, and @option{--extract}. If
+you already know how to use some other version of @command{tar}, then you
+may not need to read this chapter. This chapter omits most complicated
+details about how @command{tar} works.
+
address@hidden
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
address@hidden menu
+
address@hidden assumptions
address@hidden Assumptions this Tutorial Makes
+
+This chapter is paced to allow beginners to learn about @command{tar}
+slowly. At the same time, we will try to cover all the basic aspects of
+these three operations. In order to accomplish both of these tasks, we
+have made certain assumptions about your knowledge before reading this
+manual, and the hardware you will be using:
+
address@hidden @bullet
address@hidden
+Before you start to work through this tutorial, you should understand
+what the terms ``archive'' and ``archive member'' mean
+(@pxref{Definitions}). In addition, you should understand something
+about how Unix-type operating systems work, and you should know how to
+use some basic utilities. For example, you should know how to create,
+list, copy, rename, edit, and delete files and directories; how to
+change between directories; and how to figure out where you are in the
+file system. You should have some basic understanding of directory
+structure and how files are named according to which directory they are
+in. You should understand concepts such as standard output and standard
+input, what various definitions of the term ``argument'' mean, and the
+differences between relative and absolute path names. @allow-recursion
address@hidden
+
+
address@hidden
+This manual assumes that you are working from your own home directory
+(unless we state otherwise). In this tutorial, you will create a
+directory to practice @command{tar} commands in. When we show path names,
+we will assume that those paths are relative to your home directory.
+For example, my home directory path is @file{/home/fsf/melissa}. All of
+my examples are in a subdirectory of the directory named by that path
+name; the subdirectory is called @file{practice}.
+
address@hidden
+In general, we show examples of archives which exist on (or can be
+written to, or worked with from) a directory on a hard disk. In most
+cases, you could write those archives to, or work with them on any other
+device, such as a tape drive. However, some of the later examples in
+the tutorial and next chapter will not work on tape drives.
+Additionally, working with tapes is much more complicated than working
+with hard disks. For these reasons, the tutorial does not cover working
+with tape drives. @xref{Media}, for complete information on using
address@hidden archives with tape drives.
+
address@hidden
address@hidden
+
address@hidden itemize
+
address@hidden stylistic conventions
address@hidden Stylistic Conventions
+
+In the examples, @samp{$} represents a typical shell prompt. It
+precedes lines you should type; to make this more clear, those lines are
+shown in @kbd{this font}, as opposed to lines which represent the
+computer's response; those lines are shown in @code{this font}, or
+sometimes @samp{like this}.
+
address@hidden When we have lines which are too long to be
address@hidden displayed in any other way, we will show them like this:
+
address@hidden basic tar options
address@hidden Basic @command{tar} Operations and Options
+
address@hidden can take a wide variety of arguments which specify and define
+the actions it will have on the particular set of files or the archive.
+The main types of arguments to @command{tar} fall into one of two classes:
+operations, and options.
+
+Some arguments fall into a class called @dfn{operations}; exactly one of
+these is both allowed and required for any instance of using @command{tar};
+you may @emph{not} specify more than one. People sometimes speak of
address@hidden modes}. You are in a particular operating mode when you
+have specified the operation which specifies it; there are eight
+operations in total, and thus there are eight operating modes.
+
+The other arguments fall into the class known as @dfn{options}. You are
+not required to specify any options, and you are allowed to specify more
+than one at a time (depending on the way you are using @command{tar} at
+that time). Some options are used so frequently, and are so useful for
+helping you type commands more carefully that they are effectively
+``required''. We will discuss them in this chapter.
+
+You can write most of the @command{tar} operations and options in any
+of three forms: long (mnemonic) form, short form, and old style. Some
+of the operations and options have no short or ``old'' forms; however,
+the operations and options which we will cover in this tutorial have
+corresponding abbreviations. @allow-recursion
address@hidden
+We will indicate those abbreviations appropriately to get
+you used to seeing them. (Note that the ``old style'' option forms
+exist in @acronym{GNU} @command{tar} for compatibility with Unix
address@hidden In this book we present a full discussion of this way
+of writing options and operations (@pxref{Old Options}), and we discuss
+the other two styles of writing options (@xref{Long Options}, and
address@hidden Options}).
+
+In the examples and in the text of this tutorial, we usually use the
+long forms of operations and options; but the ``short'' forms produce
+the same result and can make typing long @command{tar} commands easier.
+For example, instead of typing
+
address@hidden
address@hidden --create --verbose --file=afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+you can type
address@hidden
address@hidden -c -v -f afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+or even
address@hidden
address@hidden -cvf afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+For more information on option syntax, see @ref{Advanced tar}. In
+discussions in the text, when we name an option by its long form, we
+also give the corresponding short option in parentheses.
+
+The term, ``option'', can be confusing at times, since ``operations''
+are often lumped in with the actual, @emph{optional} ``options'' in certain
+general class statements. For example, we just talked about ``short and
+long forms of options and operations''. However, experienced @command{tar}
+users often refer to these by shorthand terms such as, ``short and long
+options''. This term assumes that the ``operations'' are included, also.
+Context will help you determine which definition of ``options'' to use.
+
+Similarly, the term ``command'' can be confusing, as it is often used in
+two different ways. People sometimes refer to @command{tar} ``commands''.
+A @command{tar} @dfn{command} is the entire command line of user input
+which tells @command{tar} what to do --- including the operation, options,
+and any arguments (file names, pipes, other commands, etc). However,
+you will also sometimes hear the term ``the @command{tar} command''. When
+the word ``command'' is used specifically like this, a person is usually
+referring to the @command{tar} @emph{operation}, not the whole line.
+Again, use context to figure out which of the meanings the speaker
+intends.
+
address@hidden frequent operations
address@hidden The Three Most Frequently Used Operations
+
+Here are the three most frequently used operations (both short and long
+forms), as well as a brief description of their meanings. The rest of
+this chapter will cover how to use these operations in detail. We will
+present the rest of the operations in the next chapter.
+
address@hidden @option
address@hidden --create
address@hidden -c
+Create a new @command{tar} archive.
address@hidden --list
address@hidden -t
+List the contents of an archive.
address@hidden --extract
address@hidden -x
+Extract one or more members from an archive.
address@hidden table
+
address@hidden Two Frequent Options
address@hidden Two Frequently Used Options
+
+To understand how to run @command{tar} in the three operating modes listed
+previously, you also need to understand how to use two of the options to
address@hidden: @option{--file} (which takes an archive file as an argument)
+and @option{--verbose}. (You are usually not @emph{required} to specify
+either of these options when you run @command{tar}, but they can be very
+useful in making things more clear and helping you avoid errors.)
+
address@hidden
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
address@hidden menu
+
address@hidden file tutorial
address@hidden The @option{--file} Option
+
address@hidden @option
address@hidden address@hidden, tutorial}
address@hidden address@hidden
address@hidden -f @var{archive-name}
+Specify the name of an archive file.
address@hidden table
+
+You can specify an argument for the @address@hidden (@option{-f
@var{archive-name}}) option whenever you
+use @command{tar}; this option determines the name of the archive file
+that @command{tar} will work on.
+
address@hidden TAPE
+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
+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
+attached, or the default is not meaningful, then @command{tar} will
+print an error message. The error message might look roughly like one
+of the following:
+
address@hidden
+tar: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
address@hidden smallexample
+
address@hidden
+To avoid confusion, we recommend that you always specify an archive file
+name by using @address@hidden (@option{-f @var{archive-name}}) when writing
your @command{tar} commands.
+For more information on using the @address@hidden (@option{-f
@var{archive-name}}) option, see
address@hidden
+
address@hidden verbose tutorial
address@hidden The @option{--verbose} Option
+
address@hidden @option
address@hidden address@hidden, introduced}
address@hidden --verbose
address@hidden -v
+Show the files being worked on as @command{tar} is running.
address@hidden table
+
address@hidden (@option{-v}) shows details about the results of running
address@hidden This can be especially useful when the results might not be
+obvious. For example, if you want to see the progress of @command{tar} as
+it writes files into the archive, you can use the @option{--verbose}
+option. In the beginning, you may find it useful to use
address@hidden at all times; when you are more accustomed to
address@hidden, you will likely want to use it at certain times but not at
+others. We will use @option{--verbose} at times to help make something
+clear, and we will give many examples both using and not using
address@hidden to show the differences.
+
+Each instance of @option{--verbose} on the command line increases the
+verbosity level by one, so if you need more details on the output,
+specify it twice.
+
+When reading archives (@option{--list}, @option{--extract},
address@hidden), @command{tar} by default prints only the names of
+the members being extracted. Using @option{--verbose} will show a full,
address@hidden style member listing.
+
+In contrast, when writing archives (@option{--create}, @option{--append},
address@hidden), @command{tar} does not print file names by
+default. So, a single @option{--verbose} option shows the file names
+being added to the archive, while two @option{--verbose} options
+enable the full listing.
+
+For example, to create an archive in verbose mode:
+
address@hidden
+$ @kbd{tar -cvf afiles.tar apple angst aspic}
+apple
+angst
+aspic
address@hidden smallexample
+
address@hidden
+Creating the same archive with the verbosity level 2 could give:
+
address@hidden
+$ @kbd{tar -cvvf afiles.tar apple angst aspic}
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
+-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
address@hidden smallexample
+
address@hidden
+This works equally well using short or long forms of options. Using
+long forms, you would simply write out the mnemonic form of the option
+twice, like this:
+
address@hidden
+$ @kbd{tar --create --verbose --verbose @dots{}}
address@hidden smallexample
+
address@hidden
+Note that you must double the hyphens properly each time.
+
+Later in the tutorial, we will give examples using @address@hidden
+--verbose}}.
+
address@hidden member listing}
+The full output consists of six fields:
+
address@hidden @bullet
address@hidden File type and permissions in symbolic form.
+These are displayed in the same format as the first column of
address@hidden -l} output (@pxref{What information is listed,
+format=verbose, Verbose listing, fileutils, GNU file utilities}).
+
address@hidden Owner name and group separated by a slash character.
+If these data are not available (for example, when listing a @samp{v7} format
+archive), numeric ID values are printed instead.
+
address@hidden Size of the file, in bytes.
+
address@hidden File modification date in ISO 8601 format.
+
address@hidden File modification time.
+
address@hidden File name.
+If the name contains any special characters (white space, newlines,
+etc.) these are displayed in an unambiguous form using so called
address@hidden style}. For the detailed discussion of available styles
+and on how to use them, see @ref{quoting styles}.
+
+Depending on the file type, the name can be followed by some
+additional information, described in the following table:
+
address@hidden @samp
address@hidden -> @var{link-name}
+The file or archive member is a @dfn{symbolic link} and
address@hidden is the name of file it links to.
+
address@hidden link to @var{link-name}
+The file or archive member is a @dfn{hard link} and @var{link-name} is
+the name of file it links to.
+
address@hidden --Long Link--
+The archive member is an old GNU format long link. You will normally
+not encounter this.
+
address@hidden --Long Name--
+The archive member is an old GNU format long name. You will normally
+not encounter this.
+
address@hidden --Volume Header--
+The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}).
+
address@hidden --Continued at byte @var{n}--
+Encountered only at the beginning of a multy-volume archive
+(@pxref{Using Multiple Tapes}). This archive member is a continuation
+from the previous volume. The number @var{n} gives the offset where
+the original file was split.
+
address@hidden --Mangled file names--
+This archive member contains @dfn{mangled file names} declarations,
+a special member type that was used by early versions of @acronym{GNU}
@command{tar}.
+You probably will never encounter this, unless you are reading a very
+old archive.
+
address@hidden unknown file type @var{c}
+An archive member of unknown type. @var{c} is the type character from
+the archive header. If you encounter such a message, it means that
+either your archive contains proprietary member types @acronym{GNU}
@command{tar} is not
+able to handle, or the archive is corrupted.
address@hidden table
+
address@hidden itemize
+
+For example, here is an archive listing containing most of the special
+suffixes explained above:
+
address@hidden
address@hidden
+V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
+byte 32456--
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden smallexample
+
address@hidden help tutorial
address@hidden Getting Help: Using the @option{--help} Option
+
address@hidden @option
address@hidden help
address@hidden --help
+
+The @option{--help} option to @command{tar} prints out a very brief list of
+all operations and option available for the current version of
address@hidden available on your system.
address@hidden table
+
address@hidden create
address@hidden How to Create Archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Creation of the archive
address@hidden Archive, creation of
+One of the basic operations of @command{tar} is @option{--create}
(@option{-c}), which
+you use to create a @command{tar} archive. We will explain
address@hidden first because, in order to learn about the other
+operations, you will find it useful to have an archive available to
+practice on.
+
+To make this easier, in this section you will first create a directory
+containing three files. Then, we will show you how to create an
address@hidden (inside the new directory). Both the directory, and
+the archive are specifically for you to practice on. The rest of this
+chapter and the next chapter will show many examples using this
+directory and the files you will create: some of those files may be
+other directories and other archives.
+
+The three files you will archive in this example are called
address@hidden, @file{folk}, and @file{jazz}. The archive is called
address@hidden
+
+This section will proceed slowly, detailing how to use @option{--create}
+in @code{verbose} mode, and showing examples using both short and long
+forms. In the rest of the tutorial, and in the examples in the next
+chapter, we will proceed at a slightly quicker pace. This section
+moves more slowly to allow beginning users to understand how
address@hidden works.
+
address@hidden
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
address@hidden menu
+
address@hidden prepare for examples
address@hidden Preparing a Practice Directory for Examples
+
+To follow along with this and future examples, create a new directory
+called @file{practice} containing files called @file{blues}, @file{folk}
+and @file{jazz}. The files can contain any information you like:
+ideally, they should contain information which relates to their names,
+and be of different lengths. Our examples assume that @file{practice}
+is a subdirectory of your home directory.
+
+Now @command{cd} to the directory named @file{practice}; @file{practice}
+is now your @dfn{working directory}. (@emph{Please note}: Although
+the full path name of this directory is
address@hidden/@var{homedir}/practice}, in our examples we will refer to
+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}.
+Because you just created the directory and the files and have changed to
+that directory, you probably don't need to do that this time.
+
+It is very important to make sure there isn't already a file in the
+working directory with the archive name you intend to use (in this case,
address@hidden), or that you don't care about its contents.
+Whenever you use @samp{create}, @command{tar} will erase the current
+contents of the file named by @address@hidden (@option{-f @var{archive-name}})
if it exists. @command{tar}
+will not tell you if you are about to overwrite an archive unless you
+specify an option which does this (@pxref{backup}, for the
+information on how to do so). To add files to an existing archive,
+you need to use a different option, such as @option{--append} (@option{-r});
see
address@hidden for information on how to do this.
+
address@hidden Creating the archive
address@hidden Creating the Archive
+
address@hidden address@hidden, introduced}
+To place the files @file{blues}, @file{folk}, and @file{jazz} into an
+archive named @file{collection.tar}, use the following command:
+
address@hidden
+$ @kbd{tar --create --file=collection.tar blues folk jazz}
address@hidden smallexample
+
+The order of the arguments is not very important, @emph{when using long
+option forms}. You could also say:
+
address@hidden
+$ @kbd{tar blues --create folk --file=collection.tar jazz}
address@hidden smallexample
+
address@hidden
+However, you can see that this order is harder to understand; this is
+why we will list the arguments in the order that makes the commands
+easiest to understand (and we encourage you to do the same when you use
address@hidden, to avoid errors).
+
+Note that the sequence
address@hidden@-collection.tar} is considered to be @emph{one} argument.
+If you substituted any other string of characters for
address@hidden, then that string would become the name of the
+archive file you create.
+
+The order of the options becomes more important when you begin to use
+short forms. With short forms, if you type commands in the wrong order
+(even if you type them correctly in all other ways), you may end up with
+results you don't expect. For this reason, it is a good idea to get
+into the habit of typing options in the order that makes inherent sense.
address@hidden create}, for more information on this.
+
+In this example, you type the command as shown above: @option{--create}
+is the operation which creates the new archive
+(@file{collection.tar}), and @option{--file} is the option which lets
+you give it the name you chose. The files, @file{blues}, @file{folk},
+and @file{jazz}, are now members of the archive, @file{collection.tar}
+(they are @dfn{file name arguments} to the @option{--create} operation.
address@hidden, for the detailed discussion on these.) Now that they are
+in the archive, they are called @emph{archive members}, not files.
+(@pxref{Definitions,members}).
+
+When you create an archive, you @emph{must} specify which files you
+want placed in the archive. If you do not specify any archive
+members, @acronym{GNU} @command{tar} will complain.
+
+If you now list the contents of the working directory (@command{ls}), you will
+find the archive file listed as well as the files you saw previously:
+
address@hidden
+blues folk jazz collection.tar
address@hidden smallexample
+
address@hidden
+Creating the archive @samp{collection.tar} did not destroy the copies of
+the files in the directory.
+
+Keep in mind that if you don't indicate an operation, @command{tar} will not
+run and will prompt you for one. If you don't name any files, @command{tar}
+will complain. You must have write access to the working directory,
+or else you will not be able to create an archive in that directory.
+
address@hidden: Do not attempt to use @option{--create} (@option{-c}) to add
files to
+an existing archive; it will delete the archive and write a new one.
+Use @option{--append} (@option{-r}) instead. @xref{append}.
+
address@hidden create verbose
address@hidden Running @option{--create} with @option{--verbose}
+
address@hidden address@hidden, using with @option{--verbose}}
address@hidden address@hidden, using with @option{--create}}
+If you include the @option{--verbose} (@option{-v}) option on the command line,
address@hidden will list the files it is acting on as it is working. In
+verbose mode, the @code{create} example above would appear as:
+
address@hidden
+$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
+blues
+folk
+jazz
address@hidden smallexample
+
+This example is just like the example we showed which did not use
address@hidden, except that @command{tar} generated the remaining lines
+
+In the rest of the examples in this chapter, we will frequently use
address@hidden mode so we can show actions or @command{tar} responses that
+you would otherwise not see, and which are important for you to
+understand.
+
address@hidden short create
address@hidden Short Forms with @samp{create}
+
+As we said before, the @option{--create} (@option{-c}) operation is one of the
most
+basic uses of @command{tar}, and you will use it countless times.
+Eventually, you will probably want to use abbreviated (or ``short'')
+forms of options. A full discussion of the three different forms that
+options can take appears in @ref{Styles}; for now, here is what the
+previous example (including the @option{--verbose} (@option{-v}) option) looks
like
+using short option forms:
+
address@hidden
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+blues
+folk
+jazz
address@hidden smallexample
+
address@hidden
+As you can see, the system responds the same no matter whether you use
+long or short option forms.
+
address@hidden
address@hidden
+ One difference between using
+short and long option forms is that, although the exact placement of
+arguments following options is no more specific when using short forms,
+it is easier to become confused and make a mistake when using short
+forms. For example, suppose you attempted the above example in the
+following way:
+
address@hidden
+$ @kbd{tar -cfv collection.tar blues folk jazz}
address@hidden smallexample
+
address@hidden
+In this case, @command{tar} will make an archive file called @file{v},
+containing the files @file{blues}, @file{folk}, and @file{jazz}, because
+the @samp{v} is the closest ``file name'' to the @option{-f} option, and
+is thus taken to be the chosen archive file name. @command{tar} will try
+to add a file called @file{collection.tar} to the @file{v} archive file;
+if the file @file{collection.tar} did not already exist, @command{tar} will
+report an error indicating that this file does not exist. If the file
address@hidden does already exist (e.g., from a previous command
+you may have run), then @command{tar} will add this file to the archive.
+Because the @option{-v} option did not get registered, @command{tar} will not
+run under @samp{verbose} mode, and will not report its progress.
+
+The end result is that you may be quite confused about what happened,
+and possibly overwrite a file. To illustrate this further, we will show
+you how an example we showed previously would look using short forms.
+
+This example,
+
address@hidden
+$ @kbd{tar blues --create folk --file=collection.tar jazz}
address@hidden smallexample
+
address@hidden
+is confusing as it is. When shown using short forms, however, it
+becomes much more so:
+
address@hidden
+$ @kbd{tar blues -c folk -f collection.tar jazz}
address@hidden smallexample
+
address@hidden
+It would be very easy to put the wrong string of characters
+immediately following the @option{-f}, but doing that could sacrifice
+valuable data.
+
+For this reason, we recommend that you pay very careful attention to
+the order of options and placement of file and archive names,
+especially when using short option forms. Not having the option name
+written out mnemonically can affect how well you remember which option
+does what, and therefore where different names have to be placed.
+
address@hidden create dir
address@hidden Archiving Directories
+
address@hidden Archiving Directories
address@hidden Directories, Archiving
+You can archive a directory by specifying its directory name as a
+file name argument to @command{tar}. The files in the directory will be
+archived relative to the working directory, and the directory will be
+re-created along with its contents when the archive is extracted.
+
+To archive a directory, first move to its superior directory. If you
+have followed the previous instructions in this tutorial, you should
+type:
+
address@hidden
+$ @kbd{cd ..}
+$
address@hidden smallexample
+
address@hidden
+This will put you into the directory which contains @file{practice},
+i.e., your home directory. Once in the superior directory, you can
+specify the subdirectory, @file{practice}, as a file name argument. To
+store @file{practice} in the new archive file @file{music.tar}, type:
+
address@hidden
+$ @kbd{tar --create --verbose --file=music.tar practice}
address@hidden smallexample
+
address@hidden
address@hidden should output:
+
address@hidden
+practice/
+practice/blues
+practice/folk
+practice/jazz
+practice/collection.tar
address@hidden smallexample
+
+Note that the archive thus created is not in the subdirectory
address@hidden, but rather in the current working directory---the
+directory from which @command{tar} was invoked. Before trying to archive a
+directory from its superior directory, you should make sure you have
+write access to the superior directory itself, not only the directory
+you are trying archive with @command{tar}. For example, you will probably
+not be able to store your home directory in an archive by invoking
address@hidden from the root directory; @xref{absolute}. (Note
+also that @file{collection.tar}, the original archive file, has itself
+been archived. @command{tar} will accept any file as a file to be
+archived, regardless of its content. When @file{music.tar} is
+extracted, the archive file @file{collection.tar} will be re-written
+into the file system).
+
+If you give @command{tar} a command such as
+
address@hidden
+$ @kbd{tar --create --file=foo.tar .}
address@hidden smallexample
+
address@hidden
address@hidden will report @samp{tar: ./foo.tar is the archive; not
+dumped}. This happens because @command{tar} creates the archive
address@hidden in the current directory before putting any files into
+it. Then, when @command{tar} attempts to add all the files in the
+directory @file{.} to the archive, it notices that the file
address@hidden/foo.tar} is the same as the archive @file{foo.tar}, and skips
+it. (It makes no sense to put an archive into itself.) @acronym{GNU}
@command{tar}
+will continue in this case, and create the archive
+normally, except for the exclusion of that one file. (@emph{Please
+note:} Other implementations of @command{tar} may not be so clever;
+they will enter an infinite loop when this happens, so you should not
+depend on this behavior unless you are certain you are running
address@hidden @command{tar}. In general, it is wise to always place the
archive outside
+of the directory being dumped.
+
address@hidden list
address@hidden How to List Archives
+
address@hidden list
+Frequently, you will find yourself wanting to determine exactly what a
+particular archive contains. You can use the @option{--list}
+(@option{-t}) operation to get the member names as they currently
+appear in the archive, as well as various attributes of the files at
+the time they were archived. For example, you can examine the archive
address@hidden that you created in the last section with the
+command,
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
address@hidden smallexample
+
address@hidden
+The output of @command{tar} would then be:
+
address@hidden
+blues
+folk
+jazz
address@hidden smallexample
+
address@hidden
+The archive @file{bfiles.tar} would list as follows:
+
address@hidden
+./birds
+baboon
+./box
address@hidden smallexample
+
address@hidden
+Be sure to use a @address@hidden (@option{-f
address@hidden) option just as with @option{--create}
+(@option{-c}) to specify the name of the archive.
+
address@hidden address@hidden, using with @option{--verbose}}
address@hidden address@hidden, using with @option{--list}}
+If you use the @option{--verbose} (@option{-v}) option with
address@hidden, then @command{tar} will print out a listing
+reminiscent of @address@hidden -l}}, showing owner, file size, and so
+forth. This output is described in detail in @ref{verbose member listing}.
+
+If you had used @option{--verbose} (@option{-v}) mode, the example
+above would look like:
+
address@hidden
+$ @kbd{tar --list --verbose --file=collection.tar folk}
+-rw-r--r-- myself user 62 1990-05-23 10:55 folk
address@hidden smallexample
+
address@hidden listing member and file names
address@hidden member and file names}
+It is important to notice that the output of @kbd{tar --list
+--verbose} does not necessarily match that produced by @kbd{tar
+--create --verbose} while creating the archive. It is because
address@hidden @command{tar}, unless told explicitly not to do so, removes some
directory
+prefixes from file names before storing them in the archive
+(@xref{absolute}, for more information). In other
+words, in verbose mode @acronym{GNU} @command{tar} shows @dfn{file names} when
creating
+an archive and @dfn{member names} when listing it. Consider this
+example:
+
address@hidden
address@hidden
+$ @kbd{tar cfv archive /etc/mail}
+tar: Removing leading `/' from member names
+/etc/mail/
+/etc/mail/sendmail.cf
+/etc/mail/aliases
+$ @kbd{tar tf archive}
+etc/mail/
+etc/mail/sendmail.cf
+etc/mail/aliases
address@hidden group
address@hidden smallexample
+
address@hidden show-stored-names
+ This default behavior can sometimes be inconvenient. You can force
address@hidden @command{tar} show member names when creating archive by
supplying
address@hidden option.
+
address@hidden @option
address@hidden --show-stored-names
+Print member (as opposed to @emph{file}) names when creating the archive.
address@hidden table
+
address@hidden File name arguments, using @option{--list} with
address@hidden address@hidden, using with file name arguments}
+You can specify one or more individual member names as arguments when
+using @samp{list}. In this case, @command{tar} will only list the
+names of members you identify. For example, @address@hidden --list
+--file=afiles.tar apple}} would only print @file{apple}.
+
+Because @command{tar} preserves paths, file names must be specified as
+they appear in the archive (i.e., relative to the directory from which
+the archive was created). Therefore, it is essential when specifying
+member names to @command{tar} that you give the exact member names.
+For example, @address@hidden --list --file=bfiles.tar birds}} would produce an
+error message something like @samp{tar: birds: Not found in archive},
+because there is no member named @file{birds}, only one named
address@hidden/birds}. While the names @file{birds} and @file{./birds} name
+the same file, @emph{member} names by default are compared verbatim.
+
+However, @address@hidden --list --file=bfiles.tar baboon}} would respond
+with @file{baboon}, because this exact member name is in the archive file
address@hidden If you are not sure of the exact file name,
+use @dfn{globbing patterns}, for example:
+
address@hidden
+$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'}
address@hidden smallexample
+
address@hidden
+will list all members whose name contains @samp{b}. @xref{wildcards},
+for a detailed discussion of globbing patterns and related
address@hidden command line options.
+
address@hidden
+* list dir::
address@hidden menu
+
address@hidden list dir
address@hidden Listing the Contents of a Stored Directory
+
+To get information about the contents of an archived directory,
+use the directory name as a file name argument in conjunction with
address@hidden (@option{-t}). To find out file attributes, include the
address@hidden (@option{-v}) option.
+
+For example, to find out about files in the directory @file{practice}, in
+the archive file @file{music.tar}, type:
+
address@hidden
+$ @kbd{tar --list --verbose --file=music.tar practice}
address@hidden smallexample
+
address@hidden responds:
+
address@hidden
+drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
+-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
address@hidden smallexample
+
+When you use a directory name as a file name argument, @command{tar} acts on
+all the files (including sub-directories) in that directory.
+
address@hidden extract
address@hidden How to Extract Members from an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Extraction
address@hidden Retrieving files from an archive
address@hidden Resurrecting files from an archive
+
address@hidden extract
+Creating an archive is only half the job---there is no point in storing
+files in an archive if you can't retrieve them. The act of retrieving
+members from an archive so they can be used and manipulated as
+unarchived files again is called @dfn{extraction}. To extract files
+from an archive, use the @option{--extract} (@option{--get} or
address@hidden) operation. As with @option{--create}, specify the name
+of the archive with @option{--file} (@option{-f}) option. Extracting
+an archive does not modify the archive in any way; you can extract it
+multiple times if you want or need to.
+
+Using @option{--extract}, you can extract an entire archive, or specific
+files. The files can be directories containing other files, or not. As
+with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you
may use the short or the
+long form of the operation without affecting the performance.
+
address@hidden
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
address@hidden menu
+
address@hidden extracting archives
address@hidden Extracting an Entire Archive
+
+To extract an entire archive, specify the archive file name only, with
+no individual file names as arguments. For example,
+
address@hidden
+$ @kbd{tar -xvf collection.tar}
address@hidden smallexample
+
address@hidden
+produces this:
+
address@hidden
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
address@hidden smallexample
+
address@hidden extracting files
address@hidden Extracting Specific Files
+
+To extract specific archive members, give their exact member names as
+arguments, as printed by @option{--list} (@option{-t}). If you had
+mistakenly deleted one of the files you had placed in the archive
address@hidden earlier (say, @file{blues}), you can extract it
+from the archive without changing the archive's structure. Its
+contents will be identical to the original file @file{blues} that you
+deleted.
+
+First, make sure you are in the @file{practice} directory, and list the
+files in the directory. Now, delete the file, @samp{blues}, and list
+the files in the directory again.
+
+You can now extract the member @file{blues} from the archive file
address@hidden like this:
+
address@hidden
+$ @kbd{tar --extract --file=collection.tar blues}
address@hidden smallexample
+
address@hidden
+If you list the files in the directory again, you will see that the file
address@hidden has been restored, with its original permissions, data
+modification times, and address@hidden is only accidentally
+true, but not in general. Whereas modification times are always
+restored, in most cases, one has to be root for restoring the owner,
+and use a special option for restoring permissions. Here, it just
+happens that the restoring user is also the owner of the archived
+members, and that the current @code{umask} is compatible with original
+permissions.} (These parameters will be identical to those which
+the file had when you originally placed it in the archive; any changes
+you may have made before deleting the file from the file system,
+however, will @emph{not} have been made to the archive member.) The
+archive file, @samp{collection.tar}, is the same as it was before you
+extracted @samp{blues}. You can confirm this by running @command{tar} with
address@hidden (@option{-t}).
+
+Remember that as with other operations, specifying the exact member
+name is important. @address@hidden --extract --file=bfiles.tar birds}}
+will fail, because there is no member named @file{birds}. To extract
+the member named @file{./birds}, you must specify @address@hidden
+--extract --file=bfiles.tar ./birds}}. If you don't remember the
+exact member names, use @option{--list} (@option{-t}) option
+(@pxref{list}). You can also extract those members that match a
+specific @dfn{globbing pattern}. For example, to extract from
address@hidden all files that begin with @samp{b}, no matter their
+directory prefix, you could type:
+
address@hidden
+$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'}
address@hidden smallexample
+
address@hidden
+Here, @option{--wildcards} instructs @command{tar} to treat
+command line arguments as globbing patterns and @option{--no-anchored}
+informs it that the patterns apply to member names after any @samp{/}
+delimiter. The use of globbing patterns is discussed in detail in
address@hidden
+
+You can extract a file to standard output by combining the above options
+with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard
+Output}).
+
+If you give the @option{--verbose} option, then @option{--extract}
+will print the names of the archive members as it extracts them.
+
address@hidden extract dir
address@hidden Extracting Files that are Directories
+
+Extracting directories which are members of an archive is similar to
+extracting other files. The main difference to be aware of is that if
+the extracted directory has the same name as any directory already in
+the working directory, then files in the extracted directory will be
+placed into the directory of the same name. Likewise, if there are
+files in the pre-existing directory with the same names as the members
+which you extract, the files from the extracted archive will replace
+the files already in the working directory (and possible
+subdirectories). This will happen regardless of whether or not the
+files in the working directory were more recent than those extracted
+(there exist, however, special options that alter this behavior
address@hidden).
+
+However, if a file was stored with a directory name as part of its file
+name, and that directory does not exist under the working directory when
+the file is extracted, @command{tar} will create the directory.
+
+We can demonstrate how to use @option{--extract} to extract a directory
+file with an example. Change to the @file{practice} directory if you
+weren't there, and remove the files @file{folk} and @file{jazz}. Then,
+go back to the parent directory and extract the archive
address@hidden You may either extract the entire archive, or you may
+extract only the files you just deleted. To extract the entire archive,
+don't give any file names as arguments after the archive name
address@hidden To extract only the files you deleted, use the
+following command:
+
address@hidden
+$ @kbd{tar -xvf music.tar practice/folk practice/jazz}
+practice/folk
+practice/jazz
address@hidden smallexample
+
address@hidden
+If you were to specify two @option{--verbose} (@option{-v}) options,
@command{tar}
+would have displayed more detail about the extracted files, as shown
+in the example below:
+
address@hidden
+$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
+-rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
+-rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
address@hidden smallexample
+
address@hidden
+Because you created the directory with @file{practice} as part of the
+file names of each of the files by archiving the @file{practice}
+directory as @file{practice}, you must give @file{practice} as part
+of the file names when you extract those files from the archive.
+
address@hidden extracting untrusted archives
address@hidden Extracting Archives from Untrusted Sources
+
+Extracting files from archives can overwrite files that already exist.
+If you receive an archive from an untrusted source, you should make a
+new directory and extract into that directory, so that you don't have
+to worry about the extraction overwriting one of your existing files.
+For example, if @file{untrusted.tar} came from somewhere else on the
+Internet, and you don't necessarily trust its contents, you can
+extract it as follows:
+
address@hidden
+$ @kbd{mkdir newdir}
+$ @kbd{cd newdir}
+$ @kbd{tar -xvf ../untrusted.tar}
address@hidden smallexample
+
+It is also a good practice to examine contents of the archive
+before extracting it, using @option{--list} (@option{-t}) option, possibly
combined
+with @option{--verbose} (@option{-v}).
+
address@hidden failing commands
address@hidden Commands That Will Fail
+
+Here are some sample commands you might try which will not work, and why
+they won't work.
+
+If you try to use this command,
+
address@hidden
+$ @kbd{tar -xvf music.tar folk jazz}
address@hidden smallexample
+
address@hidden
+you will get the following response:
+
address@hidden
+tar: folk: Not found in archive
+tar: jazz: Not found in archive
+$
address@hidden smallexample
+
address@hidden
+This is because these files were not originally @emph{in} the parent
+directory @file{..}, where the archive is located; they were in the
address@hidden directory, and their file names reflect this:
+
address@hidden
+$ @kbd{tar -tvf music.tar}
+practice/folk
+practice/jazz
+practice/rock
address@hidden smallexample
+
address@hidden
address@hidden
+
+
address@hidden
+Likewise, if you try to use this command,
+
address@hidden
+$ @kbd{tar -tvf music.tar folk jazz}
address@hidden smallexample
+
address@hidden
+you would get a similar response. Members with those names are not in the
+archive. You must use the correct member names, or wildcards, in order
+to extract the files from the archive.
+
+If you have forgotten the correct names of the files in the archive,
+use @address@hidden --list --verbose}} to list them correctly.
+
address@hidden
address@hidden
+
+
address@hidden going further
address@hidden Going Further Ahead in this Manual
+
address@hidden
address@hidden
+
+
address@hidden tar invocation
address@hidden Invoking @acronym{GNU} @command{tar}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+This chapter is about how one invokes the @acronym{GNU} @command{tar}
+command, from the command synopsis (@pxref{Synopsis}). There are
+numerous options, and many styles for writing them. One mandatory
+option specifies the operation @command{tar} should perform
+(@pxref{Operation Summary}), other options are meant to detail how
+this operation should be performed (@pxref{Option Summary}).
+Non-option arguments are not always interpreted the same way,
+depending on what the operation is.
+
+You will find in this chapter everything about option styles and rules for
+writing them (@pxref{Styles}). On the other hand, operations and options
+are fully described elsewhere, in other chapters. Here, you will find
+only synthetic descriptions for operations and options, together with
+pointers to other parts of the @command{tar} manual.
+
+Some options are so special they are fully described right in this
+chapter. They have the effect of inhibiting the normal operation of
address@hidden or else, they globally alter the amount of feedback the user
+receives about what is going on. These are the @option{--help} and
address@hidden (@pxref{help}), @option{--verbose} (@pxref{verbose})
+and @option{--interactive} options (@pxref{interactive}).
+
address@hidden
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
address@hidden menu
+
address@hidden Synopsis
address@hidden General Synopsis of @command{tar}
+
+The @acronym{GNU} @command{tar} program is invoked as either one of:
+
address@hidden
address@hidden @address@hidden address@hidden@dots{}}
address@hidden @address@hidden address@hidden@dots{} address@hidden@dots{}
address@hidden@dots{}}
address@hidden smallexample
+
+The second form is for when old options are being used.
+
+You can use @command{tar} to store files in an archive, to extract them from
+an archive, and to do other types of archive manipulation. The primary
+argument to @command{tar}, which is called the @dfn{operation}, specifies
+which action to take. The other arguments to @command{tar} are either
address@hidden, which change the way @command{tar} performs an operation,
+or file names or archive members, which specify the files or members
address@hidden is to act on.
+
+You can actually type in arguments in any order, even if in this manual
+the options always precede the other arguments, to make examples easier
+to understand. Further, the option stating the main operation mode
+(the @command{tar} main command) is usually given first.
+
+Each @var{name} in the synopsis above is interpreted as an archive member
+name when the main command is one of @option{--compare}
+(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract}
+(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or
address@hidden (@option{-u}). When naming archive members, you
+must give the exact name of the member in the archive, as it is
+printed by @option{--list}. For @option{--append} (@option{-r}) and
address@hidden (@option{-c}), these @var{name} arguments specify
+the names of either files or directory hierarchies to place in the archive.
+These files or hierarchies should already exist in the file system,
+prior to the execution of the @command{tar} command.
+
address@hidden interprets relative file names as being relative to the
+working directory. @command{tar} will make all file names relative
+(by removing leading slashes when archiving or restoring files),
+unless you specify otherwise (using the @option{--absolute-names}
+option). @xref{absolute}, for more information about
address@hidden
+
+If you give the name of a directory as either a file name or a member
+name, then @command{tar} acts recursively on all the files and directories
+beneath that directory. For example, the name @file{/} identifies all
+the files in the file system to @command{tar}.
+
+The distinction between file names and archive member names is especially
+important when shell globbing is used, and sometimes a source of confusion
+for newcomers. @xref{wildcards}, for more information about globbing.
+The problem is that shells may only glob using existing files in the
+file system. Only @command{tar} itself may glob on archive members, so when
+needed, you must ensure that wildcard characters reach @command{tar} without
+being interpreted by the shell first. Using a backslash before @samp{*}
+or @samp{?}, or putting the whole argument between quotes, is usually
+sufficient for this.
+
+Even if @var{name}s are often specified on the command line, they
+can also be read from a text file in the file system, using the
address@hidden@var{file-of-names}} (@option{-T @var{file-of-names}}) option.
+
+If you don't use any file name arguments, @option{--append} (@option{-r}),
address@hidden and @option{--concatenate} (@option{--catenate},
address@hidden) will do nothing, while @option{--create} (@option{-c})
+will usually yield a diagnostic and inhibit @command{tar} execution.
+The other operations of @command{tar} (@option{--list},
address@hidden, @option{--compare}, and @option{--update})
+will act on the entire contents of the archive.
+
address@hidden exit status
address@hidden return status
+Besides successful exits, @acronym{GNU} @command{tar} may fail for
+many reasons. Some reasons correspond to bad usage, that is, when the
address@hidden command is improperly written. Errors may be
+encountered later, while encountering an error processing the archive
+or the files. Some errors are recoverable, in which case the failure
+is delayed until @command{tar} has completed all its work. Some
+errors are such that it would not meaningful, or at least risky, to
+continue processing: @command{tar} then aborts processing immediately.
+All abnormal exits, whether immediate or delayed, should always be
+clearly diagnosed on @code{stderr}, after a line stating the nature of
+the error.
+
address@hidden @command{tar} returns only a few exit statuses. I'm really
+aiming simplicity in that area, for now. If you are not using the
address@hidden @option{--diff}, @option{-d}) option, zero means
+that everything went well, besides maybe innocuous warnings. Nonzero
+means that something went wrong. Right now, as of today, ``nonzero''
+is almost always 2, except for remote operations, where it may be
+128.
+
address@hidden using tar options
address@hidden Using @command{tar} Options
+
address@hidden @command{tar} has a total of eight operating modes which
+allow you to perform a variety of tasks. You are required to choose
+one operating mode each time you employ the @command{tar} program by
+specifying one, and only one operation as an argument to the
address@hidden command (two lists of four operations each may be found
+at @ref{frequent operations} and @ref{Operations}). Depending on
+circumstances, you may also wish to customize how the chosen operating
+mode behaves. For example, you may wish to change the way the output
+looks, or the format of the files that you wish to archive may require
+you to do something special in order to make the archive look right.
+
+You can customize and control @command{tar}'s performance by running
address@hidden with one or more options (such as @option{--verbose}
+(@option{-v}), which we used in the tutorial). As we said in the
+tutorial, @dfn{options} are arguments to @command{tar} which are (as
+their name suggests) optional. Depending on the operating mode, you
+may specify one or more options. Different options will have different
+effects, but in general they all change details of the operation, such
+as archive format, archive name, or level of user interaction. Some
+options make sense with all operating modes, while others are
+meaningful only with particular modes. You will likely use some
+options frequently, while you will only use others infrequently, or
+not at all. (A full list of options is available in @pxref{All Options}.)
+
address@hidden TAR_OPTIONS, environment variable
address@hidden
+The @env{TAR_OPTIONS} environment variable specifies default options to
+be placed in front of any explicit options. For example, if
address@hidden is @samp{-v --unlink-first}, @command{tar} behaves as
+if the two options @option{-v} and @option{--unlink-first} had been
+specified before any explicit options. Option specifications are
+separated by whitespace. A backslash escapes the next character, so it
+can be used to specify an option containing whitespace or a backslash.
+
+Note that @command{tar} options are case sensitive. For example, the
+options @option{-T} and @option{-t} are different; the first requires an
+argument for stating the name of a file providing a list of @var{name}s,
+while the second does not require an argument and is another way to
+write @option{--list} (@option{-t}).
+
+In addition to the eight operations, there are many options to
address@hidden, and three different styles for writing both: long (mnemonic)
+form, short form, and old style. These styles are discussed below.
+Both the options and the operations can be written in any of these three
+styles.
+
address@hidden
address@hidden
+
+
address@hidden Styles
address@hidden The Three Option Styles
+
+There are three styles for writing operations and options to the command
+line invoking @command{tar}. The different styles were developed at
+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
+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
+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
+subtle, yet can often be very important; incorrect option placement
+can cause you to overwrite a number of important files. We urge you
+to note these differences, and only use the option style(s) which
+makes the most sense to you until you feel comfortable with the others.
+
+Some options @emph{may} take an argument. Such options may have at
+most long and short forms, they do not have old style equivalent. The
+rules for specifying an argument for such options are stricter than
+those for specifying mandatory arguments. Please, pay special
+attention to them.
+
address@hidden
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
address@hidden menu
+
address@hidden Long Options
address@hidden Long Option Style
+
+Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with
two
+dashes in a row, e.g., @option{--list}. The long names are more clear than
+their corresponding short or old names. It sometimes happens that a
+single long option has many different different names which are
+synonymous, such as @option{--compare} and @option{--diff}. In addition,
+long option names can be given unique abbreviations. For example,
address@hidden can be used in place of @option{--create} because there is no
+other long option which begins with @samp{cre}. (One way to find
+this out is by trying it and seeing what happens; if a particular
+abbreviation could represent more than one option, @command{tar} will tell
+you that that abbreviation is ambiguous and you'll know that that
+abbreviation won't work. You may also choose to run @samp{tar --help}
+to see a list of options. Be aware that if you run @command{tar} with a
+unique abbreviation for the long name of an option you didn't want to
+use, you are stuck; @command{tar} will perform the command as ordered.)
+
+Long options are meant to be obvious and easy to remember, and their
+meanings are generally easier to discern than those of their
+corresponding short options (see below). For example:
+
address@hidden
+$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
address@hidden smallexample
+
address@hidden
+gives a fairly good set of hints about what the command does, even
+for those not fully acquainted with @command{tar}.
+
+Long options which require arguments take those arguments
+immediately following the option name. There are two ways of
+specifying a mandatory argument. It can be separated from the
+option name either by an equal sign, or by any amount of
+white space characters. For example, the @option{--file} option (which
+tells the name of the @command{tar} archive) is given a file such as
address@hidden as argument by using any of the following notations:
address@hidden or @option{--file archive.tar}.
+
+In contrast, optional arguments must always be introduced using
+an equal sign. For example, the @option{--backup} option takes
+an optional argument specifying backup type. It must be used
+as @address@hidden
+
address@hidden Short Options
address@hidden Short Option Style
+
+Most options also have a @dfn{short option} name. Short options start with
+a single dash, and are followed by a single character, e.g., @option{-t}
+(which is equivalent to @option{--list}). The forms are absolutely
+identical in function; they are interchangeable.
+
+The short option names are faster to type than long option names.
+
+Short options which require arguments take their arguments immediately
+following the option, usually separated by white space. It is also
+possible to stick the argument right after the short option name, using
+no intervening space. For example, you might write @address@hidden
+archive.tar}} or @option{-farchive.tar} instead of using
address@hidden Both @address@hidden and
address@hidden@option{-f @var{archive-name}}} denote the option which indicates
a
+specific archive, here named @file{archive.tar}.
+
+Short options which take optional arguments take their arguments
+immediately following the option letter, @emph{without any intervening
+white space characters}.
+
+Short options' letters may be clumped together, but you are not
+required to do this (as compared to old options; see below). When
+short options are clumped as a set, use one (single) dash for them
+all, e.g., @address@hidden@command{tar} -cvf}}. Only the last option in
+such a set is allowed to have an address@hidden many
+options, the last of which has an argument, is a rather opaque way to
+write options. Some wonder if @acronym{GNU} @code{getopt} should not
+even be made helpful enough for considering such usages as invalid.}.
+
+When the options are separated, the argument for each option which requires
+an argument directly follows that option, as is usual for Unix programs.
+For example:
+
address@hidden
+$ @kbd{tar -c -v -b 20 -f /dev/rmt0}
address@hidden smallexample
+
+If you reorder short options' locations, be sure to move any arguments
+that belong to them. If you do not move the arguments properly, you may
+end up overwriting files.
+
address@hidden Old Options
address@hidden Old Option Style
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Like short options, @dfn{old options} are single letters. However, old options
+must be written together as a single clumped set, without spaces separating
+them or dashes preceding address@hidden that if you precede options
+with a dash, you are announcing the short option style instead of the
+old option style; short options are decoded differently.}. This set
+of letters must be the first to appear on the command line, after the
address@hidden program name and some white space; old options cannot appear
+anywhere else. The letter of an old option is exactly the same letter as
+the corresponding short option. For example, the old option @samp{t} is
+the same as the short option @option{-t}, and consequently, the same as the
+long option @option{--list}. So for example, the command @address@hidden
+cv}} specifies the option @option{-v} in addition to the operation @option{-c}.
+
+When options that need arguments are given together with the command,
+all the associated arguments follow, in the same order as the options.
+Thus, the example given previously could also be written in the old
+style as follows:
+
address@hidden
+$ @kbd{tar cvbf 20 /dev/rmt0}
address@hidden smallexample
+
address@hidden
+Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
+the argument of @option{-f}.
+
+On the other hand, this old style syntax makes it difficult to match
+option letters with their corresponding arguments, and is often
+confusing. In the command @address@hidden cvbf 20 /dev/rmt0}}, for example,
address@hidden is the argument for @option{-b}, @samp{/dev/rmt0} is the
+argument for @option{-f}, and @option{-v} does not have a corresponding
+argument. Even using short options like in @address@hidden -c -v -b 20 -f
+/dev/rmt0}} is clearer, putting all arguments next to the option they
+pertain to.
+
+If you want to reorder the letters in the old option argument, be
+sure to reorder any corresponding argument appropriately.
+
+This old way of writing @command{tar} options can surprise even experienced
+users. For example, the two commands:
+
address@hidden
address@hidden cfz archive.tar.gz file}
address@hidden -cfz archive.tar.gz file}
address@hidden smallexample
+
address@hidden
+are quite different. The first example uses @file{archive.tar.gz} as
+the value for option @samp{f} and recognizes the option @samp{z}. The
+second example, however, uses @file{z} as the value for option
address@hidden --- probably not what was intended.
+
+Old options are kept for compatibility with old versions of @command{tar}.
+
+This second example could be corrected in many ways, among which the
+following are equivalent:
+
address@hidden
address@hidden -czf archive.tar.gz file}
address@hidden -cf archive.tar.gz -z file}
address@hidden cf archive.tar.gz -z file}
address@hidden smallexample
+
address@hidden option syntax, traditional
+As far as we know, all @command{tar} programs, @acronym{GNU} and
address@hidden, support old options. @acronym{GNU} @command{tar}
+supports them not only for historical reasons, but also because many
+people are used to them. For compatibility with Unix @command{tar},
+the first argument is always treated as containing command and option
+letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
+equivalent to @address@hidden -c}:} both of them specify the
address@hidden (@option{-c}) command to create an archive.
+
address@hidden Mixing
address@hidden Mixing Option Styles
+
+All three styles may be intermixed in a single @command{tar} command,
+so long as the rules for each style are fully
address@hidden @acronym{GNU} @command{tar} version 1.11.6,
+a bug prevented intermixing old style options with long options in
+some cases.}. Old style options and either of the modern styles of
+options may be mixed within a single @command{tar} command. However,
+old style options must be introduced as the first arguments only,
+following the rule for old options (old options must appear directly
+after the @command{tar} command and some white space). Modern options
+may be given only after all arguments to the old options have been
+collected. If this rule is not respected, a modern option might be
+falsely interpreted as the value of the argument to one of the old
+style options.
+
+For example, all the following commands are wholly equivalent, and
+illustrate the many combinations and orderings of option styles.
+
address@hidden
address@hidden --create --file=archive.tar}
address@hidden --create -f archive.tar}
address@hidden --create -farchive.tar}
address@hidden --file=archive.tar --create}
address@hidden --file=archive.tar -c}
address@hidden -c --file=archive.tar}
address@hidden -c -f archive.tar}
address@hidden -c -farchive.tar}
address@hidden -cf archive.tar}
address@hidden -cfarchive.tar}
address@hidden -f archive.tar --create}
address@hidden -f archive.tar -c}
address@hidden -farchive.tar --create}
address@hidden -farchive.tar -c}
address@hidden c --file=archive.tar}
address@hidden c -f archive.tar}
address@hidden c -farchive.tar}
address@hidden cf archive.tar}
address@hidden f archive.tar --create}
address@hidden f archive.tar -c}
address@hidden fc archive.tar}
address@hidden smallexample
+
+On the other hand, the following commands are @emph{not} equivalent to
+the previous set:
+
address@hidden
address@hidden -f -c archive.tar}
address@hidden -fc archive.tar}
address@hidden -fcarchive.tar}
address@hidden -farchive.tarc}
address@hidden cfarchive.tar}
address@hidden smallexample
+
address@hidden
+These last examples mean something completely different from what the
+user intended (judging based on the example in the previous set which
+uses long options, whose intent is therefore very clear). The first
+four specify that the @command{tar} archive would be a file named
address@hidden, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc},
+respectively. The first two examples also specify a single non-option,
address@hidden argument having the value @samp{archive.tar}. The last
+example contains only old style option letters (repeating option
address@hidden twice), not all of which are meaningful (eg., @samp{.},
address@hidden, or @samp{i}), with no argument value. @allow-recursion
address@hidden
+
+
address@hidden All Options
address@hidden All @command{tar} Options
+
+The coming manual sections contain an alphabetical listing of all
address@hidden 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.
+
address@hidden
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
address@hidden menu
+
address@hidden Operation Summary
address@hidden Operations
+
address@hidden @option
+
address@hidden ANCHOR--append 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --append
address@hidden -r
+
+Appends files to the end of the archive. @xref{append}.
+
address@hidden ANCHOR--catenate 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --catenate
address@hidden -A
+
+Same as @option{--concatenate}. @xref{concatenate}.
+
address@hidden ANCHOR--compare 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --compare
address@hidden -d
+
+Compares archive members with their counterparts in the file
+system, and reports differences in file size, mode, owner,
+modification date and contents. @xref{compare}.
+
address@hidden ANCHOR--concatenate 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --concatenate
address@hidden -A
+
+Appends other @command{tar} archives to the end of the archive.
address@hidden
+
address@hidden ANCHOR--create 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --create
address@hidden -c
+
+Creates a new @command{tar} archive. @xref{create}.
+
address@hidden ANCHOR--delete 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --delete
+
+Deletes members from the archive. Don't try this on a archive on a
+tape! @xref{delete}.
+
address@hidden ANCHOR--diff 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --diff
address@hidden -d
+
+Same @option{--compare}. @xref{compare}.
+
address@hidden ANCHOR--extract 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --extract
address@hidden -x
+
+Extracts members from the archive into the file system. @xref{extract}.
+
address@hidden ANCHOR--get 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --get
address@hidden -x
+
+Same as @option{--extract}. @xref{extract}.
+
address@hidden ANCHOR--list 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --list
address@hidden -t
+
+Lists the members in an archive. @xref{list}.
+
address@hidden ANCHOR--update 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --update
address@hidden -u
+
+Adds files to the end of the archive, but only if they are newer than
+their counterparts already in the archive, or if they do not already
+exist in the archive. @xref{update}.
+
address@hidden table
+
address@hidden Option Summary
address@hidden @command{tar} Options
+
address@hidden @option
+
address@hidden ANCHOR--absolute-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --absolute-names
address@hidden -P
+
+Normally when creating an archive, @command{tar} strips an initial
address@hidden/} from member names. This option disables that behavior.
address@hidden
+
address@hidden ANCHOR--after-date 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --after-date
+
+(See @option{--newer}, @pxref{after})
+
address@hidden ANCHOR--anchored 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --anchored
+A pattern must match an initial subsequence of the name's components.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--atime-preserve 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --atime-preserve
address@hidden --atime-preserve=replace
address@hidden --atime-preserve=system
+
+Attempt to preserve the access time of files when reading them. This
+option currently is effective only on files that you own, unless you
+have superuser privileges.
+
address@hidden remembers the access time of a file
+before reading it, and then restores the access time afterwards. This
+may cause problems if other programs are reading the file at the same
+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
+to detect this situation, but cannot do so reliably due to race
+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.
+
address@hidden avoids changing time stamps on files,
+without interfering with time stamp updates
+caused by other programs, so it works better with incremental backups.
+However, it requires a special @code{O_NOATIME} option from the
+underlying operating and file system implementation, and it also requires
+that searching directories does not update their access times. As of
+this writing (November 2005) this works only with Linux, and only with
+Linux kernels 2.6.8 and later. Worse, there is currently no reliable
+way to know whether this feature actually works. Sometimes
address@hidden knows that it does not work, and if you use
address@hidden then @command{tar} complains and
+exits right away. But other times @command{tar} might think that the
+option works when it actually does not.
+
+Currently @option{--atime-preserve} with no operand defaults to
address@hidden, but this may change in the future
+as support for @option{--atime-preserve=system} improves.
+
+If your operating system does not support
address@hidden@-system}, you might be able to preserve access
+times reliably by 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
+superuser privileges and can be a pain to manage.
+
address@hidden ANCHOR--backup 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Rather than deleting files from the file system, @command{tar} will
+back them up using simple or numbered backups, depending upon
address@hidden @xref{backup}.
+
address@hidden ANCHOR--block-number 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --block-number
address@hidden -R
+
+With this option present, @command{tar} prints error messages for read errors
+with the block number in the archive file. @xref{block-number}.
+
address@hidden ANCHOR--blocking-factor 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -b @var{blocking}
+
+Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per
+record. @xref{Blocking Factor}.
+
address@hidden ANCHOR--bzip2 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --bzip2
address@hidden -j
+
+This option tells @command{tar} to read or write archives through
address@hidden @xref{gzip}.
+
address@hidden ANCHOR--checkpoint 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+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}.
+
address@hidden ANCHOR--check-links 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --check-links
address@hidden -l
+If this option was given, @command{tar} will 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, a warning message will be
+output @footnote{Earlier versions of @acronym{GNU} @command{tar} understood
@option{-l} as a
+synonym for @option{--one-file-system}. The current semantics, which
+complies to UNIX98, was introduced with version
+1.15.91. @xref{Changes}, for more information.}.
+
address@hidden ANCHOR--compress 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--uncompress 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --compress
address@hidden --uncompress
address@hidden -Z
+
address@hidden will use the @command{compress} program when reading or
+writing the archive. This allows you to directly act on archives
+while saving space. @xref{gzip}.
+
address@hidden ANCHOR--confirmation 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --confirmation
+
+(See @option{--interactive}.) @xref{interactive}.
+
address@hidden ANCHOR--delay-directory-restore 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --delay-directory-restore
+
+Delay setting modification times and permissions of extracted
+directories until the end of extraction. @xref{Directory Modification Times
and Permissions}.
+
address@hidden ANCHOR--dereference 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --dereference
address@hidden -h
+
+When creating a @command{tar} archive, @command{tar} will archive the
+file that a symbolic link points to, rather than archiving the
+symlink. @xref{dereference}.
+
address@hidden ANCHOR--directory 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -C @var{dir}
+
+When this option is specified, @command{tar} will change its current directory
+to @var{dir} before performing any operations. When this option is used
+during archive creation, it is order sensitive. @xref{directory}.
+
address@hidden ANCHOR--exclude 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When performing operations, @command{tar} will skip files that match
address@hidden @xref{exclude}.
+
address@hidden ANCHOR--exclude-from 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -X @var{file}
+
+Similar to @option{--exclude}, except @command{tar} will use the list of
+patterns in the file @var{file}. @xref{exclude}.
+
address@hidden ANCHOR--exclude-caches 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --exclude-caches
+
+Automatically excludes all directories
+containing a cache directory tag. @xref{exclude}.
+
address@hidden ANCHOR--file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -f @var{archive}
+
address@hidden will use the file @var{archive} as the @command{tar} archive it
+performs operations on, rather than @command{tar}'s compilation dependent
+default. @xref{file tutorial}.
+
address@hidden ANCHOR--files-from 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -T @var{file}
+
address@hidden will use the contents of @var{file} as a list of archive members
+or files to operate on, in addition to those specified on the
+command-line. @xref{files}.
+
address@hidden ANCHOR--force-local 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --force-local
+
+Forces @command{tar} to interpret the filename given to @option{--file}
+as a local file, even if it looks like a remote tape drive name.
address@hidden and remote archives}.
+
address@hidden ANCHOR--format 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -H @var{format}
+
+Selects output archive format. @var{Format} may be one of the
+following:
+
address@hidden @samp
address@hidden v7
+Creates an archive that is compatible with Unix V7 @command{tar}.
+
address@hidden oldgnu
+Creates an archive that is compatible with GNU @command{tar} version
+1.12 or earlier.
+
address@hidden gnu
+Creates archive in GNU tar 1.13 format. Basically it is the same as
address@hidden with the only difference in the way it handles long
+numeric fields.
+
address@hidden ustar
+Creates a @acronym{POSIX.1-1988} compatible archive.
+
address@hidden posix
+Creates a @acronym{POSIX.1-2001 archive}.
+
address@hidden table
+
address@hidden, for a detailed discussion of these formats.
+
address@hidden ANCHOR--group 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Files added to the @command{tar} archive will have a group id of @var{group},
+rather than the group from the source file. @var{group} is first decoded
+as a group symbolic name, but if this interpretation fails, it has to be
+a decimal numeric group ID. @xref{override}.
+
+Also see the comments for the @address@hidden option.
+
address@hidden ANCHOR--gzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--gunzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--ungzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --gzip
address@hidden --gunzip
address@hidden --ungzip
address@hidden -z
+
+This option tells @command{tar} to read or write archives through
address@hidden, allowing @command{tar} to directly operate on several
+kinds of compressed archives transparently. @xref{gzip}.
+
address@hidden ANCHOR--help 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --help
address@hidden -?
+
address@hidden will print out a short message summarizing the operations and
+options to @command{tar} and exit. @xref{help}.
+
address@hidden ANCHOR--ignore-case 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-case
+Ignore case when matching member or file names with
+patterns. @xref{controlling pattern-matching}.
+
address@hidden ANCHOR--ignore-command-error 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-command-error
+Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--ignore-failed-read 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-failed-read
+
+Do not exit unsuccessfully merely because an unreadable file was encountered.
address@hidden
+
address@hidden ANCHOR--ignore-zeros 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-zeros
address@hidden -i
+
+With this option, @command{tar} will ignore zeroed blocks in the
+archive, which normally signals EOF. @xref{Reading}.
+
address@hidden ANCHOR--incremental 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --incremental
address@hidden -G
+
+Used to inform @command{tar} that it is working with an old
address@hidden incremental backup archive. It is intended
+primarily for backwards compatibility only. @xref{Incremental Dumps},
+for a detailed discussion of incremental archives.
+
address@hidden ANCHOR--index-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Send verbose output to @var{file} instead of to standard output.
+
address@hidden ANCHOR--info-script 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--new-volume-script 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden address@hidden
address@hidden -F @var{script-file}
+
+When @command{tar} is performing multi-tape backups, @var{script-file} is run
+at the end of each tape. If @var{script-file} exits with nonzero status,
address@hidden fails immediately. @xref{info-script}, for a detailed
+discussion of @var{script-file}.
+
address@hidden ANCHOR--interactive 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --interactive
address@hidden --confirmation
address@hidden -w
+
+Specifies that @command{tar} should ask the user for confirmation before
+performing potentially destructive options, such as overwriting files.
address@hidden
+
address@hidden ANCHOR--keep-newer-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --keep-newer-files
+
+Do not replace existing files that are newer than their archive copies
+when extracting files from an archive.
+
address@hidden ANCHOR--keep-old-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --keep-old-files
address@hidden -k
+
+Do not overwrite existing files when extracting files from an archive.
address@hidden Old Files}.
+
address@hidden ANCHOR--label 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -V @var{name}
+
+When creating an archive, instructs @command{tar} to write @var{name}
+as a name record in the archive. When extracting or listing archives,
address@hidden will only operate on archives that have a label matching
+the pattern specified in @var{name}. @xref{Tape Files}.
+
address@hidden ANCHOR--listed-incremental 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -g @var{snapshot-file}
+
+During a @option{--create} operation, specifies that the archive that
address@hidden creates is a new @acronym{GNU}-format incremental
+backup, using @var{snapshot-file} to determine which files to backup.
+With other operations, informs @command{tar} that the archive is in
+incremental format. @xref{Incremental Dumps}.
+
address@hidden ANCHOR--mode 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use
address@hidden for the archive members, rather than the permissions
+from the files. @var{permissions} can be specified either as an octal
+number or as symbolic permissions, like with
address@hidden @xref{override}.
+
address@hidden ANCHOR--mtime 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use @var{date} as
+the modification time of members when creating archives, instead of
+their actual modification times. The value of @var{date} can be
+either a textual date representation (@pxref{Date input formats}) or a
+name of the existing file, starting with @samp{/} or @samp{.}. In the
+latter case, the modification time of that file is used. @xref{override}.
+
address@hidden ANCHOR--multi-volume 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --multi-volume
address@hidden -M
+
+Informs @command{tar} that it should create or otherwise operate on a
+multi-volume @command{tar} archive. @xref{Using Multiple Tapes}.
+
address@hidden address@hidden, summary}
address@hidden --new-volume-script
+
+(see --info-script)
+
address@hidden ANCHOR--seek 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --seek
address@hidden -n
+
+Assume that the archive media supports seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. This option is intended for use
+in cases when such recognition fails.
+
address@hidden ANCHOR--newer 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden address@hidden
address@hidden -N
+
+When creating an archive, @command{tar} will only add files that have changed
+since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it
+is taken to be the name of a file whose data modification time specifies
+the date. @xref{after}.
+
address@hidden ANCHOR--newer-mtime 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Like @option{--newer}, but add only files whose
+contents have changed (as opposed to just @option{--newer}, which will
+also back up files for which any status information has
+changed). @xref{after}.
+
address@hidden ANCHOR--no-anchored 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-anchored
+An exclude pattern can match any subsequence of the name's components.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-delay-directory-restore 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-delay-directory-restore
+
+Setting modification times and permissions of extracted
+directories when all files from this directory has been
+extracted. This is the default. @xref{Directory Modification Times and
Permissions}.
+
address@hidden ANCHOR--no-ignore-case 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-ignore-case
+Use case-sensitive matching.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-ignore-command-error 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-ignore-command-error
+Print warnings about subprocesses terminated with a non-zero exit
+code. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--no-overwrite-dir 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-overwrite-dir
+
+Preserve metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--no-quote-chars 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option
+(@pxref{quoting styles}).
+
address@hidden ANCHOR--no-recursion 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-recursion
+
+With this option, @command{tar} will not recurse into directories.
address@hidden
+
address@hidden ANCHOR--no-same-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-same-owner
address@hidden -o
+
+When extracting an archive, do not attempt to preserve the owner
+specified in the @command{tar} archive. This the default behavior
+for ordinary users.
+
address@hidden ANCHOR--no-same-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-same-permissions
+
+When extracting an archive, subtract the user's umask from files from
+the permissions specified in the archive. This is the default behavior
+for ordinary users.
+
address@hidden ANCHOR--no-unquote 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-unquote
+Treat all input file or member names literally, do not interpret
+escape sequences. @xref{input name quoting}.
+
address@hidden ANCHOR--no-wildcards 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-wildcards
+Do not use wildcards.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-wildcards-match-slash 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-wildcards-match-slash
+Wildcards do not match @samp{/}.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--null 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --null
+
+When @command{tar} is using the @option{--files-from} option, this option
+instructs @command{tar} to expect filenames terminated with @option{NUL}, so
address@hidden can correctly work with file names that contain newlines.
address@hidden
+
address@hidden ANCHOR--numeric-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --numeric-owner
+
+This option will notify @command{tar} that it should use numeric user
+and group IDs when creating a @command{tar} file, rather than names.
address@hidden
+
address@hidden -o
+The function of this option depends on the action @command{tar} is
+performing. When extracting files, @option{-o} is a synonym for
address@hidden, i.e. it prevents @command{tar} from
+restoring ownership of files being extracted.
+
+When creating an archive, it is a synonym for
address@hidden This behavior is for compatibility
+with previous versions of @acronym{GNU} @command{tar}, and will be
+removed in the future releases.
+
address@hidden, for more information.
+
address@hidden ANCHOR--occurrence 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+This option can be used in conjunction with one of the subcommands
address@hidden, @option{--diff}, @option{--extract} or
address@hidden when a list of files is given either on the command
+line or via @option{-T} option.
+
+This option instructs @command{tar} to process only the @var{number}th
+occurrence of each named file. @var{Number} defaults to 1, so
+
address@hidden
+tar -x -f archive.tar --occurrence filename
address@hidden smallexample
+
address@hidden
+will extract the first occurrence of the member @file{filename} from
@file{archive.tar}
+and will terminate without scanning to the end of the archive.
+
address@hidden ANCHOR--old-archive 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --old-archive
+Synonym for @option{--format=v7}.
+
address@hidden ANCHOR--one-file-system 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --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 @acronym{GNU} @command{tar} understood
@option{-l} as a
+synonym for @option{--one-file-system}. This has changed in version
+1.15.91. @xref{Changes}, for more information.}.
+
address@hidden ANCHOR--overwrite 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --overwrite
+
+Overwrite existing files and directory metadata when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--overwrite-dir 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --overwrite-dir
+
+Overwrite the metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file. @var{user} is first decoded as a user symbolic name, but if
+this interpretation fails, it has to be a decimal numeric user ID.
address@hidden
+
+This option does not affect extraction from archives.
+
address@hidden ANCHOR--transform 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Transform file or member names using @command{sed} replacement expression
address@hidden For example,
+
address@hidden
+$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .}
address@hidden smallexample
+
address@hidden
+will add to @file{archive} files from the current working directory,
+replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
+discussion, @xref{transform}.
+
+To see transformed member names in verbose listings, use
address@hidden option
+(@pxref{show-transformed-names}).
+
address@hidden ANCHOR--quote-chars 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them (@pxref{quoting styles}).
+
address@hidden ANCHOR--quoting-style 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Set quoting style to use when printing member and file names
+(@pxref{quoting styles}). Valid @var{style} values are:
address@hidden, @code{shell}, @code{shell-always}, @code{c},
address@hidden, @code{locale}, and @code{clocale}. Default quoting
+style is @code{escape}, unless overridden while configuring the
+package.
+
address@hidden ANCHOR--pax-option 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+This option is meaningful only with @acronym{POSIX.1-2001} archives
+(@pxref{posix}). It modifies the way @command{tar} handles the
+extended header keywords. @var{Keyword-list} is a comma-separated
+list of keyword options. @xref{PAX keywords}, for a detailed
+discussion.
+
address@hidden ANCHOR--portability 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --portability
address@hidden --old-archive
+Synonym for @option{--format=v7}.
+
address@hidden ANCHOR--posix 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --posix
+Same as @option{--format=posix}.
+
address@hidden ANCHOR--preserve 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve
+
+Synonymous with specifying both @option{--preserve-permissions} and
address@hidden @xref{Setting Access Permissions}.
+
address@hidden ANCHOR--preserve-order 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve-order
+
+(See @option{--same-order}; @pxref{Reading}.)
+
address@hidden ANCHOR--preserve-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--same-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve-permissions
address@hidden --same-permissions
address@hidden -p
+
+When @command{tar} is extracting an archive, it normally subtracts the
+users' umask from the permissions specified in the archive and uses
+that number as the permissions to create the destination file.
+Specifying this option instructs @command{tar} that it should use the
+permissions directly from the archive. @xref{Setting Access Permissions}.
+
address@hidden ANCHOR--read-full-records 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --read-full-records
address@hidden -B
+
+Specifies that @command{tar} should reblock its input, for reading
+from pipes on systems with buggy implementations. @xref{Reading}.
+
address@hidden ANCHOR--record-size 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Instructs @command{tar} to use @var{size} bytes per record when accessing the
+archive. @xref{Blocking Factor}.
+
address@hidden ANCHOR--recursion 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --recursion
+
+With this option, @command{tar} recurses into directories.
address@hidden
+
address@hidden ANCHOR--recursive-unlink 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --recursive-unlink
+
+Remove existing
+directory hierarchies before extracting directories of the same name
+from the archive. @xref{Recursive Unlink}.
+
address@hidden ANCHOR--remove-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --remove-files
+
+Directs @command{tar} to remove the source file from the file system after
+appending it to an archive. @xref{remove files}.
+
address@hidden ANCHOR--restrict 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --restrict
+
+Disable use of some potentially harmful @command{tar} options.
+Currently this option disables shell invocaton from multi-volume menu
+(@pxref{Using Multiple Tapes}).
+
address@hidden ANCHOR--rmt-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Notifies @command{tar} that it should use @var{cmd} instead of
+the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}).
+
address@hidden ANCHOR--rsh-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Notifies @command{tar} that is should use @var{cmd} to communicate with remote
+devices. @xref{Device}.
+
address@hidden ANCHOR--same-order 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --same-order
address@hidden --preserve-order
address@hidden -s
+
+This option is an optimization for @command{tar} when running on machines with
+small amounts of memory. It informs @command{tar} that the list of file
+arguments has already been sorted to match the order of files in the
+archive. @xref{Reading}.
+
address@hidden ANCHOR--same-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --same-owner
+
+When extracting an archive, @command{tar} will attempt to preserve the owner
+specified in the @command{tar} archive with this option present.
+This is the default behavior for the superuser; this option has an
+effect only for ordinary users. @xref{Attributes}.
+
address@hidden address@hidden, summary}
address@hidden --same-permissions
+
+(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
+
address@hidden ANCHOR--show-defaults 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-defaults
+
+Displays the default options used by @command{tar} and exits
+successfully. This option is intended for use in shell scripts.
+Here is an example of what you can see using this option:
+
address@hidden
+$ tar --show-defaults
+--format=gnu -f- -b20 --quoting-style=escape \
+--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
address@hidden smallexample
+
address@hidden ANCHOR--show-omitted-dirs 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-omitted-dirs
+
+Instructs @command{tar} to mention directories its skipping over when
+operating on a @command{tar} archive. @xref{show-omitted-dirs}.
+
address@hidden ANCHOR--show-transformed-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--show-stored-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-transformed-names
address@hidden --show-stored-names
+
+Display file or member names after applying any transformations
+(@pxref{transform}). In particular, when used in conjunction with one of
+archive creation operations it instructs tar to list the member names
+stored in the archive, as opposed to the actual file
+names. @xref{listing member and file names}.
+
address@hidden ANCHOR--sparse 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --sparse
address@hidden -S
+
+Invokes a @acronym{GNU} extension when adding files to an archive that handles
+sparse files efficiently. @xref{sparse}.
+
address@hidden ANCHOR--sparse-version 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Specified the @dfn{format version} to use when archiving sparse
+files. Implies @option{--sparse}. @xref{sparse}. For the description
+of the supported sparse formats, @xref{Sparse Formats}.
+
address@hidden ANCHOR--starting-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -K @var{name}
+
+This option affects extraction only; @command{tar} will skip extracting
+files in the archive until it finds one that matches @var{name}.
address@hidden
+
address@hidden ANCHOR--strip-components 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Strip given @var{number} of leading components from file names before
address@hidden option was called @option{--strip-path} in
+version 1.14.} For example, if archive @file{archive.tar} contained
address@hidden/some/file/name}, then running
+
address@hidden
+tar --extract --file archive.tar --strip-components=2
address@hidden smallexample
+
address@hidden
+would extract this file to file @file{name}.
+
address@hidden ANCHOR--suffix 1
address@hidden
address@hidden address@hidden, summary}, summary
address@hidden address@hidden
+
+Alters the suffix @command{tar} uses when backing up files from the default
address@hidden @xref{backup}.
+
address@hidden ANCHOR--tape-length 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -L @var{num}
+
+Specifies the length of tapes that @command{tar} is writing as being
address@hidden@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}.
+
address@hidden ANCHOR--test-label 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --test-label
+
+Reads the volume label. If an argument is specified, test whether it
+matches the volume label. @xref{--test-label option}.
+
address@hidden ANCHOR--to-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+During extraction @command{tar} will pipe extracted files to the
+standard input of @var{command}. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--to-stdout 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --to-stdout
address@hidden -O
+
+During extraction, @command{tar} will extract files to stdout rather
+than to the file system. @xref{Writing to Standard Output}.
+
address@hidden ANCHOR--totals 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Displays the total number of bytes transferred when processing an
+archive. If an argument is given, these data are displayed on
+request, when signal @var{signo} is delivered to @command{tar}.
address@hidden
+
address@hidden ANCHOR--touch 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --touch
address@hidden -m
+
+Sets the data modification time of extracted files to the extraction time,
+rather than the data modification time stored in the archive.
address@hidden Modification Times}.
+
address@hidden address@hidden, summary}
address@hidden --uncompress
+
+(See @option{--compress}. @pxref{gzip})
+
address@hidden address@hidden, summary}
address@hidden --ungzip
+
+(See @option{--gzip}. @pxref{gzip})
+
address@hidden ANCHOR--unlink-first 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --unlink-first
address@hidden -U
+
+Directs @command{tar} to remove the corresponding file from the file
+system before extracting it from the archive. @xref{Unlink First}.
+
address@hidden ANCHOR--unquote 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --unquote
+Enable unquoting input file or member names (default). @xref{input
+name quoting}.
+
address@hidden ANCHOR--use-compress-program 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Instructs @command{tar} to access the archive through @var{prog}, which is
+presumed to be a compression program of some sort. @xref{gzip}.
+
address@hidden ANCHOR--utc 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --utc
+
+Display file modification dates in @acronym{UTC}. This option implies
address@hidden
+
address@hidden ANCHOR--verbose 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --verbose
address@hidden -v
+
+Specifies that @command{tar} should be more verbose about the operations its
+performing. This option can be specified multiple times for some
+operations to increase the amount of information displayed.
address@hidden
+
address@hidden ANCHOR--verify 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --verify
address@hidden -W
+
+Verifies that the archive was correctly written when creating an
+archive. @xref{verify}.
+
address@hidden ANCHOR--version 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --version
+
+Print information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden
+
address@hidden ANCHOR--volno-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Used in conjunction with @option{--multi-volume}. @command{tar} will
+keep track of which volume of a multi-volume archive its working in
address@hidden @xref{volno-file}.
+
address@hidden ANCHOR--wildcards 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --wildcards
+Use wildcards when matching member names with patterns.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--wildcards-match-slash 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --wildcards-match-slash
+Wildcards match @samp{/}.
address@hidden pattern-matching}.
address@hidden table
+
address@hidden Short Option Summary
address@hidden Short Options Cross Reference
+
+Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
+
address@hidden @columnfractions 0.20 0.80
address@hidden Short Option @tab Reference
+
address@hidden -A @tab @ref{--concatenate}.
+
address@hidden -B @tab @ref{--read-full-records}.
+
address@hidden -C @tab @ref{--directory}.
+
address@hidden -F @tab @ref{--info-script}.
+
address@hidden -G @tab @ref{--incremental}.
+
address@hidden -K @tab @ref{--starting-file}.
+
address@hidden -L @tab @ref{--tape-length}.
+
address@hidden -M @tab @ref{--multi-volume}.
+
address@hidden -N @tab @ref{--newer}.
+
address@hidden -O @tab @ref{--to-stdout}.
+
address@hidden -P @tab @ref{--absolute-names}.
+
address@hidden -R @tab @ref{--block-number}.
+
address@hidden -S @tab @ref{--sparse}.
+
address@hidden -T @tab @ref{--files-from}.
+
address@hidden -U @tab @ref{--unlink-first}.
+
address@hidden -V @tab @ref{--label}.
+
address@hidden -W @tab @ref{--verify}.
+
address@hidden -X @tab @ref{--exclude-from}.
+
address@hidden -Z @tab @ref{--compress}.
+
address@hidden -b @tab @ref{--blocking-factor}.
+
address@hidden -c @tab @ref{--create}.
+
address@hidden -d @tab @ref{--compare}.
+
address@hidden -f @tab @ref{--file}.
+
address@hidden -g @tab @ref{--listed-incremental}.
+
address@hidden -h @tab @ref{--dereference}.
+
address@hidden -i @tab @ref{--ignore-zeros}.
+
address@hidden -j @tab @ref{--bzip2}.
+
address@hidden -k @tab @ref{--keep-old-files}.
+
address@hidden -l @tab @ref{--check-links}.
+
address@hidden -m @tab @ref{--touch}.
+
address@hidden -o @tab When creating, @ref{--no-same-owner}, when extracting ---
address@hidden
+
+The later usage is deprecated. It is retained for compatibility with
+the earlier versions of @acronym{GNU} @command{tar}. In the future releases
address@hidden will be equivalent to @option{--no-same-owner} only.
+
address@hidden -p @tab @ref{--preserve-permissions}.
+
address@hidden -r @tab @ref{--append}.
+
address@hidden -s @tab @ref{--same-order}.
+
address@hidden -t @tab @ref{--list}.
+
address@hidden -u @tab @ref{--update}.
+
address@hidden -v @tab @ref{--verbose}.
+
address@hidden -w @tab @ref{--interactive}.
+
address@hidden -x @tab @ref{--extract}.
+
address@hidden -z @tab @ref{--gzip}.
+
address@hidden multitable
+
address@hidden help
address@hidden @acronym{GNU} @command{tar} documentation
+
address@hidden Getting program version number
address@hidden version
address@hidden Version of the @command{tar} program
+Being careful, the first thing is really checking that you are using
address@hidden @command{tar}, indeed. The @option{--version} option
+causes @command{tar} to print information about its name, version,
+origin and legal status, all on standard output, and then exit
+successfully. For example, @address@hidden --version}} might print:
+
address@hidden
+tar (GNU tar) 1.15.92
+Copyright (C) 2006 Free Software Foundation, Inc.
+This is free software. You may redistribute copies of it under the terms
+of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by John Gilmore and Jay Fenlason.
address@hidden smallexample
+
address@hidden
+The first occurrence of @samp{tar} in the result above is the program
+name in the package (for example, @command{rmt} is another program),
+while the second occurrence of @samp{tar} is the name of the package
+itself, containing possibly many programs. The package is currently
+named @samp{tar}, after the name of the main program it
address@hidden are plans to merge the @command{cpio} and
address@hidden packages into a single one which would be called
address@hidden So, who knows if, one of this days, the
address@hidden would not output @address@hidden (@acronym{GNU}
+paxutils) 3.2}}}.
+
address@hidden Obtaining help
address@hidden Listing all @command{tar} options
address@hidden address@hidden, introduction}
+Another thing you might want to do is checking the spelling or meaning
+of some particular @command{tar} option, without resorting to this
+manual, for once you have carefully read it. @acronym{GNU} @command{tar}
+has a short help feature, triggerable through the
address@hidden option. By using this option, @command{tar} will
+print a usage message listing all available options on standard
+output, then exit successfully, without doing anything else and
+ignoring all other options. Even if this is only a brief summary, it
+may be several screens long. So, if you are not using some kind of
+scrollable window, you might prefer to use something like:
+
address@hidden
+$ @kbd{tar --help | less}
address@hidden smallexample
+
address@hidden
+presuming, here, that you like using @command{less} for a pager. Other
+popular pagers are @command{more} and @command{pg}. If you know about some
address@hidden which interests you and do not want to read all the
address@hidden output, another common idiom is doing:
+
address@hidden
+tar --help | grep @var{keyword}
address@hidden smallexample
+
address@hidden
+for getting only the pertinent lines. Notice, however, that some
address@hidden options have long description lines and the above
+command will list only the first of them.
+
+The exact look of the option summary displayed by @kbd{tar --help} is
+configurable. @xref{Configuring Help Summary}, for a detailed description.
+
address@hidden 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
address@hidden option 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
+this paragraph, you already have the @command{tar} manual in some
+form. This manual is available in a variety of forms from
address@hidden://www.gnu.org/software/tar/manual}. It may be printed out of
the @acronym{GNU} @command{tar}
+distribution, provided you have @TeX{} already installed somewhere,
+and a laser printer around. Just configure the distribution, execute
+the command @address@hidden dvi}}, then print @file{doc/tar.dvi} the
+usual way (contact your local guru to know how). If @acronym{GNU}
@command{tar}
+has been conveniently installed at your place, this
+manual is also available in interactive, hypertextual form as an Info
+file. Just call @address@hidden tar}} or, if you do not have the
address@hidden program handy, use the Info reader provided within
address@hidden Emacs, calling @samp{tar} from the main Info menu.
+
+There is currently no @code{man} page for @acronym{GNU} @command{tar}.
+If you observe such a @code{man} page on the system you are running,
+either it does not belong to @acronym{GNU} @command{tar}, or it has not
+been produced by @acronym{GNU}. Some package maintainers convert
address@hidden --help} output to a man page, using @command{help2man}. In
+any case, please bear in mind that the authoritative source of
+information about @acronym{GNU} @command{tar} is this Texinfo documentation.
+
address@hidden defaults
address@hidden Obtaining @acronym{GNU} @command{tar} default values
+
address@hidden show-defaults
address@hidden @command{tar} has some predefined defaults that are used when
you do not
+explicitely specify another values. To obtain a list of such
+defaults, use @option{--show-defaults} option. This will output the
+values in the form of @command{tar} command line options:
+
address@hidden
address@hidden
address@hidden --show-defaults}
+--format=gnu -f- -b20 --quoting-style=escape
+--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that this option outputs only one line. The example output above
+has been split to fit page boundaries.
+
address@hidden
+The above output shows that this version of @acronym{GNU} @command{tar}
defaults to
+using @samp{gnu} archive format (@pxref{Formats}), it uses standard
+output as the archive, if no @option{--file} option has been given
+(@pxref{file tutorial}), the default blocking factor is 20
+(@pxref{Blocking Factor}). It also shows the default locations where
address@hidden will look for @command{rmt} and @command{rsh} binaries.
+
address@hidden verbose
address@hidden Checking @command{tar} progress
+
+Typically, @command{tar} performs most operations without reporting any
+information to the user except error messages. When using @command{tar}
+with many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
address@hidden provides several options that make observing @command{tar}
+easier. These options cause @command{tar} to print information as it
+progresses in its job, and you might want to use them just for being
+more careful about what is going on, or merely for entertaining
+yourself. If you have encountered a problem when operating on an
+archive, however, you may need more information than just an error
+message in order to solve the problem. The following options can be
+helpful diagnostic tools.
+
address@hidden Verbose operation
address@hidden verbose
+Normally, the @option{--list} (@option{-t}) command to list an archive
+prints just the file names (one per line) and the other commands are
+silent. When used with most operations, the @option{--verbose}
+(@option{-v}) option causes @command{tar} to print the name of each
+file or archive member as it is processed. This and the other options
+which make @command{tar} print status information can be useful in
+monitoring @command{tar}.
+
+With @option{--create} or @option{--extract}, @option{--verbose} used
+once just prints the names of the files or members as they are processed.
+Using it twice causes @command{tar} to print a longer listing
+(@xref{verbose member listing}, for the description) for each member.
+Since @option{--list} already prints the names of the members,
address@hidden used once with @option{--list} causes @command{tar}
+to print an @samp{ls -l} type listing of the files in the archive.
+The following examples both extract members with long list output:
+
address@hidden
+$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
+$ @kbd{tar xvvf archive.tar}
address@hidden smallexample
+
+Verbose output appears on the standard output except when an archive is
+being written to the standard output, as with @samp{tar --create
+--file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+installer let standard output be the default archive). In that case
address@hidden writes verbose output to the standard error stream.
+
+If @address@hidden is specified, @command{tar} sends
+verbose output to @var{file} rather than to standard output or standard
+error.
+
address@hidden
address@hidden Obtaining total status information
address@hidden totals
+The @option{--totals} option causes @command{tar} to print on the
+standard error the total amount of bytes transferred when processing
+an archive. When creating or appending to an archive, this option
+prints the number of bytes written to the archive and the average
+speed at which they have been written, e.g.:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --totals /home}
+Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
address@hidden group
address@hidden smallexample
+
+When reading an archive, this option displays the number of bytes
+read:
+
address@hidden
address@hidden
+$ @kbd{tar -x -f archive.tar --totals}
+Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
address@hidden group
address@hidden smallexample
+
+Finally, when deleting from an archive, the @option{--totals} option
+displays both numbers plus number of bytes removed from the archive:
+
address@hidden
address@hidden
+$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'}
+Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+Total bytes deleted: 1474048
address@hidden group
address@hidden smallexample
+
+You can also obtain this information on request. When
address@hidden is used with an argument, this argument is
+interpreted as a symbolic name of a signal, upon delivery of which the
+statistics is to be printed:
+
address@hidden @option
address@hidden address@hidden
+Print statistics upon delivery of signal @var{signo}. Valid arguments
+are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and
address@hidden Shortened names without @samp{SIG} prefix are also
+accepted.
address@hidden table
+
+Both forms of @option{--totals} option can be used simultaneously.
+Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to
+extract all members from its default archive and print statistics
+after finishing the extraction, as well as when receiving signal
address@hidden
+
address@hidden information}
address@hidden Progress information
address@hidden 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
address@hidden (@option{-R}), but do want visual confirmation
+that @command{tar} is actually making forward progress. By default it
+prints a message each 10 records read or written. This can be changed
+by giving it a numeric argument after an equal sign:
+
address@hidden
+$ @kbd{tar -c --checkpoint=1000} /var
+tar: Write checkpoint 1000
+tar: Write checkpoint 2000
+tar: Write checkpoint 3000
address@hidden smallexample
+
+This example shows the default checkpoint message used by
address@hidden If you place a dot immediately after the equal
+sign, it will print a @samp{.} at each checkpoint. For example:
+
address@hidden
+$ @kbd{tar -c --checkpoint=.1000} /var
+...
address@hidden smallexample
+
address@hidden show-omitted-dirs
address@hidden
+The @option{--show-omitted-dirs} option, when reading an archive---with
address@hidden or @option{--extract}, for example---causes a message
+to be printed for each directory in the archive which is skipped.
+This happens regardless of the reason for skipping: the directory might
+not have been named on the command line (implicitly or explicitly),
+it might be excluded by the use of the
address@hidden@var{pattern}} option, or some other reason.
+
address@hidden block-number
address@hidden Block number where error occurred
address@hidden
+If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along
with
+every message it would normally produce, the block number within the
+archive where the message was triggered. Also, supplementary messages
+are triggered when reading blocks full of NULs, or when hitting end of
+file on the archive. As of now, if the archive if properly terminated
+with a NUL block, the reading of the file may stop before end of file
+is met, so the position of end of file will not usually show when
address@hidden (@option{-R}) is used. Note that @acronym{GNU} @command{tar}
+drains the archive before exiting when reading the
+archive from a pipe.
+
address@hidden Error message, block number of
+This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
address@hidden (@option{-t}) when listing a file-system backup tape, allowing
you to
+choose among several backup tapes when retrieving a file later, in
+favor of the tape where the file appears earliest (closest to the
+front of the tape). @xref{backup}.
+
address@hidden interactive
address@hidden Asking for Confirmation During Operations
address@hidden Interactive operation
+
+Typically, @command{tar} carries out a command without stopping for
+further instructions. In some situations however, you may want to
+exclude some files and archive members from the operation (for instance
+if disk or storage space is tight). You can do this by excluding
+certain files automatically (@pxref{Choosing}), or by performing
+an operation interactively, using the @option{--interactive} (@option{-w})
option.
address@hidden also accepts @option{--confirmation} for this option.
+
address@hidden interactive
+When the @option{--interactive} (@option{-w}) option is specified, before
+reading, writing, or deleting files, @command{tar} first prints a message
+for each such file, telling what operation it intends to take, then asks
+for confirmation on the terminal. The actions which require
+confirmation include adding a file to the archive, extracting a file
+from the archive, deleting a file from the archive, and deleting a file
+from disk. To confirm the action, you must type a line of input
+beginning with @samp{y}. If your input line begins with anything other
+than @samp{y}, @command{tar} skips that file.
+
+If @command{tar} is reading the archive from the standard input,
address@hidden opens the file @file{/dev/tty} to support the interactive
+communications.
+
+Verbose output is normally sent to standard output, separate from
+other error messages. However, if the archive is produced directly
+on standard output, then verbose output is mixed with errors on
address@hidden Producing the archive on standard output may be used
+as a way to avoid using disk space, when the archive is soon to be
+consumed by another process reading it, say. Some people felt the need
+of producing an archive on stdout, still willing to segregate between
+verbose output and error output. A possible approach would be using a
+named pipe to receive the archive, and having the consumer process to
+read from that named pipe. This has the advantage of letting standard
+output free to receive verbose output, all separate from errors.
+
address@hidden operations
address@hidden @acronym{GNU} @command{tar} Operations
+
address@hidden
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
address@hidden menu
+
address@hidden Basic tar
address@hidden Basic @acronym{GNU} @command{tar} Operations
+
+The basic @command{tar} operations, @option{--create} (@option{-c}),
address@hidden (@option{-t}) and @option{--extract} (@option{--get},
address@hidden), are currently presented and described in the tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+
address@hidden @option
address@hidden address@hidden, complementary notes}
address@hidden --create
address@hidden -c
+
+Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use @option{--append}
+(@option{-r}) for adding all members. Some applications would not
+welcome making an exception in the way of adding the first archive
+member. On the other hand, many people reported that it is
+dangerously too easy for @command{tar} to destroy a magnetic tape with
+an empty address@hidden is well described in @cite{Unix-haters
+Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG
+Books, ISBN 1-56884-203-1.}. The two most common errors are:
+
address@hidden
address@hidden
+Mistakingly using @code{create} instead of @code{extract}, when the
+intent was to extract the full contents of an archive. This error
+is likely: keys @kbd{c} and @kbd{x} are right next to each other on
+the QWERTY keyboard. Instead of being unpacked, the archive then
+gets wholly destroyed. When users speak about @dfn{exploding} an
+archive, they usually mean something else :-).
+
address@hidden
+Forgetting the argument to @code{file}, when the intent was to create
+an archive with a single file in it. This error is likely because a
+tired user can easily add the @kbd{f} key to the cluster of option
+letters, by the mere force of habit, without realizing the full
+consequence of doing so. The usual consequence is that the single
+file, which was meant to be saved, is rather destroyed.
address@hidden enumerate
+
+So, recognizing the likelihood and the catastrophical nature of these
+errors, @acronym{GNU} @command{tar} now takes some distance from elegance, and
+cowardly refuses to create an archive when @option{--create} option is
+given, there are no arguments besides options, and
address@hidden (@option{-T}) option is @emph{not} used. To get
+around the cautiousness of @acronym{GNU} @command{tar} and nevertheless create
an
+archive with nothing in it, one may still use, as the value for the
address@hidden option, a file with no names in it, as shown in
+the following commands:
+
address@hidden
address@hidden --create --file=empty-archive.tar --files-from=/dev/null}
address@hidden cfT empty-archive.tar /dev/null}
address@hidden smallexample
+
address@hidden address@hidden, complementary notes}
address@hidden --extract
address@hidden --get
address@hidden -x
+
+A socket is stored, within a @acronym{GNU} @command{tar} archive, as a pipe.
+
address@hidden @option{--list} (@option{-t})
+
address@hidden @command{tar} now shows dates as @samp{1996-08-30},
+while it used to show them as @samp{Aug 30 1996}. Preferably,
+people should get used to ISO 8601 dates. Local American dates should
+be made available again with full date localization support, once
+ready. In the meantime, programs not being localizable for dates
+should prefer international dates, that's really the way to go.
+
+Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you
+are curious, it contains a detailed explanation of the ISO 8601 standard.
+
address@hidden table
+
address@hidden Advanced tar
address@hidden Advanced @acronym{GNU} @command{tar} Operations
+
+Now that you have learned the basics of using @acronym{GNU} @command{tar}, you
may want
+to learn about further ways in which @command{tar} can help you.
+
+This chapter presents five, more advanced operations which you probably
+won't use on a daily basis, but which serve more specialized functions.
+We also explain the different styles of options and why you might want
+to use one or another, or a combination of them in your @command{tar}
+commands. Additionally, this chapter includes options which allow you to
+define the output from @command{tar} more carefully, and provide help and
+error correction in special circumstances.
+
address@hidden
address@hidden
+
+
address@hidden
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
address@hidden menu
+
address@hidden Operations
address@hidden The Five Advanced @command{tar} Operations
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+In the last chapter, you learned about the first three operations to
address@hidden This chapter presents the remaining five operations to
address@hidden: @option{--append}, @option{--update}, @option{--concatenate},
address@hidden, and @option{--compare}.
+
+You are not likely to use these operations as frequently as those
+covered in the last chapter; however, since they perform specialized
+functions, they are quite useful when you do need to use them. We
+will give examples using the same directory and files that you created
+in the last chapter. As you may recall, the directory is called
address@hidden, the files are @samp{jazz}, @samp{blues}, @samp{folk},
address@hidden, and the two archive files you created are
address@hidden and @samp{music.tar}.
+
+We will also use the archive files @samp{afiles.tar} and
address@hidden The archive @samp{afiles.tar} contains the members @samp{apple},
address@hidden, and @samp{aspic}; @samp{bfiles.tar} contains the members
address@hidden/birds}, @samp{baboon}, and @samp{./box}.
+
+Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the @file{practice} directory that
+you created in the previous chapter; see @ref{prepare for examples}.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+
+The five operations that we will cover in this chapter are:
+
address@hidden @option
address@hidden --append
address@hidden -r
+Add new entries to an archive that already exists.
address@hidden --update
address@hidden -r
+Add more recent copies of archive members to the end of an archive, if
+they exist.
address@hidden --concatenate
address@hidden --catenate
address@hidden -A
+Add one or more pre-existing archives to the end of another archive.
address@hidden --delete
+Delete items from an archive (does not work on tapes).
address@hidden --compare
address@hidden --diff
address@hidden -d
+Compare archive members to their counterparts in the file system.
address@hidden table
+
address@hidden append
address@hidden How to Add Files to Existing Archives: @option{--append}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden append
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use @option{--append} (@option{-r}).
+The archive must already exist in order to use @option{--append}. (A
+related operation is the @option{--update} operation; you can use this
+to add newer versions of archive members to an existing archive. To learn how
to
+do this with @option{--update}, @pxref{update}.)
+
+If you use @option{--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 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 @option{--list} (@option{-t}), you will see all
+of those members listed, with their data modification times, owners, etc.
+
+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
+other members would end up in the working directory. This is because
address@hidden 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 address@hidden you give it
address@hidden option, or the disk copy is newer than the
+the one in the archive and you invoke @command{tar} with
address@hidden 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
address@hidden contained three copies of file @file{myfile}, then
+the command
+
address@hidden
+tar --extract --file archive.tar --occurrence=2 myfile
address@hidden smallexample
+
address@hidden
+would extract only the second copy. @xref{Option
+Summary,---occurrence}, for the description of @option{--occurrence}
+option.
+
address@hidden
address@hidden
+
+
address@hidden Members, replacing with other members
address@hidden Replacing members with other members
+If you want to replace an archive member, use @option{--delete} to
+delete the member you want to remove from the archive, , and then use
address@hidden to add the member you want to be in the archive. Note
+that you can not change the order of the archive; the most recently
+added member will still appear last. In this sense, you cannot truly
+``replace'' one member with another. (Replacing one member with another
+will not work on certain types of media, such as tapes; see @ref{delete}
+and @ref{Media}, for more information.)
+
address@hidden
+* appending files:: Appending Files to an Archive
+* multiple::
address@hidden menu
+
address@hidden appending files
address@hidden Appending Files to an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Adding files to an Archive
address@hidden Appending files to an Archive
address@hidden Archives, Appending files to
+
+The simplest way to add a file to an already existing archive is the
address@hidden (@option{-r}) operation, which writes specified
+files into the archive whether or not they are already among the
+archived files.
+
+When you use @option{--append}, you @emph{must} specify file name
+arguments, as there is no default. If you specify a file that already
+exists in the archive, another copy of the file will be added to the
+end of the archive. As with other operations, the member names of the
+newly added files will be exactly the same as their names given on the
+command line. The @option{--verbose} (@option{-v}) option will print
+out the names of the files as they are written into the archive.
+
address@hidden cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid @command{tar} archive, or else the results of using this
+operation will be unpredictable. @xref{Media}.
+
+To demonstrate using @option{--append} to add a file to an archive,
+create a file called @file{rock} in the @file{practice} directory.
+Make sure you are in the @file{practice} directory. Then, run the
+following @command{tar} command to add @file{rock} to
address@hidden:
+
address@hidden
+$ @kbd{tar --append --file=collection.tar rock}
address@hidden smallexample
+
address@hidden
+If you now use the @option{--list} (@option{-t}) operation, you will see that
address@hidden has been added to the archive:
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
address@hidden smallexample
+
address@hidden multiple
address@hidden Multiple Members with the Same Name
+
+You can use @option{--append} (@option{-r}) to add copies of files
+which have been updated since the archive was created. (However, we
+do not recommend doing this since there is another @command{tar}
+option called @option{--update}; @xref{update}, for more information.
+We describe this use of @option{--append} here for the sake of
+completeness.) When you extract the archive, the older version will
+be effectively lost. This works because files are extracted from an
+archive in the order in which they were archived. Thus, when the
+archive is extracted, a file archived later in time will replace a
+file of the same name which was archived earlier, even though the
+older version of the file will remain in the archive unless you delete
+all versions of the file.
+
+Supposing you change the file @file{blues} and then append the changed
+version to @file{collection.tar}. As you saw above, the original
address@hidden is in the archive @file{collection.tar}. If you change the
+file and append the new version of the file to the archive, there will
+be two copies in the archive. When you extract the archive, the older
+version of the file will be extracted first, and then replaced by the
+newer version when it is extracted.
+
+You can append the new, changed copy of the file @file{blues} to the
+archive in this way:
+
address@hidden
+$ @kbd{tar --append --verbose --file=collection.tar blues}
+blues
address@hidden smallexample
+
address@hidden
+Because you specified the @option{--verbose} option, @command{tar} has
+printed the name of the file being appended as it was acted on. Now
+list the contents of the archive:
+
address@hidden
+$ @kbd{tar --list --verbose --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
+-rw-r--r-- me user 58 1996-10-24 18:30 blues
address@hidden smallexample
+
address@hidden
+The newest version of @file{blues} is now at the end of the archive
+(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.
+
+If you wish to extract the first occurrence of the file @file{blues}
+from the archive, use @option{--occurrence} option, as shown in
+the following example:
+
address@hidden
+$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
address@hidden smallexample
+
address@hidden, for more information on @option{--extract} and
address@hidden Summary, --occurrence}, for the description of
address@hidden option.
+
address@hidden update
address@hidden Updating an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Updating an archive
+
address@hidden update
+In the previous section, you learned how to use @option{--append} to
+add a file to an existing archive. A related operation is
address@hidden (@option{-u}). The @option{--update} operation
+updates a @command{tar} archive by comparing the date of the specified
+archive members against the date of the file with the same name. If
+the file has been modified more recently than the archive member, then
+the newer version of the file is added to the archive (as with
address@hidden).
+
+Unfortunately, you cannot use @option{--update} with magnetic tape drives.
+The operation will fail.
+
address@hidden
address@hidden
+
+
+Both @option{--update} and @option{--append} work by adding to the end
+of the archive. When you extract a file from the archive, only the
+version stored last will wind up in the file system, unless you use
+the @option{--backup} option. @xref{multiple}, for a detailed discussion.
+
address@hidden
+* how to update::
address@hidden menu
+
address@hidden how to update
address@hidden How to Update an Archive Using @option{--update}
+
+You must use file name arguments with the @option{--update}
+(@option{-u}) operation. If you don't specify any files,
address@hidden won't act on any files and won't tell you that it didn't
+do anything (which may end up confusing you).
+
address@hidden note: the above parenthetical added because in fact, this
address@hidden behavior just confused the author. :-)
+
+To see the @option{--update} option at work, create a new file,
address@hidden, in your practice directory, and some extra text to the
+file @file{blues}, using any text editor. Then invoke @command{tar} with
+the @samp{update} operation and the @option{--verbose} (@option{-v})
+option specified, using the names of all the files in the practice
+directory as file name arguments:
+
address@hidden
+$ @kbd{tar --update -v -f collection.tar blues folk rock classical}
+blues
+classical
+$
address@hidden smallexample
+
address@hidden
+Because we have specified verbose mode, @command{tar} prints out the names
+of the files it is working on, which in this case are the names of the
+files that needed to be updated. If you run @samp{tar --list} and look
+at the archive, you will see @file{blues} and @file{classical} at its
+end. There will be a total of two versions of the member @samp{blues};
+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
+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.
+
address@hidden (@option{-u}) is not suitable for performing backups for two
+reasons: it does not change directory content entries, and it
+lengthens the archive every time it is used. The @acronym{GNU} @command{tar}
+options intended specifically for backups are more
+efficient. If you need to run backups, please consult @ref{Backups}.
+
address@hidden concatenate
address@hidden Combining Archives with @option{--concatenate}
+
address@hidden Adding archives to an archive
address@hidden Concatenating Archives
address@hidden concatenate
address@hidden catenate
address@hidden @cindex @option{-A} described
+Sometimes it may be convenient to add a second archive onto the end of
+an archive rather than adding individual files to the archive. To add
+one or more archives to the end of another archive, you should use the
address@hidden (@option{--catenate}, @option{-A}) operation.
+
+To use @option{--concatenate}, give the first archive with
address@hidden 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.
address@hidden 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
address@hidden, @command{tar} will use the value of the environment
+variable @env{TAPE}, or, if this has not been set, the default archive name.
+
address@hidden
address@hidden
+
+
+To demonstrate how @option{--concatenate} works, create two small archives
+called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
+files from @file{practice}:
+
address@hidden
+$ @kbd{tar -cvf bluesrock.tar blues rock}
+blues
+rock
+$ @kbd{tar -cvf folkjazz.tar folk jazz}
+folk
+jazz
address@hidden smallexample
+
address@hidden
+If you like, You can run @samp{tar --list} to make sure the archives
+contain what they are supposed to:
+
address@hidden
+$ @kbd{tar -tvf bluesrock.tar}
+-rw-r--r-- melissa user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa user 33 1997-01-20 15:34 rock
+$ @kbd{tar -tvf jazzfolk.tar}
+-rw-r--r-- melissa user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
address@hidden smallexample
+
+We can concatenate these two archives with @command{tar}:
+
address@hidden
+$ @kbd{cd ..}
+$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
address@hidden smallexample
+
+If you now list the contents of the @file{bluesrock.tar}, you will see
+that now it also contains the archive members of @file{jazzfolk.tar}:
+
address@hidden
+$ @kbd{tar --list --file=bluesrock.tar}
+blues
+rock
+folk
+jazz
address@hidden smallexample
+
+When you use @option{--concatenate}, the source and target archives must
+already exist and must have been created using compatible format
+parameters. Notice, that @command{tar} does not check whether the
+archives it concatenates have compatible formats, it does not
+even check if the files are really tar archives.
+
+Like @option{--append} (@option{-r}), this operation cannot be performed on
some
+tape drives, due to deficiencies in the formats those tape drives use.
+
address@hidden @code{concatenate} vs @command{cat}
address@hidden @command{cat} vs @code{concatenate}
+It may seem more intuitive to you to want or try to use @command{cat} to
+concatenate two archives instead of using the @option{--concatenate}
+operation; after all, @command{cat} is the utility for combining files.
+
+However, @command{tar} archives incorporate an end-of-file marker which
+must be removed if the concatenated archives are to be read properly as
+one archive. @option{--concatenate} removes the end-of-archive marker
+from the target archive before each new archive is appended. If you use
address@hidden to combine the archives, the result will not be a valid
address@hidden format archive. If you need to retrieve files from an
+archive that was added to using the @command{cat} utility, use the
address@hidden (@option{-i}) option. @xref{Ignore Zeros}, for further
+information on dealing with archives improperly combined using the
address@hidden shell utility.
+
address@hidden delete
address@hidden Removing Archive Members Using @option{--delete}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Deleting files from an archive
address@hidden Removing files from an archive
+
address@hidden delete
+You can remove members from an archive by using the @option{--delete}
+option. Specify the name of the archive with @option{--file}
+(@option{-f}) and then specify the names of the members to be deleted;
+if you list no member names, nothing will be deleted. The
address@hidden option will cause @command{tar} to print the names
+of the members as they are deleted. As with @option{--extract}, you
+must give the exact member names when using @samp{tar --delete}.
address@hidden will remove all versions of the named file from the
+archive. The @option{--delete} operation can run very slowly.
+
+Unlike other operations, @option{--delete} has no short form.
+
address@hidden Tapes, using @option{--delete} and
address@hidden Deleting from tape archives
+This operation will rewrite the archive. You can only use
address@hidden on an archive if the archive device allows you to
+write to any point on the media, such as a disk; because of this, it
+does not work on magnetic tapes. Do not try to delete an archive member
+from a magnetic tape; the action will not succeed, and you will be
+likely to scramble the archive and damage your tape. There is no safe
+way (except by completely re-writing the archive) to delete files from
+most kinds of magnetic tape. @xref{Media}.
+
+To delete all versions of the file @file{blues} from the archive
address@hidden in the @file{practice} directory, make sure you
+are in that directory, and then,
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
+blues
+folk
+jazz
+rock
+$ @kbd{tar --delete --file=collection.tar blues}
+$ @kbd{tar --list --file=collection.tar}
+folk
+jazz
+rock
+$
address@hidden smallexample
+
address@hidden
address@hidden
+
+
+The @option{--delete} option has been reported to work properly when
address@hidden acts as a filter from @code{stdin} to @code{stdout}.
+
address@hidden compare
address@hidden Comparing Archive Members with the File System
address@hidden Verifying the currency of an archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden compare
+The @option{--compare} (@option{-d}), or @option{--diff} operation compares
+specified archive members against files with the same names, and then
+reports differences in file size, mode, owner, modification date and
+contents. You should @emph{only} specify archive member names, not file
+names. If you do not name any members, then @command{tar} will compare the
+entire archive. If a file is represented in the archive but does not
+exist in the file system, @command{tar} reports a difference.
+
+You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
address@hidden ignores files in the file system that do not have
+corresponding members in the archive.
+
+The following example compares the archive members @file{rock},
address@hidden and @file{funk} in the archive @file{bluesrock.tar} with
+files of the same name in the file system. (Note that there is no file,
address@hidden; @command{tar} will report an error message.)
+
address@hidden
+$ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
+rock
+blues
+tar: funk not found in archive
address@hidden smallexample
+
+The spirit behind the @option{--compare} (@option{--diff},
address@hidden) 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}.
+
address@hidden create options
address@hidden Options Used by @option{--create}
+
address@hidden address@hidden, additional options}
+The previous chapter described the basics of how to use
address@hidden (@option{-c}) to create an archive from a set of files.
address@hidden This section described advanced options to be used with
address@hidden
+
address@hidden
+* override:: Overriding File Metadata.
+* Ignore Failed Read::
address@hidden menu
+
address@hidden override
address@hidden Overriding File Metadata
+
+As described above, a @command{tar} archive keeps, for each member it contains,
+its @dfn{metadata}, such as modification time, mode and ownership of
+the file. @acronym{GNU} @command{tar} allows to replace these data with other
values
+when adding files to the archive. The options described in this
+section affect creation of archives of any type. For POSIX archives,
+see also @ref{PAX keywords}, for additional ways of controlling
+metadata, stored in the archive.
+
address@hidden @option
address@hidden mode
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use
address@hidden for the archive members, rather than the permissions
+from the files. @var{permissions} can be specified either as an octal
+number or as symbolic permissions, like with
address@hidden (@xref{File permissions, Permissions, File
+permissions, fileutils, @acronym{GNU} file utilities}. This reference
+also has useful information for those not being overly familiar with
+the UNIX permission system). Using latter syntax allows for
+more flexibility. For example, the value @samp{a+rw} adds read and write
+permissions for everybody, while retaining executable bits on directories
+or on any other file already marked as executable:
+
address@hidden
+$ @kbd{tar -c -f archive.tar --mode='a+rw' .}
address@hidden smallexample
+
address@hidden address@hidden
address@hidden mtime
+
+When adding files to an archive, @command{tar} will use @var{date} as
+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
+with @samp{/} or @samp{.}. In the latter case, the modification time
+of that file will be used.
+
+The following example will set the modification date to 00:00:00 UTC,
+January 1, 1970:
+
address@hidden
+$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .}
address@hidden smallexample
+
address@hidden
+When used with @option{--verbose} (@pxref{verbose tutorial}) @acronym{GNU}
@command{tar}
+will try to convert the specified date back to its textual
+representation and compare it with the one given with
address@hidden options. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date.
+
+For example:
+
address@hidden
+$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
+tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+13:06:29.152478
address@hidden
address@hidden smallexample
+
address@hidden address@hidden
address@hidden owner
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file. The argument @var{user} can be either an existing user symbolic
+name, or a decimal numeric user ID.
+
+There is no value indicating a missing number, and @samp{0} usually means
address@hidden Some people like to force @samp{0} as the value to offer in
+their distributions for the owner of files, because the @code{root} user is
+anonymous anyway, so that might as well be the owner of anonymous
+archives. For example:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --owner=0 .}
+# @r{Or:}
+$ @kbd{tar -c -f archive.tar --owner=root .}
address@hidden group
address@hidden smallexample
+
address@hidden address@hidden
address@hidden group
+
+Files added to the @command{tar} archive will have a group id of @var{group},
+rather than the group from the source file. The argument @var{group}
+can be either an existing group symbolic name, or a decimal numeric group ID.
address@hidden table
+
address@hidden Ignore Failed Read
address@hidden Ignore Fail Read
+
address@hidden @option
address@hidden --ignore-failed-read
address@hidden ignore-failed-read
+Do not exit with nonzero on unreadable files or directories.
address@hidden table
+
address@hidden extract options
address@hidden Options Used by @option{--extract}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden address@hidden, additional options}
+The previous chapter showed how to use @option{--extract} to extract
+an archive into the file system. Various options cause @command{tar} to
+extract more information than just file contents, such as the owner,
+the permissions, the modification date, and so forth. This section
+presents options to be used with @option{--extract} when certain special
+considerations arise. You may review the information presented in
address@hidden for more basic information about the
address@hidden operation.
+
address@hidden
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
address@hidden menu
+
address@hidden Reading
address@hidden Options to Help Read Archives
address@hidden Options when reading archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Reading incomplete records
address@hidden Records, incomplete
address@hidden read-full-records
+Normally, @command{tar} will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
address@hidden will report an error. However, some devices do not always
+return full records, or do not require the last record of an archive to
+be padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the @option{--read-full-records}
(@option{-B}) option
+in conjunction with the @option{--extract} or @option{--list} operations.
address@hidden
+
+The @option{--read-full-records} (@option{-B}) option is turned on by default
when
address@hidden reads an archive from standard input, or from a remote
+machine. This is because on BSD Unix systems, attempting to read a
+pipe returns however much happens to be in the pipe, even if it is
+less than was requested. If this option were not enabled, @command{tar}
+would fail as soon as it read an incomplete record from the pipe.
+
+If you're not sure of the blocking factor of an archive, you can
+read the archive by specifying @option{--read-full-records} (@option{-B}) and
address@hidden@var{512-size}} (@option{-b
address@hidden), using a blocking factor larger than what the archive
+uses. This lets you avoid having to determine the blocking factor
+of an archive. @xref{Blocking Factor}.
+
address@hidden
+* read full records::
+* Ignore Zeros::
address@hidden menu
+
address@hidden read full records
address@hidden Reading Full Records
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden read-full-records
address@hidden --read-full-records
address@hidden -B
+Use in conjunction with @option{--extract} (@option{--get},
address@hidden) to read an archive which contains incomplete records, or
+one which has a blocking factor less than the one specified.
address@hidden table
+
address@hidden Ignore Zeros
address@hidden Ignoring Blocks of Zeros
+
address@hidden End-of-archive blocks, ignoring
address@hidden Ignoring end-of-archive blocks
address@hidden ignore-zeros
+Normally, @command{tar} stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
address@hidden (@option{-i}) allows @command{tar} to
+completely read an archive which contains a block of zeros before the
+end (i.e., a damaged archive, or one that was created by concatenating
+several archives together).
+
+The @option{--ignore-zeros} (@option{-i}) option is turned off by default
because many
+versions of @command{tar} write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read. @acronym{GNU}
@command{tar}
+does not write after the end of an archive, but seeks to
+maintain compatiblity among archiving utilities.
+
address@hidden @option
address@hidden --ignore-zeros
address@hidden -i
+To ignore blocks of zeros (i.e., end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
address@hidden or @option{--list}.
address@hidden table
+
address@hidden Writing
address@hidden Changing How @command{tar} Writes Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
address@hidden menu
+
address@hidden Dealing with Old Files
address@hidden Options Controlling the Overwriting of Existing Files
+
address@hidden address@hidden, introduced}
+When extracting files, if @command{tar} discovers that the extracted
+file already exists, it normally replaces the file by removing it before
+extracting it, to prevent confusion in the presence of hard or symbolic
+links. (If the existing file is a symbolic link, it is removed, not
+followed.) However, if a directory cannot be removed because it is
+nonempty, @command{tar} normally overwrites its metadata (ownership,
+permission, etc.). The @option{--overwrite-dir} option enables this
+default behavior. To be more cautious and preserve the metadata of
+such a directory, use the @option{--no-overwrite-dir} option.
+
address@hidden Overwriting old files, prevention
address@hidden address@hidden, introduced}
+To be even more cautious and prevent existing files from being replaced, use
+the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar}
to refuse
+to replace or update a file that already exists, i.e., a file with the
+same name as an archive member prevents extraction of that archive
+member. Instead, it reports an error.
+
address@hidden address@hidden, introduced}
+To be more aggressive about altering existing files, use the
address@hidden option. It causes @command{tar} to overwrite
+existing files and to follow existing symbolic links when extracting.
+
address@hidden Protecting old files
+Some people argue that @acronym{GNU} @command{tar} should not hesitate
+to overwrite files with other files when extracting. When extracting
+a @command{tar} archive, they expect to see a faithful copy of the
+state of the file system when the archive was created. It is debatable
+that this would always be a proper behavior. For example, suppose one
+has an archive in which @file{usr/local} is a link to
address@hidden/local2}. Since then, maybe the site removed the link and
+renamed the whole hierarchy from @file{/usr/local2} to
address@hidden/usr/local}. Such things happen all the time. I guess it would
+not be welcome at all that @acronym{GNU} @command{tar} removes the
+whole hierarchy just to make room for the link to be reinstated
+(unless it @emph{also} simultaneously restores the full
address@hidden/usr/local2}, of course!) @acronym{GNU} @command{tar} is indeed
+able to remove a whole hierarchy to reestablish a symbolic link, for
+example, but @emph{only if} @option{--recursive-unlink} is specified
+to allow this behavior. In any case, single files are silently
+removed.
+
address@hidden address@hidden, introduced}
+Finally, the @option{--unlink-first} (@option{-U}) option can improve
performance in
+some cases by causing @command{tar} to remove files unconditionally
+before extracting them.
+
address@hidden Overwrite Old Files
address@hidden Overwrite Old Files
+
address@hidden @option
address@hidden overwrite
address@hidden --overwrite
+Overwrite existing files and directory metadata when extracting files
+from an archive.
+
+This causes @command{tar} to write extracted files into the file system without
+regard to the files already on the system; i.e., files with the same
+names as archive members are overwritten when the archive is extracted.
+It also causes @command{tar} to extract the ownership, permissions,
+and time stamps onto any preexisting files or directories.
+If the name of a corresponding file name is a symbolic link, the file
+pointed to by the symbolic link will be overwritten instead of the
+symbolic link itself (if this is possible). Moreover, special devices,
+empty directories and even symbolic links are automatically removed if
+they are in the way of extraction.
+
+Be careful when using the @option{--overwrite} option, particularly when
+combined with the @option{--absolute-names} (@option{-P}) option, as this
combination
+can change the contents, ownership or permissions of any file on your
+system. Also, many systems do not take kindly to overwriting files that
+are currently being executed.
+
address@hidden overwrite-dir
address@hidden --overwrite-dir
+Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
address@hidden table
+
address@hidden Keep Old Files
address@hidden Keep Old Files
+
address@hidden @option
address@hidden keep-old-files
address@hidden --keep-old-files
address@hidden -k
+Do not replace existing files from archive. The
address@hidden (@option{-k}) option prevents @command{tar}
+from replacing existing files with files with the same name from the
+archive. The @option{--keep-old-files} option is meaningless with
address@hidden (@option{-t}). Prevents @command{tar} from replacing
+files in the file system during extraction.
address@hidden table
+
address@hidden Keep Newer Files
address@hidden Keep Newer Files
+
address@hidden @option
address@hidden keep-newer-files
address@hidden --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @option{--list} (@option{-t}).
address@hidden table
+
address@hidden Unlink First
address@hidden Unlink First
+
address@hidden @option
address@hidden unlink-first
address@hidden --unlink-first
address@hidden -U
+Remove files before extracting over them.
+This can make @command{tar} run a bit faster if you know in advance
+that the extracted files all need to be removed. Normally this option
+slows @command{tar} down slightly, so it is disabled by default.
address@hidden table
+
address@hidden Recursive Unlink
address@hidden Recursive Unlink
+
address@hidden @option
address@hidden recursive-unlink
address@hidden --recursive-unlink
+When this option is specified, try removing files and directory hierarchies
+before extracting over them. @emph{This is a dangerous option!}
address@hidden table
+
+If you specify the @option{--recursive-unlink} option,
address@hidden removes @emph{anything} that keeps you from extracting a file
+as far as current permissions will allow it. This could include removal
+of the contents of a full directory hierarchy.
+
address@hidden Data Modification Times
address@hidden Setting Data Modification Times
+
address@hidden Data modification times of extracted files
address@hidden Modification times of extracted files
+Normally, @command{tar} sets the data modification times of extracted
+files to the corresponding times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the data modification times of extracted files to the time when
+the files were extracted, use the @option{--touch} (@option{-m}) option in
+conjunction with @option{--extract} (@option{--get}, @option{-x}).
+
address@hidden @option
address@hidden touch
address@hidden --touch
address@hidden -m
+Sets the data modification time of extracted archive members to the time
+they were extracted, not the time recorded for them in the archive.
+Use in conjunction with @option{--extract} (@option{--get}, @option{-x}).
address@hidden table
+
address@hidden Setting Access Permissions
address@hidden Setting Access Permissions
+
address@hidden Permissions of extracted files
address@hidden Modes of extracted files
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use @option{--same-permissions}
+in conjunction with the @option{--extract} (@option{--get},
address@hidden) operation.
+
address@hidden @option
address@hidden preserve-permissions
address@hidden same-permissions
address@hidden --preserve-permissions
address@hidden --same-permissions
address@hidden @itemx --ignore-umask
address@hidden -p
+Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
address@hidden (@option{--get}, @option{-x}).
address@hidden table
+
address@hidden Directory Modification Times and Permissions
address@hidden Directory Modification Times and Permissions
+
+After sucessfully extracting a file member, @acronym{GNU} @command{tar}
normally
+restores its permissions and modification times, as described in the
+previous sections. This cannot be done for directories, because
+after extracting a directory @command{tar} will almost certainly
+extract files into that directory and this will cause the directory
+modification time to be updated. Moreover, restoring that directory
+permissions may not permit file creation within it. Thus, restoring
+directory permissions and modification times must be delayed at least
+until all files have been extracted into that directory. @acronym{GNU}
@command{tar}
+restores directories using the following approach.
+
+The extracted directories are created with the mode specified in the
+archive, as modified by the umask of the user, which gives sufficient
+permissions to allow file creation. The meta-information about the
+directory is recorded in the temporary list of directories. When
+preparing to extract next archive member, @acronym{GNU} @command{tar} checks
if the
+directory prefix of this file contains the remembered directory. If
+it does not, the program assumes that all files have been extracted
+into that directory, restores its modification time and permissions
+and removes its entry from the internal list. This approach allows
+to correctly restore directory meta-information in the majority of
+cases, while keeping memory requirements sufficiently small. It is
+based on the fact, that most @command{tar} archives use the predefined
+order of members: first the directory, then all the files and
+subdirectories in that directory.
+
+However, this is not always true. The most important exception are
+incremental archives (@pxref{Incremental Dumps}). The member order in
+an incremental archive is reversed: first all directory members are
+stored, followed by other (non-directory) members. So, when extracting
+from incremental archives, @acronym{GNU} @command{tar} alters the above
procedure. It
+remebers all restored directories, and restores their meta-data
+only after the entire archive has been processed. Notice, that you do
+not need to specity any special options for that, as @acronym{GNU}
@command{tar}
+automatically detects archives in incremental format.
+
+There may be cases, when such processing is required for normal archives
+too. Consider the following example:
+
address@hidden
address@hidden
+$ @kbd{tar --no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2}
+foo/
+foo/file1
+bar/
+bar/file
+foo/file2
address@hidden group
address@hidden smallexample
+
+During the normal operation, after encountering @file{bar}
address@hidden @command{tar} will assume that all files from the directory
@file{foo}
+were already extracted and will therefore restore its timestamp and
+permission bits. However, after extracting @file{foo/file2} the
+directory timestamp will be offset again.
+
+To correctly restore directory meta-information in such cases, use
address@hidden command line option:
+
address@hidden @option
address@hidden delay-directory-restore
address@hidden --delay-directory-restore
+Delays restoring of the modification times and permissions of extracted
+directories until the end of extraction. This way, correct
+meta-information is restored even if the archive has unusual member
+ordering.
+
address@hidden no-delay-directory-restore
address@hidden --no-delay-directory-restore
+Cancel the effect of the previous @option{--delay-directory-restore}.
+Use this option if you have used @option{--delay-directory-restore} in
address@hidden variable (@pxref{TAR_OPTIONS}) and wish to
+temporarily disable it.
address@hidden table
+
address@hidden Writing to Standard Output
address@hidden Writing to Standard Output
+
address@hidden Writing extracted files to standard output
address@hidden Standard output, writing extracted files to
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @option{--to-stdout} (@option{-O})
in
+conjunction with @option{--extract} (@option{--get}, @option{-x}). This
option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
address@hidden @option
address@hidden to-stdout
address@hidden --to-stdout
address@hidden -O
+Writes files to the standard output. Use only in conjunction with
address@hidden (@option{--get}, @option{-x}). When this option is
+used, instead of creating the files specified, @command{tar} writes
+the contents of the files extracted to its standard output. This may
+be useful if you are only extracting the files in order to send them
+through a pipe. This option is meaningless with @option{--list}
+(@option{-t}).
address@hidden table
+
+This can be useful, for example, if you have a tar archive containing
+a big file and don't want to store the file on disk before processing
+it. You can use a command like this:
+
address@hidden
+tar -xOzf foo.tgz bigfile | process
address@hidden smallexample
+
+or even like this if you want to process the concatenation of the files:
+
address@hidden
+tar -xOzf foo.tgz bigfile1 bigfile2 | process
address@hidden smallexample
+
+Hovewer, @option{--to-command} may be more convenient for use with
+multiple files. See the next section.
+
address@hidden Writing to an External Program
address@hidden Writing to an External Program
+
+You can instruct @command{tar} to send the contents of each extracted
+file to the standard input of an external program:
+
address@hidden @option
address@hidden to-command
address@hidden address@hidden
+Extract files and pipe their contents to the standard input of
address@hidden When this option is used, instead of creating the
+files specified, @command{tar} invokes @var{command} and pipes the
+contents of the files to its standard output. @var{Command} may
+contain command line arguments. The program is executed via
address@hidden -c}. Notice, that @var{command} is executed once for each
regular file
+extracted. Non-regular files (directories, etc.) are ignored when this
+option is used.
address@hidden table
+
+The command can obtain the information about the file it processes
+from the following environment variables:
+
address@hidden @var
address@hidden TAR_FILETYPE, to-command environment
address@hidden TAR_FILETYPE
+Type of the file. It is a single letter with the following meaning:
+
address@hidden @columnfractions 0.10 0.90
address@hidden f @tab Regular file
address@hidden d @tab Directory
address@hidden l @tab Symbolic link
address@hidden h @tab Hard link
address@hidden b @tab Block device
address@hidden c @tab Character device
address@hidden multitable
+
+Currently only regular files are supported.
+
address@hidden TAR_MODE, to-command environment
address@hidden TAR_MODE
+File mode, an octal number.
+
address@hidden TAR_FILENAME, to-command environment
address@hidden TAR_FILENAME
+The name of the file.
+
address@hidden TAR_REALNAME, to-command environment
address@hidden TAR_REALNAME
+Name of the file as stored in the archive.
+
address@hidden TAR_UNAME, to-command environment
address@hidden TAR_UNAME
+Name of the file owner.
+
address@hidden TAR_GNAME, to-command environment
address@hidden TAR_GNAME
+Name of the file owner group.
+
address@hidden TAR_ATIME, to-command environment
address@hidden TAR_ATIME
+Time of last access. It is a decimal number, representing seconds
+since the epoch. If the archive provides times with nanosecond
+precision, the nanoseconds are appended to the timestamp after a
+decimal point.
+
address@hidden TAR_MTIME, to-command environment
address@hidden TAR_MTIME
+Time of last modification.
+
address@hidden TAR_CTIME, to-command environment
address@hidden TAR_CTIME
+Time of last status change.
+
address@hidden TAR_SIZE, to-command environment
address@hidden TAR_SIZE
+Size of the file.
+
address@hidden TAR_UID, to-command environment
address@hidden TAR_UID
+UID of the file owner.
+
address@hidden TAR_GID, to-command environment
address@hidden TAR_GID
+GID of the file owner.
address@hidden table
+
+In addition to these variables, @env{TAR_VERSION} contains the
address@hidden @command{tar} version number.
+
+If @var{command} exits with a non-0 status, @command{tar} will print
+an error message similar to the following:
+
address@hidden
+tar: 2345: Child returned status 1
address@hidden smallexample
+
+Here, @samp{2345} is the PID of the finished process.
+
+If this behavior is not wanted, use @option{--ignore-command-error}:
+
address@hidden @option
address@hidden ignore-command-error
address@hidden --ignore-command-error
+Ignore exit codes of subprocesses. Notice that if the program
+exits on signal or otherwise terminates abnormally, the error message
+will be printed even if this option is used.
+
address@hidden no-ignore-command-error
address@hidden --no-ignore-command-error
+Cancel the effect of any previous @option{--ignore-command-error}
+option. This option is useful if you have set
address@hidden in @env{TAR_OPTIONS}
+(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it.
address@hidden table
+
address@hidden remove files
address@hidden Removing Files
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden remove-files
address@hidden --remove-files
+Remove files after adding them to the archive.
address@hidden table
+
address@hidden Scarce
address@hidden Coping with Scarce Resources
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Small memory
address@hidden Running out of space
+
address@hidden
+* Starting File::
+* Same Order::
address@hidden menu
+
address@hidden Starting File
address@hidden Starting File
+
address@hidden @option
address@hidden starting-file
address@hidden address@hidden
address@hidden -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @option{--extract} (@option{--get}, @option{-x}) or @option{--list}
(@option{-t}).
address@hidden table
+
address@hidden Middle of the archive, starting in the
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @address@hidden (@option{-K
address@hidden) to start extracting only after member @var{name} of the
+archive. This assumes, of course, that there is now free space, or
+that you are now extracting into a different file system. (You could
+also choose to suspend @command{tar}, remove unnecessary files from
+the file system, and then restart the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.
address@hidden Dumps}, @xref{interactive}, and @ref{exclude}.)
+
address@hidden Same Order
address@hidden Same Order
+
address@hidden @option
address@hidden Large lists of file names on small machines
address@hidden same-order
address@hidden preserve-order
address@hidden --same-order
address@hidden --preserve-order
address@hidden -s
+To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with @option{--compare} (@option{--diff},
address@hidden), @option{--list} (@option{-t}) or @option{--extract}
+(@option{--get}, @option{-x}).
address@hidden table
+
+The @option{--same-order} (@option{--preserve-order}, @option{-s}) option
tells @command{tar} that the list of file
+names to be listed or extracted is sorted in the same order as the
+files in the archive. This allows a large list of names to be used,
+even on a small machine that would not otherwise be able to hold all
+the names in memory at the same time. Such a sorted list can easily be
+created by running @samp{tar -t} on the archive and editing its output.
+
+This option is probably never needed on modern computer systems.
+
address@hidden backup
address@hidden Backup options
+
address@hidden backup options
+
address@hidden @command{tar} offers options for making backups of files
+before writing new versions. These options control the details of
+these backups. They may apply to the archive itself before it is
+created or rewritten, as well as individual extracted members. Other
address@hidden programs (@command{cp}, @command{install}, @command{ln},
+and @command{mv}, for example) offer similar options.
+
+Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting archives
+on systems having file name limitations, making different members appear
+has having similar names through the side-effect of name truncation.
+(This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.)
+When any existing file is backed up before being overwritten by extraction,
+then clashing files are automatically be renamed to be unique, and the
+true name is kept for only the last file of a series of clashing files.
+By using verbose mode, users may track exactly what happens.
+
+At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So, please
+do not learn to depend blindly on the details of the backup features.
+For example, currently, directories themselves are never renamed through
+using these options, so, extracting a file over a directory still has
+good chances to fail. Also, backup options apply to created archives,
+not only to extracted members. For created archives, backups will not
+be attempted when the archive is a block or character device, or when it
+refers to a remote file.
+
+For the sake of simplicity and efficiency, backups are made by renaming old
+files prior to creation or extraction, and not by copying. The original
+name is restored if the file creation fails. If a failure occurs after a
+partial extraction of a file, both the backup and the partially extracted
+file are kept.
+
address@hidden @samp
address@hidden address@hidden
address@hidden backup
address@hidden VERSION_CONTROL
address@hidden backups
+Back up files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+
+Use @var{method} to determine the type of backups made.
+If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
+environment variable. And if @env{VERSION_CONTROL} is not set,
+use the @samp{existing} method.
+
address@hidden version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the same values for @var{method} are accepted as in Emacs. This option
+also allows more descriptive names. The valid @var{method}s are:
+
address@hidden @samp
address@hidden t
address@hidden numbered
address@hidden numbered @r{backup method}
+Always make numbered backups.
+
address@hidden nil
address@hidden existing
address@hidden existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
address@hidden never
address@hidden simple
address@hidden simple @r{backup method}
+Always make simple backups.
+
address@hidden table
+
address@hidden address@hidden
address@hidden suffix
address@hidden backup suffix
address@hidden SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{--backup}. If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
address@hidden table
+
address@hidden Applications
address@hidden Notable @command{tar} Usages
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
address@hidden uuencode
+You can easily use archive files to transport a group of files from
+one system to another: put all relevant files into an archive on one
+computer system, transfer the archive to another system, and extract
+the contents there. The basic transfer medium might be magnetic tape,
+Internet FTP, or even electronic mail (though you must encode the
+archive with @command{uuencode} in order to transport it properly by
+mail). Both machines do not have to use the same operating system, as
+long as they both support the @command{tar} program.
+
+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:
+
address@hidden
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
address@hidden smallexample
+
address@hidden
+You can avoid subshells by using @option{-C} option:
+
address@hidden
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
address@hidden smallexample
+
address@hidden
+The command also works using short option forms:
+
address@hidden
+$ @kbd{(cd sourcedir; tar --create --file=- . ) \
+ | (cd targetdir; tar --extract --file=-)}
+# Or:
+$ @kbd{tar --directory sourcedir --create --file=- . ) \
+ | tar --directory targetdir --extract --file=-}
address@hidden smallexample
+
address@hidden
+This is one of the easiest methods to transfer a @command{tar} archive.
+
address@hidden looking ahead
address@hidden Looking Ahead: The Rest of this Manual
+
+You have now seen how to use all eight of the operations available to
address@hidden, and a number of the possible options. The next chapter
+explains how to choose and change file and archive names, how to use
+files to store names of other files which you can then call as
+arguments to @command{tar} (this can help you save time if you expect to
+archive the same list of files a number of times), and so forth.
address@hidden
address@hidden
+
+
+If there are too many files to conveniently list on the command line,
+you can list the names in a file, and @command{tar} will read that file.
address@hidden
+
+There are various ways of causing @command{tar} to skip over some files,
+and not archive them. @xref{Choosing}.
+
address@hidden Backups
address@hidden Performing Backups and Restoring Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @command{tar} is distributed along with the scripts
+which the Free Software Foundation uses for performing backups. There
+is no corresponding scripts available yet for doing restoration of
+files. Even if there is a good chance those scripts may be satisfying
+to you, they are not the only scripts or methods available for doing
+backups and restore. You may well create your own, or use more
+sophisticated packages dedicated to that purpose.
+
+Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
+This is free software, and it is available at these places:
+
address@hidden
+http://www.cs.umd.edu/projects/amanda/amanda.html
+ftp://ftp.cs.umd.edu/pub/amanda
address@hidden smallexample
+
address@hidden
address@hidden
+
+
+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
+all the files in that file system. Those archives can then be used to
+restore any or all of those files (for instance if a disk crashes or a
+file is accidentally deleted). File system @dfn{backups} are also
+called @dfn{dumps}.
+
address@hidden
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental
Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
address@hidden menu
+
address@hidden Full Dumps
address@hidden Using @command{tar} to Perform Full Dumps
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden full dumps
address@hidden dumps, full
+
address@hidden corrupted archives
+Full dumps should only be made when no other people or programs
+are modifying files in the file system. If files are modified while
address@hidden is making the backup, they may not be stored properly in
+the archive, in which case you won't be able to restore them if you
+have to. (Files not being modified are written with no trouble, and do
+not corrupt the entire archive.)
+
+You will want to use the @address@hidden
+(@option{-V @var{archive-label}}) option to give the archive a
+volume label, so you can tell what this archive is even if the label
+falls off the tape, or anything like that.
+
+Unless the file system you are dumping is guaranteed to fit on
+one volume, you will need to use the @option{--multi-volume} (@option{-M})
option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each file system separately you will need to use
+the @option{--one-file-system} option to prevent
address@hidden from crossing file system boundaries when storing
+(sub)directories.
+
+The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
+option is not needed, since this is a complete copy of everything in
+the file system, and a full restore from this backup would only be
+done onto a completely
+empty disk.
+
+Unless you are in a hurry, and trust the @command{tar} program (and your
+tapes), it is a good idea to use the @option{--verify} (@option{-W})
+option, to make sure your files really made it onto the dump properly.
+This will also detect cases where the file was modified while (or just
+after) it was being archived. Not all media (notably cartridge tapes)
+are capable of being verified, unfortunately.
+
address@hidden Incremental Dumps
address@hidden Using @command{tar} to Perform Incremental Dumps
+
address@hidden backup} is a special form of @acronym{GNU} @command{tar} archive
that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+
address@hidden @command{tar} currently offers two options for handling
incremental
+backups: @address@hidden (@option{-g
address@hidden) and @option{--incremental} (@option{-G}).
+
address@hidden listed-incremental
+The option @option{--listed-incremental} instructs tar to operate on
+an incremental archive with additional metadata stored in a standalone
+file, called a @dfn{snapshot file}. The purpose of this file is to help
+determine which files have been changed, added or deleted since the
+last backup, so that the next incremental backup will contain only
+modified files. The name of the snapshot file is given as an argument
+to the option:
+
address@hidden @option
address@hidden address@hidden
address@hidden -g @var{file}
+ Handle incremental backups with snapshot data in @var{file}.
address@hidden table
+
+To create an incremental backup, you would use
address@hidden together with @option{--create}
+(@pxref{create}). For example:
+
address@hidden
+$ @kbd{tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
address@hidden smallexample
+
+This will create in @file{archive.1.tar} an incremental backup of
+the @file{/usr} file system, storing additional metadata in the file
address@hidden/var/log/usr.snar}. If this file does not exist, it will be
+created. The created archive will then be a @dfn{level 0 backup};
+please see the next section for more on backup levels.
+
+Otherwise, if the file @file{/var/log/usr.snar} exists, it
+determines which files are modified. In this case only these files will be
+stored in the archive. Suppose, for example, that after running the
+above command, you delete file @file{/usr/doc/old} and create
+directory @file{/usr/local/db} with the following contents:
+
address@hidden
+$ @kbd{ls /usr/local/db}
+/usr/local/db/data
+/usr/local/db/index
address@hidden smallexample
+
+Some time later you create another incremental backup. You will
+then see:
+
address@hidden
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+tar: usr/local/db: Directory is new
+usr/local/db/
+usr/local/db/data
+usr/local/db/index
address@hidden smallexample
+
address@hidden
+The created archive @file{archive.2.tar} will contain only these
+three members. This archive is called a @dfn{level 1 backup}. Notice
+that @file{/var/log/usr.snar} will be updated with the new data, so if
+you plan to create more @samp{level 1} backups, it is necessary to
+create a working copy of the snapshot file before running
address@hidden The above example will then be modified as follows:
+
address@hidden
+$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr}
address@hidden smallexample
+
+Incremental dumps depend crucially on time stamps, so the results are
+unreliable if you modify a file's time stamps during dumping (e.g.,
+with the @option{--atime-preserve=replace} option), or if you set the clock
+backwards.
+
+Metadata stored in snapshot files include device numbers, which,
+obviously is supposed to be a non-volatile value. However, it turns
+out that NFS devices have undependable values when an automounter
+gets in the picture. This can lead to a great deal of spurious
+redumping in incremental dumps, so it is somewhat useless to compare
+two NFS devices numbers over time. The solution implemented currently
+is to considers all NFS devices as being equal when it comes to
+comparing directories; this is fairly gross, but there does not seem
+to be a better way to go.
+
+Note that incremental archives use @command{tar} extensions and may
+not be readable by address@hidden versions of the @command{tar} program.
+
address@hidden address@hidden, using with @option{--extract}}
address@hidden address@hidden, using with @option{--listed-incremental}}
+To extract from the incremental dumps, use
address@hidden together with @option{--extract}
+option (@pxref{extracting files}). In this case, @command{tar} does
+not need to access snapshot file, since all the data necessary for
+extraction are stored in the archive itself. So, when extracting, you
+can give whatever argument to @option{--listed-incremental}, the usual
+practice is to use @option{--listed-incremental=/dev/null}.
+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
+option, @pxref{incremental-op}).
+
+When extracting from the incremental backup @acronym{GNU} @command{tar}
attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will @emph{delete} those files in the file
+system that did not exist in their directories when the archive was
+created. If you have created several levels of incremental files,
+then in order to restore the exact contents the file system had when
+the last level was created, you will need to restore from all backups
+in turn. Continuing our example, to restore the state of @file{/usr}
+file system, one would address@hidden, that since both archives
+were created withouth @option{-P} option (@pxref{absolute}), these
+commands should be run from the root file system.}:
+
address@hidden
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar}
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar}
address@hidden smallexample
+
+To list the contents of an incremental archive, use @option{--list}
+(@pxref{list}), as usual. To obtain more information about the
+archive, use @option{--listed-incremental} or @option{--incremental}
+combined with two @option{--verbose} address@hidden
address@hidden options were selected to avoid breaking usual
+verbose listing output (@option{--list --verbose}) when using in
+scripts.
+
address@hidden address@hidden, using with @option{--list}}
address@hidden address@hidden, using with @option{--list}}
address@hidden address@hidden, using with @option{--incremental}}
address@hidden address@hidden, using with @option{--listed-incremental}}
+Versions of @acronym{GNU} @command{tar} up to 1.15.1 used to dump verbatim
binary
+contents of the DUMPDIR header (with terminating nulls) when
address@hidden or @option{--listed-incremental} option was
+given, no matter what the verbosity level. This behavior, and,
+especially, the binary output it produced were considered incovenient
+and were changed in version 1.16}:
+
address@hidden
address@hidden --list --incremental --verbose --verbose archive.tar}
address@hidden smallexample
+
+This command will print, for each directory in the archive, the list
+of files in that directory at the time the archive was created. This
+information is put out in a format which is both human-readable and
+unambiguous for a program: each file name is printed as
+
address@hidden
address@hidden @var{file}
address@hidden smallexample
+
address@hidden
+where @var{x} is a letter describing the status of the file: @samp{Y}
+if the file is present in the archive, @samp{N} if the file is not
+included in the archive, or a @samp{D} if the file is a directory (and
+is included in the archive). @xref{Dumpdir}, for the detailed
+description of dumpdirs and status codes. Each such
+line is terminated by a newline character. The last line is followed
+by an additional newline to indicate the end of the data.
+
address@hidden option @option{--incremental} (@option{-G})
+gives the same behavior as @option{--listed-incremental} when used
+with @option{--list} and @option{--extract} options. When used with
address@hidden option, it creates an incremental archive without
+creating snapshot file. Thus, it is impossible to create several
+levels of incremental backups with @option{--incremental} option.
+
address@hidden Backup Levels
address@hidden Levels of Backups
+
+An archive containing all the files in the file system is called a
address@hidden backup} or @dfn{full dump}. You could insure your data by
+creating a full dump every day. This strategy, however, would waste a
+substantial amount of archive media and user time, as unchanged files
+are daily re-archived.
+
+It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level
+one} dump archives all the files that have changed since the last full
+dump.
+
+A typical dump strategy would be to perform a full dump once a week,
+and a level one dump once a day. This means some versions of files
+will in fact be archived more than once, but this dump strategy makes
+it possible to restore a file system to within one day of accuracy by
+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).
+
address@hidden @command{tar} comes with scripts you can use to do full
+and level-one (actually, even level-two and so on) dumps. Using
+scripts (shell programs) to perform backups and restoration is a
+convenient and reliable alternative to typing out file name lists
+and @command{tar} commands by hand.
+
+Before you use these scripts, you need to edit the file
address@hidden, which specifies parameters used by the backup
+scripts and by the restore script. This file is usually located
+in @file{/etc/backup} directory. @xref{Backup Parameters}, for its
+detailed description. Once the backup parameters are set, you can
+perform backups or restoration by running the appropriate script.
+
+The name of the backup script is @code{backup}. The name of the
+restore script is @code{restore}. The following sections describe
+their use in detail.
+
address@hidden Note:} The backup and restoration scripts are
+designed to be used together. While it is possible to restore files by
+hand from an archive which was created using a backup script, and to create
+an archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. @xref{Incremental Dumps}, before
+making such an attempt.
+
address@hidden Backup Parameters
address@hidden Setting Parameters for Backups and Restoration
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @command{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+Syntactically, @file{backup-specs} is a shell script, containing
+mainly variable assignments. However, any valid shell construct
+is allowed in this file. Particularly, you may wish to define
+functions within that script (e.g., see @code{RESTORE_BEGIN} below).
+For more information about shell script syntax, please refer to
address@hidden://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02, the definition of the Shell Command Language}. See also
address@hidden,,Bash Features,bashref,Bash Reference Manual}.
+
+The shell variables controlling behavior of @code{backup} and
address@hidden are described in the following subsections.
+
address@hidden
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
address@hidden menu
+
address@hidden General-Purpose Variables
address@hidden General-Purpose Variables
+
address@hidden {Backup variable} ADMINISTRATOR
+The user name of the backup administrator. @code{Backup} scripts
+sends a backup report to this address.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the time specification in form @var{hours}:@var{minutes},
+or the string @samp{now}.
+
+This variable is used by @code{backup}. Its value may be overridden
+using @option{--time} option (@pxref{Scripted Backups}).
address@hidden defvr
+
address@hidden {Backup variable} TAPE_FILE
+
+The device @command{tar} writes the archive to. If @var{TAPE_FILE}
+is a remote archive (@pxref{remote-dev}), backup script will suppose
+that your @command{mt} is able to access remote devices. If @var{RSH}
+(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
+invocations of @command{mt}.
address@hidden defvr
+
address@hidden {Backup variable} BLOCKING
+
+The blocking factor @command{tar} will use when writing the dump archive.
address@hidden Factor}.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_DIRS
+
+A list of file systems to be dumped (for @code{backup}), or restored
+(for @code{restore}). You can include any directory
+name in the list --- subdirectories on that file system will be
+included, regardless of how they may look to other networked machines.
+Subdirectories on other file systems will be ignored.
+
+The host name specifies which host to run @command{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have @acronym{GNU} @command{tar} installed, and
+must be able to access the directory containing the backup scripts and
+their support files using the same file name that is used on the
+machine where the scripts are run (i.e. what @command{pwd} will print
+when in that directory on that machine). If the host that contains
+the file system does not have this capability, you can specify another
+host as long as it can access the file system through NFS.
+
+If the list of file systems is very long you may wish to put it
+in a separate file. This file is usually named
address@hidden/etc/backup/dirs}, but this name may be overridden in
address@hidden using @code{DIRLIST} variable.
address@hidden defvr
+
address@hidden {Backup variable} DIRLIST
+
+A path to the file containing the list of the file systems to backup
+or restore. By default it is @file{/etc/backup/dirs}.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_FILES
+
+A list of individual files to be dumped (for @code{backup}), or restored
+(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
+in a separate file. This file is usually named
address@hidden/etc/backup/files}, but this name may be overridden in
address@hidden using @code{FILELIST} variable.
address@hidden defvr
+
address@hidden {Backup variable} FILELIST
+
+A path to the file containing the list of the individual files to backup
+or restore. By default it is @file{/etc/backup/files}.
address@hidden defvr
+
address@hidden {Backup variable} MT
+
+Full file name of @command{mt} binary.
address@hidden defvr
+
address@hidden {Backup variable} RSH
address@hidden
+Full file name of @command{rsh} binary or its equivalent. You may wish to
+set it to @code{ssh}, to improve security. In this case you will have
+to use public key authentication.
address@hidden defvr
+
address@hidden {Backup variable} RSH_COMMAND
+
+Full file name of @command{rsh} binary on remote mashines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @acronym{GNU} @command{tar}.
address@hidden defvr
+
address@hidden {Backup variable} VOLNO_FILE
+
+Name of temporary file to hold volume numbers. This needs to be accessible
+by all the machines which have file systems to be dumped.
address@hidden defvr
+
address@hidden {Backup variable} XLIST
+
+Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
+located on the remote machine and containing the list of files to
+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).
+
+This variable affects only @code{backup}.
address@hidden defvr
+
address@hidden {Backup variable} SLEEP_TIME
+
+Time to sleep between dumps of any two successive file systems
+
+This variable affects only @code{backup}.
address@hidden defvr
+
address@hidden {Backup variable} DUMP_REMIND_SCRIPT
+
+Script to be run when it's time to insert a new tape in for the next
+volume. Administrators may want to tailor this script for their site.
+If this variable isn't set, @acronym{GNU} @command{tar} will display its
built-in
+prompt, and will expect confirmation from the console. For the
+description of the default prompt, see @ref{change volume prompt}.
+
address@hidden defvr
+
address@hidden {Backup variable} SLEEP_MESSAGE
+
+Message to display on the terminal while waiting for dump time. Usually
+this will just be some literal text.
address@hidden defvr
+
address@hidden {Backup variable} TAR
+
+Full file name of the @acronym{GNU} @command{tar} executable. If this is not
set, backup
+scripts will search @command{tar} in the current shell path.
address@hidden defvr
+
address@hidden Magnetic Tape Control
address@hidden Magnetic Tape Control
+
+Backup scripts access tape device using special @dfn{hook functions}.
+These functions take a single argument -- the name of the tape
+device. Their names are kept in the following variables:
+
address@hidden {Backup variable} MT_BEGIN
+The name of @dfn{begin} function. This function is called before
+accessing the drive. By default it retensions the tape:
+
address@hidden
+MT_BEGIN=mt_begin
+
+mt_begin() @{
+ mt -f "$1" retension
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden {Backup variable} MT_REWIND
+The name of @dfn{rewind} function. The default definition is as
+follows:
+
address@hidden
+MT_REWIND=mt_rewind
+
+mt_rewind() @{
+ mt -f "$1" rewind
address@hidden
address@hidden smallexample
+
address@hidden defvr
+
address@hidden {Backup variable} MT_OFFLINE
+The name of the function switching the tape off line. By default
+it is defined as follows:
+
address@hidden
+MT_OFFLINE=mt_offline
+
+mt_offline() @{
+ mt -f "$1" offl
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden {Backup variable} MT_STATUS
+The name of the function used to obtain the status of the archive device,
+including error count. Default definition:
+
address@hidden
+MT_STATUS=mt_status
+
+mt_status() @{
+ mt -f "$1" status
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden User Hooks
address@hidden User Hooks
+
address@hidden hooks} are shell functions executed before and after
+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:
+
address@hidden {User Hook Function} hook @var{level} @var{host} @var{fs}
@var{fsname}
+Its arguments are:
+
address@hidden @var
address@hidden level
+Current backup or restore level.
+
address@hidden host
+Name or IP address of the host machine being dumped or restored.
+
address@hidden fs
+Full path name to the file system being dumped or restored.
+
address@hidden fsname
+File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
address@hidden table
address@hidden deffn
+
+Following variables keep the names of user hook functions
+
address@hidden {Backup variable} DUMP_BEGIN
+Dump begin function. It is executed before dumping the file system.
address@hidden defvr
+
address@hidden {Backup variable} DUMP_END
+Executed after dumping the file system.
address@hidden defvr
+
address@hidden {Backup variable} RESTORE_BEGIN
+Executed before restoring the file system.
address@hidden defvr
+
address@hidden {Backup variable} RESTORE_END
+Executed after restoring the file system.
address@hidden defvr
+
address@hidden backup-specs example
address@hidden An Example Text of @file{Backup-specs}
+
+The following is an example of @file{backup-specs}:
+
address@hidden
+# site-specific parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+
+# Use @code{ssh} instead of the less secure @code{rsh}
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
+
+# Override MT_STATUS function:
+my_status() @{
+ mts -t $TAPE_FILE
address@hidden
+MT_STATUS=my_status
+
+# Disable MT_OFFLINE function
+MT_OFFLINE=:
+
+BLOCKING=124
+BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
+
+BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+
address@hidden smallexample
+
address@hidden Scripted Backups
address@hidden Using the Backup Scripts
+
+The syntax for running a backup script is:
+
address@hidden
+backup address@hidden address@hidden
address@hidden smallexample
+
+The @option{level} option requests the dump level. Thus, to produce
+a full dump, specify @code{--level=0} (this is the default, so
address@hidden may be omitted if its value is @code{0}).
address@hidden backward compatibility, the @code{backup} will also
+try to deduce the requested dump level from the name of the
+script itself. If the name consists of a string @samp{level-}
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from @code{backup}
+to @code{level-1} and then run @code{level-1} whenever you need to
+create a level one dump.}
+
+The @option{--time} option determines when should the backup be
+run. @var{Time} may take three forms:
+
address@hidden @asis
address@hidden @var{hh}:@var{mm}
+
+The dump must be run at @var{hh} hours @var{mm} minutes.
+
address@hidden @var{hh}
+
+The dump must be run at @var{hh} hours
+
address@hidden now
+
+The dump must be run immediately.
address@hidden table
+
+You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it
+needs them. Media volumes don't have to correspond to archive
+files --- a multi-volume archive can be started in the middle of a
+tape that already contains the end of another multi-volume archive.
+The @code{restore} script prompts for media by its archive volume,
+so to avoid an error message you should keep track of which tape
+(or disk) contains which volume of the archive (@pxref{Scripted
+Restoration}).
+
+The backup scripts write two files on the file system. The first is a
+record file in @file{/etc/tar-backup/}, which is used by the scripts
+to store and retrieve information about which files were dumped. This
+file is not meant to be read by humans, and should not be deleted by
+them. @xref{Snapshot Files}, for a more detailed explanation of this
+file.
+
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+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
address@hidden@address@hidden, 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.
+
+Following is the full list of options accepted by @code{backup}
+script:
+
address@hidden @option
address@hidden -l @var{level}
address@hidden address@hidden
+Do backup level @var{level} (default 0).
+
address@hidden -f
address@hidden --force
+Force backup even if today's log file already exists.
+
address@hidden address@hidden
address@hidden address@hidden
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
address@hidden -t @var{start-time}
address@hidden address@hidden
+Wait till @var{time}, then do backup.
+
address@hidden -h
address@hidden --help
+Display short help message and exit.
+
address@hidden -V
address@hidden --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden table
+
+
address@hidden Scripted Restoration
address@hidden Using the Restore Script
+
+To restore files that were archived using a scripted backup, use the
address@hidden script. Its usage is quite straightforward. In the
+simplest form, invoke @code{restore --all}, it will
+then restore all the file systems and files specified in
address@hidden (@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
+line. For example, running
+
address@hidden
+restore 'albert:*'
address@hidden smallexample
+
address@hidden
+will restore all file systems on the machine @samp{albert}. A more
+complicated example:
+
address@hidden
+restore 'albert:*' '*:/var'
address@hidden smallexample
+
address@hidden
+This command will restore all file systems on the machine @samp{albert}
+as well as @file{/var} file system on all machines.
+
+By default @code{restore} will start restoring files from the lowest
+available dump level (usually zero) and will continue through
+all available dump levels. There may be situations where such a
+thorough restore is not necessary. For example, you may wish to
+restore only files from the recent level one backup. To do so,
+use @option{--level} option, as shown in the example below:
+
address@hidden
+restore --level=1
address@hidden smallexample
+
+The full list of options accepted by @code{restore} follows:
+
address@hidden @option
address@hidden -a
address@hidden --all
+Restore all file systems and files specified in @file{backup-specs}
+
address@hidden -l @var{level}
address@hidden address@hidden
+Start restoring from the given backup level, instead of the default 0.
+
address@hidden address@hidden
address@hidden address@hidden
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
address@hidden -h
address@hidden --help
+Display short help message and exit.
+
address@hidden -V
address@hidden --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden table
+
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @xref{Tape Positioning}, for a discussion of tape
+positioning.
+
address@hidden
address@hidden:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
address@hidden quotation
+
address@hidden Dumps}, for an explanation of how the script makes
+that determination.
+
address@hidden Choosing
address@hidden Choosing Files and Names for @command{tar}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Certain options to @command{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.
+
+This chapter discusses these options in detail.
+
address@hidden
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
address@hidden menu
+
address@hidden file
address@hidden Choosing and Naming Archive Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Naming an archive
address@hidden Archive Name
address@hidden Choosing an archive file
address@hidden Where is the archive?
+By default, @command{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @command{tar}
+on the system may not have set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
address@hidden where to find (or create) the archive. The
address@hidden@var{archive-name}} (@option{-f @var{archive-name}})
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
address@hidden @option
address@hidden address@hidden, short description}
address@hidden address@hidden
address@hidden -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
address@hidden table
+
+For example, in this @command{tar} command,
+
address@hidden
+$ @kbd{tar -cvf collection.tar blues folk jazz}
address@hidden smallexample
+
address@hidden
address@hidden is the name of the archive. It must directly
+follow the @option{-f} option, since whatever directly follows @option{-f}
address@hidden end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @command{tar} will use this file's name
+for the archive name.
+
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
address@hidden Writing new archives
address@hidden Archive creation
+If you do not name the archive, @command{tar} uses the value of the
+environment variable @env{TAPE} as the file name for the archive. If
+that is not available, @command{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (i.e. @file{/dev/tu00}).
+
address@hidden Standard input and output
address@hidden tar to standard input and output
+If you use @file{-} as an @var{archive-name}, @command{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
address@hidden as an @var{archive-name} when modifying an archive,
address@hidden reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+
+The following example is a convenient way of copying directory
+hierarchy from @file{sourcedir} to @file{targetdir}.
+
address@hidden
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
address@hidden smallexample
+
+The @option{-C} option allows to avoid using subshells:
+
address@hidden
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
address@hidden smallexample
+
+In both examples above, the leftmost @command{tar} invocation archives
+the contents of @file{sourcedir} to the standard output, while the
+rightmost one reads this archive from its standard input and
+extracts it. The @option{-p} option tells it to restore permissions
+of the extracted files.
+
address@hidden Remote devices
address@hidden tar to a remote device
address@hidden
+To specify an archive file on a device attached to a remote machine,
+use the following:
+
address@hidden
address@hidden@var{hostname}:/@var{dev}/@var{file-name}}
address@hidden smallexample
+
address@hidden
address@hidden will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
address@hidden@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
+
address@hidden Local and remote archives
address@hidden and remote archives}
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
address@hidden@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @command{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @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
+the @acronym{GNU} @command{tar} distribution and by default is installed under
address@hidden@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 @option{--force-local} option.
+
+When the archive is being created to @file{/dev/null}, @acronym{GNU}
@command{tar}
+tries to minimize input and output operations. The Amanda backup
+system, when used with @acronym{GNU} @command{tar}, has an initial sizing pass
which
+uses this feature.
+
address@hidden Selecting Archive Members
address@hidden Selecting Archive Members
address@hidden Specifying files to act on
address@hidden Specifying archive members
+
address@hidden Name arguments} specify which files in the file system
address@hidden operates on, when creating or adding to an archive, or which
+archive members @command{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
+
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
address@hidden
address@hidden @var{operation} address@hidden @var{option2} @dots{}]
address@hidden name-1} @var{file name-2} @dots{}]
address@hidden smallexample
+
+If a file name begins with dash (@samp{-}), precede it with
address@hidden option to prevent it from being treated as an
+option.
+
address@hidden name quoting}
+By default @acronym{GNU} @command{tar} attempts to @dfn{unquote} each file or
member
+name, replacing @dfn{escape sequences} according to the following
+table:
+
address@hidden @columnfractions 0.20 0.60
address@hidden Escape @tab Replaced with
address@hidden \a @tab Audible bell (ASCII 7)
address@hidden \b @tab Backspace (ASCII 8)
address@hidden \f @tab Form feed (ASCII 12)
address@hidden \n @tab New line (ASCII 10)
address@hidden \r @tab Carriage return (ASCII 13)
address@hidden \t @tab Horizontal tabulation (ASCII 9)
address@hidden \v @tab Vertical tabulation (ASCII 11)
address@hidden \? @tab ASCII 127
address@hidden address@hidden @tab ASCII @var{n} (@var{n} should be an octal
number
+ of up to 3 digits)
address@hidden multitable
+
+A backslash followed by any other symbol is retained.
+
+This default behavior is controlled by the following command line
+option:
+
address@hidden @option
address@hidden unquote
address@hidden --unquote
+Enable unquoting input file or member names (default).
+
address@hidden no-unquote
address@hidden --no-unquote
+Disable unquoting input file or member names.
address@hidden table
+
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @command{tar}.
+
+If you do not specify files, @command{tar} behavior differs depending
+on the operation mode as described below:
+
+When @command{tar} is invoked with @option{--create} (@option{-c}),
address@hidden will stop immediately, reporting the following:
+
address@hidden
address@hidden
+$ @kbd{tar cf a.tar}
+tar: Cowardly refusing to create an empty archive
+Try `tar --help' or `tar --usage' for more information.
address@hidden group
address@hidden smallexample
+
+If you specify either @option{--list} (@option{-t}) or
address@hidden (@option{--get}, @option{-x}), @command{tar}
+operates on all the archive members in the archive.
+
+If run with @option{--diff} option, tar will compare the archive with
+the contents of the current working directory.
+
+If you specify any other operation, @command{tar} does nothing.
+
+By default, @command{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @command{tar} selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
+
address@hidden files
address@hidden Reading Names from a File
+
address@hidden Reading file names from a file
address@hidden Lists of file names
address@hidden File Name arguments, alternatives
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
address@hidden@var{file-of-names}} (@option{-T
address@hidden) option to @command{tar}. Give the name of the
+file which contains the list of files to include as the argument to
address@hidden In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @command{find} utility.
+
address@hidden @option
address@hidden files-from
address@hidden address@hidden
address@hidden -T @var{file-name}
+Get names to extract or create from file @var{file-name}.
address@hidden table
+
+If you give a single dash as a file name for @option{--files-from}, (i.e.,
+you specify either @code{--files-from=-} or @code{-T -}), then the file
+names are read from standard input.
+
+Unless you are running @command{tar} with @option{--create}, you can not use
+both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
+command.
+
+Any number of @option{-T} options can be given in the command line.
+
+The following example shows how to use @command{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @option{-T} option to
address@hidden to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @option{-z} option to
address@hidden compresses the archive with @command{gzip}; @pxref{gzip} for
+more information.)
+
address@hidden
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
address@hidden smallexample
+
address@hidden
+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 address@hidden of @acronym{GNU} @command{tar} up to 1.15.1
+recognized only @option{-C} option in file lists, and only if the
+option and its argument occupied two consecutive lines.} For example,
+the common use of this feature is to change to another directory by
+specifying @option{-C} option:
+
address@hidden
address@hidden
+$ @kbd{cat list}
+-C/etc
+passwd
+hosts
+-C/lib
+libc.a
+$ @kbd{tar -c -f foo.tar --files-from list}
address@hidden group
address@hidden smallexample
+
address@hidden
+In this example, @command{tar} will first switch to @file{/etc}
+directory and add files @file{passwd} and @file{hosts} to the
+archive. Then it will change to @file{/lib} directory and will archive
+the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will
+contain:
+
address@hidden
address@hidden
+$ @kbd{tar tf foo.tar}
+passwd
+hosts
+libc.a
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden address@hidden, using in @option{--files-from} argument}
+Notice that the option parsing algorithm used with @option{-T} is
+stricter than the one used by shell. Namely, when specifying option
+arguments, you should observe the following rules:
+
address@hidden @bullet
address@hidden
+When using short (single-letter) option form, its argument must
+immediately follow the option letter, without any intervening
+whitespace. For example: @code{-Cdir}.
+
address@hidden
+When using long option form, the option argument must be separated
+from the option by a single equal sign. No whitespace is allowed on
+any side of the equal sign. For example: @code{--directory=dir}.
+
address@hidden
+For both short and long option forms, the option argument can be given
+on the next line after the option name, e.g.:
+
address@hidden
address@hidden
+--directory
+dir
address@hidden group
address@hidden smallexample
+
address@hidden
+and
+
address@hidden
address@hidden
+-C
+dir
address@hidden group
address@hidden smallexample
address@hidden itemize
+
address@hidden add-file
+If you happen to have a file whose name starts with @samp{-},
+precede it with @option{--add-file} option to prevent it from
+being recognized as an option. For example: @code{--add-file=--my-file}.
+
address@hidden
+* nul::
address@hidden menu
+
address@hidden nul
address@hidden @code{NUL} Terminated File Names
+
address@hidden File names, terminated by @code{NUL}
address@hidden @code{NUL} terminated file names
+The @option{--null} option causes
address@hidden@var{file-of-names}} (@option{-T @var{file-of-names}})
+to read file names terminated by a @code{NUL} instead of a newline, so
+files whose names contain newlines can be archived using
address@hidden
+
address@hidden @option
address@hidden null
address@hidden --null
+Only consider @code{NUL} terminated file names, instead of files that
+terminate in a newline.
address@hidden table
+
+The @option{--null} option is just like the one in @acronym{GNU}
address@hidden and @command{cpio}, and is useful with the
address@hidden predicate of @acronym{GNU} @command{find}. In
address@hidden, @option{--null} also disables special handling for
+file names that begin with dash.
+
+This example shows how to use @command{find} to generate a list of files
+larger than 800K in length and put that list into a file called
address@hidden 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
address@hidden and @option{-T} options to specify that @command{tar} get the
+files from that file, @file{long-files}, to create the archive
address@hidden The @option{--null} option to @command{tar} will cause
address@hidden to recognize the @code{NUL} separator between files.
+
address@hidden
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
address@hidden smallexample
+
address@hidden
address@hidden
+
+
address@hidden exclude
address@hidden Excluding Some Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden File names, excluding files by
address@hidden Excluding files by name and pattern
address@hidden Excluding files by file system
+To avoid operating on files whose names match a particular pattern,
+use the @option{--exclude} or @option{--exclude-from} options.
+
address@hidden @option
address@hidden exclude
address@hidden address@hidden
+Causes @command{tar} to ignore files that match the @var{pattern}.
address@hidden table
+
address@hidden exclude
+The @address@hidden option prevents any file or
+member whose name matches the shell wildcard (@var{pattern}) from
+being operated on.
+For example, to create an archive with all the contents of the directory
address@hidden except for files whose names end in @file{.o}, use the
+command @samp{tar -cf src.tar --exclude='*.o' src}.
+
+You may give multiple @option{--exclude} options.
+
address@hidden @option
address@hidden exclude-from
address@hidden address@hidden
address@hidden -X @var{file}
+Causes @command{tar} to ignore files that match the patterns listed in
address@hidden
address@hidden table
+
address@hidden exclude-from
+Use the @option{--exclude-from} option to read a
+list of patterns, one per line, from @var{file}; @command{tar} will
+ignore files matching those patterns. Thus if @command{tar} is
+called as @address@hidden -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
+
address@hidden @option
address@hidden exclude-caches
address@hidden --exclude-caches
+Causes @command{tar} to ignore directories containing a cache directory tag.
address@hidden table
+
address@hidden exclude-caches
+When creating an archive, the @option{--exclude-caches} option causes
address@hidden to exclude all directories that contain a @dfn{cache
+directory tag}. A cache directory tag is a short file with the
+well-known name @file{CACHEDIR.TAG} and having a standard header
+specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
+Various applications write cache directory tags into directories they
+use to hold regenerable, non-precious data, so that such data can be
+more easily excluded from backups.
+
address@hidden
+* problems with exclude::
address@hidden menu
+
address@hidden problems with exclude
address@hidden Problems with Using the @code{exclude} Options
+
address@hidden address@hidden, potential problems with}
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
+
address@hidden @bullet
address@hidden
+The main operating mode of @command{tar} does not act on a path name
+explicitly listed on the command line if one of its file name
+components is excluded. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{dir.o/foo} after all the options have been
+listed, @samp{dir.o/foo} will be excluded from the archive.
+
address@hidden
+You can sometimes confuse the meanings of @option{--exclude} and
address@hidden Be careful: use @option{--exclude} when files
+to be excluded are given as a pattern on the command line. Use
address@hidden to introduce the name of a file which contains
+a list of patterns, one per line; each of these patterns can exclude
+zero, one, or many files.
+
address@hidden
+When you use @address@hidden, be sure to quote the
address@hidden parameter, so @acronym{GNU} @command{tar} sees wildcard
characters
+like @samp{*}. If you do not do this, the shell might expand the
address@hidden itself using files at hand, so @command{tar} might receive a
+list of files instead of one pattern, or none at all, making the
+command somewhat illegal. This might not correspond to what you want.
+
+For example, write:
+
address@hidden
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
address@hidden smallexample
+
address@hidden
+rather than:
+
address@hidden
+# @emph{Wrong!}
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
address@hidden smallexample
+
address@hidden
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @command{tar}. If you try to use
address@hidden syntax to describe files to be excluded, your command
+might fail.
+
address@hidden
address@hidden
address@hidden
+
+In earlier versions of @command{tar}, what is now the
address@hidden option was called @option{--exclude} instead.
+Now, @option{--exclude} applies to patterns listed on the command
+line and @option{--exclude-from} applies to patterns listed in a
+file.
+
address@hidden itemize
+
address@hidden wildcards
address@hidden Wildcards Patterns and Matching
+
address@hidden is the operation by which @dfn{wildcard} characters,
address@hidden or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. @acronym{GNU} @command{tar} can
use wildcard
+patterns for matching (or globbing) archive members when extracting
+from or listing an archive. Wildcard patterns are also used for
+verifying volume labels of @command{tar} archives. This section has the
+purpose of explaining wildcard syntax for @command{tar}.
+
address@hidden
address@hidden
+
+
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
address@hidden in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
address@hidden would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
address@hidden would match any of the characters, @samp{-}, @samp{\},
address@hidden, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
address@hidden in a character class.)
+
address@hidden Excluding characters from a character class
address@hidden Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
+
+Other characters of the class stand for themselves. The special
+construction @address@hidden@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
address@hidden, inclusive.
+
address@hidden
address@hidden
+
+
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: thus, excluding a directory also excludes all the files beneath it.
+
address@hidden
+* controlling pattern-matching::
address@hidden menu
+
address@hidden controlling pattern-matching
address@hidden Controlling Pattern-Matching
+
+For the purposes of this section, we call @dfn{exclusion members} all
+member names obtained while processing @option{--exclude} and
address@hidden options, and @dfn{inclusion members} those
+member names that were given in the command line or read from the file
+specified with @option{--files-from} option.
+
+These two pairs of member lists are used in the following operations:
address@hidden, @option{--extract}, @option{--list},
address@hidden
+
+There are no inclusion members in create mode (@option{--create} and
address@hidden), since in this mode the names obtained from the
+command line refer to @emph{files}, not archive members.
+
+By default, inclusion members are compared with archive members
+literally @footnote{Notice that earlier @acronym{GNU} @command{tar} versions
used
+globbing for inclusion members, which contradicted to UNIX98
+specification and was not documented. @xref{Changes}, for more
+information on this and other changes.} and exclusion members are
+treated as globbing patterns. For example:
+
address@hidden
address@hidden
+$ @kbd{tar tf foo.tar}
+a.c
+b.c
+a.txt
+[remarks]
+# @i{Member names are used verbatim:}
+$ @kbd{tar -xf foo.tar -v '[remarks]'}
+[remarks]
+# @i{Exclude member names are globbed:}
+$ @kbd{tar -xf foo.tar -v --exclude '*.c'}
+a.txt
+[remarks]
address@hidden group
address@hidden smallexample
+
+This behavior can be altered by using the following options:
+
address@hidden @option
address@hidden wildcards
address@hidden --wildcards
+Treat all member names as wildcards.
+
address@hidden no-wildcards
address@hidden --no-wildcards
+Treat all member names as literal strings.
address@hidden table
+
+Thus, to extract files whose names end in @samp{.c}, you can use:
+
address@hidden
+$ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
+a.c
+b.c
address@hidden smallexample
+
address@hidden
+Notice quoting of the pattern to prevent the shell from interpreting
+it.
+
+The effect of @option{--wildcards} option is cancelled by
address@hidden This can be used to pass part of
+the command line arguments verbatim and other part as globbing
+patterns. For example, the following invocation:
+
address@hidden
+$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
address@hidden smallexample
+
address@hidden
+instructs @command{tar} to extract from @file{foo.tar} all files whose
+names end in @samp{.txt} and the file named @file{[remarks]}.
+
+Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where @samp{*}, @samp{?}, and
address@hidden are the usual shell wildcards, @samp{\} escapes wildcards,
+and wildcards can match @samp{/}.
+
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and names are used as-is. For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
+
+However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+
address@hidden
+--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
address@hidden smallexample
+
address@hidden
+ignores case when excluding @samp{makefile}, but not when excluding
address@hidden
+
address@hidden @option
address@hidden anchored
address@hidden no-anchored
address@hidden --anchored
address@hidden --no-anchored
+If anchored, a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any
+subsequence. Default is @option{--no-anchored} for exclusion members
+and @option{--anchored} inclusion members.
+
address@hidden ignore-case
address@hidden no-ignore-case
address@hidden --ignore-case
address@hidden --no-ignore-case
+When ignoring case, upper-case patterns match lower-case names and vice versa.
+When not ignoring case (the default), matching is case-sensitive.
+
address@hidden wildcards-match-slash
address@hidden no-wildcards-match-slash
address@hidden --wildcards-match-slash
address@hidden --no-wildcards-match-slash
+When wildcards match slash (the default for exclusion members), a
+wildcard like @samp{*} in the pattern can match a @samp{/} in the
+name. Otherwise, @samp{/} is matched only by @samp{/}.
+
address@hidden table
+
+The @option{--recursion} and @option{--no-recursion} options
+(@pxref{recurse}) also affect how member patterns are interpreted. If
+recursion is in effect, a pattern matches a name if it matches any of
+the name's parent directories.
+
+The following table summarizes pattern-matching default values:
+
address@hidden @columnfractions .3 .7
address@hidden Members @tab Default settings
address@hidden Inclusion @tab @option{--no-wildcards --anchored
--no-wildcards-match-slash}
address@hidden Exclusion @tab @option{--wildcards --no-anchored
--wildcards-match-slash}
address@hidden multitable
+
address@hidden quoting styles
address@hidden Quoting Member Names
+
+When displaying member names, @command{tar} takes care to avoid
+ambiguities caused by certain characters. This is called @dfn{name
+quoting}. The characters in question are:
+
address@hidden @bullet
address@hidden Non-printable control characters:
+
address@hidden @columnfractions 0.20 0.10 0.60
address@hidden Character @tab ASCII @tab Character name
address@hidden \a @tab 7 @tab Audible bell
address@hidden \b @tab 8 @tab Backspace
address@hidden \f @tab 12 @tab Form feed
address@hidden \n @tab 10 @tab New line
address@hidden \r @tab 13 @tab Carriage return
address@hidden \t @tab 9 @tab Horizontal tabulation
address@hidden \v @tab 11 @tab Vertical tabulation
address@hidden multitable
+
address@hidden Space (ASCII 32)
+
address@hidden Single and double quotes (@samp{'} and @samp{"})
+
address@hidden Backslash (@samp{\})
address@hidden itemize
+
+The exact way @command{tar} uses to quote these characters depends on
+the @dfn{quoting style}. The default quoting style, called
address@hidden (see below), uses backslash notation to represent control
+characters, space and backslash. Using this quoting style, control
+characters are represented as listed in column @samp{Character} in the
+above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
+
address@hidden @command{tar} offers seven distinct quoting styles, which can be
selected
+using @option{--quoting-style} option:
+
address@hidden @option
address@hidden address@hidden
address@hidden quoting-style
+
+Sets quoting style. Valid values for @var{style} argument are:
+literal, shell, shell-always, c, escape, locale, clocale.
address@hidden table
+
+These styles are described in detail below. To illustrate their
+effect, we will use an imaginary tar archive @file{arch.tar}
+containing the following members:
+
address@hidden
address@hidden
+# 1. Contains horizontal tabulation character.
+a tab
+# 2. Contains newline character
+a
+newline
+# 3. Contains a space
+a space
+# 4. Contains double quotes
+a"double"quote
+# 5. Contains single quotes
+a'single'quote
+# 6. Contains a backslash character:
+a\backslash
address@hidden group
address@hidden smallexample
+
+Here is how usual @command{ls} command would have listed them, if they
+had existed in the current working directory:
+
address@hidden
address@hidden
+$ @kbd{ls}
+a\ttab
+a\nnewline
+a\ space
+a"double"quote
+a'single'quote
+a\\backslash
address@hidden group
address@hidden smallexample
+
+Quoting styles:
+
address@hidden @samp
address@hidden literal
+No quoting, display each character as is:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=literal}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\backslash
+./a tab
+./a
+newline
address@hidden group
address@hidden smallexample
+
address@hidden shell
+Display characters the same way Bourne shell does:
+control characters, except @samp{\t} and @samp{\n}, are printed using
+backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
+single quote is printed as @samp{\'}. If a name contains any quoted
+characters, it is enclosed in single quotes. In particular, if a name
+contains single quotes, it is printed as several single-quoted strings:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=shell}
+./
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
address@hidden group
address@hidden smallexample
+
address@hidden shell-always
+Same as @samp{shell}, but the names are always enclosed in single
+quotes:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=shell-always}
+'./'
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
address@hidden group
address@hidden smallexample
+
address@hidden c
+Use the notation of the C programming language. All names are
+enclosed in double quotes. Control characters are quoted using
+backslash notations, double quotes are represented as @samp{\"},
+backslash characters are represented as @samp{\\}. Single quotes and
+spaces are not quoted:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=c}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
address@hidden group
address@hidden smallexample
+
address@hidden escape
+Control characters are printed using backslash notation, a space is
+printed as @samp{\ } and a backslash as @samp{\\}. This is the
+default quoting style, unless it was changed when configured the
+package.
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=escape}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
address@hidden group
address@hidden smallexample
+
address@hidden locale
+Control characters, single quote and backslash are printed using
+backslash notation. All names are quoted using left and right
+quotation marks, appropriate to the current locale. If it does not
+define quotation marks, use @samp{`} as left and @samp{'} as right
+quotation marks. Any occurrences of the right quotation mark in a
+name are escaped with @samp{\}, for example:
+
+For example:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=locale}
+`./'
+`./a space'
+`./a\'single\'quote'
+`./a"double"quote'
+`./a\\backslash'
+`./a\ttab'
+`./a\nnewline'
address@hidden group
address@hidden smallexample
+
address@hidden clocale
+Same as @samp{locale}, but @samp{"} is used for both left and right
+quotation marks, if not provided by the currently selected locale:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=clocale}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
address@hidden group
address@hidden smallexample
address@hidden table
+
+You can specify which characters should be quoted in addition to those
+implied by the current quoting style:
+
address@hidden @option
address@hidden address@hidden
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them.
address@hidden table
+
+For example, using @samp{escape} quoting (compare with the usual
+escape listing above):
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
+./
+./a\ space
+./a'single'quote
+./a\"double\"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
address@hidden group
address@hidden smallexample
+
+To disable quoting of such additional characters, use the following
+option:
+
address@hidden @option
address@hidden address@hidden
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option.
address@hidden table
+
+This option is particularly useful if you have added
address@hidden to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
+and wish to disable it for the current invocation.
+
+Note, that @option{--no-quote-chars} does @emph{not} disable those
+characters that are quoted by default in the selected quoting style.
+
address@hidden transform
address@hidden Modifying File and Member Names
+
address@hidden archives contain detailed information about files stored
+in them and full file names are part of that information. When
+storing file to an archive, its file name is recorded in the archive
+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
+of a file archiver. However, there are some cases when it is not.
+
+First of all, it is often unsafe to extract archive members with
+absolute file names or those that begin with a @file{../}. @acronym{GNU}
@command{tar}
+takes special precautions when extracting such names and provides a
+special option for handling them, which is described in
address@hidden
+
+Secondly, you may wish to extract file names without some leading
+directory components, or with otherwise modified names. In other
+cases it is desirable to store files under differing names in the
+archive.
+
address@hidden @command{tar} provides two options for these needs.
+
address@hidden @option
address@hidden strip-components
address@hidden address@hidden
+Strip given @var{number} of leading components from file names before
+extraction.
address@hidden table
+
+For example, suppose you have archived whole @file{/usr} hierarchy to
+a tar archive named @file{usr.tar}. Among other files, this archive
+contains @file{usr/include/stdlib.h}, which you wish to extract to
+the current working directory. To do so, you type:
+
address@hidden
+$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h}
address@hidden smallexample
+
+The option @option{--strip=2} instructs @command{tar} to strip the
+two leading components (@file{usr/} and @file{include/}) off the file
+name.
+
+If you add to the above invocation @option{--verbose} (@option{-v})
+option, you will note that the verbose listing still contains the
+full file name, with the two removed components still in place. This
+can be inconvenient, so @command{tar} provides a special option for
+altering this behavior:
+
address@hidden
address@hidden @option
address@hidden show-transformed-names
address@hidden --show-transformed-names
+Display file or member names with all requested transformations
+applied.
address@hidden table
+
address@hidden
+For example:
+
address@hidden
address@hidden
+$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h}
+usr/include/stdlib.h
+$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h}
+stdlib.h
address@hidden group
address@hidden smallexample
+
+Notice that in both cases the file is @file{stdlib.h} extracted to the
+current working directory, @option{--show-transformed-names} affects
+only the way its name is displayed.
+
+This option is especially useful for verifying whether the invocation
+will have the desired effect. Thus, before running
+
address@hidden
+$ @kbd{tar -x address@hidden
address@hidden smallexample
+
address@hidden
+it is often advisable to run
+
address@hidden
+$ @kbd{tar -t -v --show-transformed address@hidden
address@hidden smallexample
+
address@hidden
+to make sure the command will produce the intended results.
+
+In case you need to apply more complex modifications to the file name,
address@hidden @command{tar} provides a general-purpose transformation option:
+
address@hidden @option
address@hidden transform
address@hidden address@hidden
+Modify file names using supplied @var{expression}.
address@hidden table
+
address@hidden
+The @var{expression} is a @command{sed}-like replace expression of the
+form:
+
address@hidden
+s/@var{regexp}/@var{replace}/address@hidden
address@hidden smallexample
+
address@hidden
+where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
+replacement for each file name part that matches @var{regexp}. Both
address@hidden and @var{replace} are described in detail in
address@hidden "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
+
+Supported @var{flags} are:
+
address@hidden @samp
address@hidden g
+Apply the replacement to @emph{all} matches to the @var{regexp}, not
+just the first.
+
address@hidden i
+Use case-insensitive matching
+
address@hidden x
address@hidden is an @dfn{extended regular expression} (@pxref{Extended
+regexps, Extended regular expressions, Extended regular expressions,
+sed, GNU sed}).
+
address@hidden @var{number}
+Only replace the @var{number}th match of the @var{regexp}.
+
+Note: the @var{posix} standard does not specify what should happen
+when you mix the @samp{g} and @var{number} modifiers. @acronym{GNU}
@command{tar}
+follows the GNU @command{sed} implementation in this regard, so
+the the interaction is defined to be: ignore matches before the
address@hidden, and then match and replace all matches from the
address@hidden on.
+
address@hidden table
+
+Any delimiter can be used in lieue of @samp{/}, the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
address@hidden
address@hidden
+s/one/two/
+s,one,two,
address@hidden group
address@hidden smallexample
+
+Changing delimiters is often useful when the @var{regex} contains
+slashes. For example, it is more convenient to write @code{s,/,-,} than
address@hidden/\//-/}.
+
+Here are several examples of @option{--transform} usage:
+
address@hidden
address@hidden Extract @file{usr/} hierarchy into @file{usr/local/}:
+
address@hidden
+$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Strip two leading directory components (equivalent to
address@hidden):
+
address@hidden
+$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Prepend @file{/prefix/} to each file name:
+
address@hidden
+$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Convert each file name to lower case:
+
address@hidden
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
address@hidden smallexample
+
address@hidden enumerate
+
+Unlike @option{--strip-components}, @option{--transform} can be used
+in any @acronym{GNU} @command{tar} operation mode. For example, the following
command
+adds files to the archive while replacing the leading @file{usr/}
+component with @file{var/}:
+
address@hidden
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /}
address@hidden smallexample
+
+To test @option{--transform} effect we suggest using
address@hidden option:
+
address@hidden
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
+ --verbose --show-transformed-names /}
address@hidden smallexample
+
+If both @option{--strip-components} and @option{--transform} are used
+together, then @option{--transform} is applied first, and the required
+number of components is then stripped from its result.
+
address@hidden after
address@hidden Operating Only on New Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Excluding file by age
address@hidden Data Modification time, excluding files by
address@hidden Modification time, excluding files by
address@hidden Age, excluding files by
+The @address@hidden (@address@hidden,
address@hidden @var{date}}) option causes @command{tar} to only work on
+files whose data modification or status change times are newer than
+the @var{date} given. If @var{date} starts with @samp{/} or @samp{.},
+it is taken to be a file name; the data modification time of that file
+is used as the date. If you use this option when creating or appending
+to an archive, the archive will only include new files. If you use
address@hidden when extracting an archive, @command{tar} will
+only extract files newer than the @var{date} you specify.
+
+If you only want @command{tar} to make the date comparison based on
+modification of the file's data (rather than status
+changes), then use the @address@hidden option.
+
+You may use these options with any operation. Note that these options
+differ from the @option{--update} (@option{-u}) operation in that they
+allow you to specify a particular date against which @command{tar} can
+compare when deciding whether or not to archive the files.
+
address@hidden @option
address@hidden after-date
address@hidden newer
address@hidden address@hidden
address@hidden address@hidden
address@hidden -N @var{date}
+Only store files newer than @var{date}.
+
+Acts on files only if their data modification or status change times are
+later than @var{date}. Use in conjunction with any operation.
+
+If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
+name; the data modification time of that file is used as the date.
+
address@hidden newer-mtime
address@hidden address@hidden
+Acts like @option{--after-date}, but only looks at data modification times.
address@hidden table
+
+These options limit @command{tar} to operate only on files which have
+been modified after the date specified. A file's status is considered to have
+changed if its contents have been modified, or if its owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see @ref{Date input formats}; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+Gurus would say that @option{--after-date} tests both the data
+modification time (@code{mtime}, the time the contents of the file
+were last modified) and the status change time (@code{ctime}, the time
+the file's status was last changed: owner, permissions, etc.@:)
+fields, while @option{--newer-mtime} tests only the @code{mtime}
+field.
+
+To be precise, @option{--after-date} checks @emph{both} @code{mtime} and
address@hidden and processes the file if either one is more recent than
address@hidden, while @option{--newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither does it use @code{atime} (the last time the
+contents of the file were looked at).
+
+Date specifiers can have embedded spaces. Because of this, you may need
+to quote date arguments to keep the shell from parsing them as separate
+arguments. For example, the following command will add to the archive
+all the files modified less than two days ago:
+
address@hidden
+$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
address@hidden smallexample
+
+When any of these options is used with the option @option{--verbose}
+(@pxref{verbose tutorial}) @acronym{GNU} @command{tar} will try to convert the
specified
+date back to its textual representation and compare that with the
+one given with the option. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date. For example:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
+tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
+13:19:37.232434
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden Note:} @option{--after-date} and @option{--newer-mtime}
+should not be used for incremental backups. @xref{Incremental Dumps},
+for proper way of creating incremental backups.
address@hidden quotation
+
address@hidden recurse
address@hidden Descending into Directories
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Avoiding recursion in directories
address@hidden Descending directories, avoiding
address@hidden Directories, avoiding recursion
address@hidden Recursion in directories, avoiding
+
address@hidden
address@hidden
+
+
+Usually, @command{tar} will recursively explore all directories (either
+those given on the command line or through the @option{--files-from}
+option) for the various files they contain. However, you may not always
+want @command{tar} to act this way.
+
address@hidden no-recursion
+The @option{--no-recursion} option inhibits @command{tar}'s recursive descent
+into specified directories. If you specify @option{--no-recursion}, you can
+use the @command{find} utility for hunting through levels of directories to
+construct a list of file names which you could then pass to @command{tar}.
address@hidden allows you to be more selective when choosing which files to
+archive; see @ref{files}, for more information on using @command{find} with
address@hidden, or look.
+
address@hidden @option
address@hidden --no-recursion
+Prevents @command{tar} from recursively descending directories.
+
address@hidden recursion
address@hidden --recursion
+Requires @command{tar} to recursively descend directories.
+This is the default.
address@hidden table
+
+When you use @option{--no-recursion}, @acronym{GNU} @command{tar} grabs
+directory entries themselves, but does not descend on them
+recursively. Many people use @command{find} for locating files they
+want to back up, and since @command{tar} @emph{usually} recursively
+descends on directories, they have to use the @address@hidden -type d}}
+test in their @command{find} invocation (@pxref{Type, Type, Type test,
+find, Finding Files}), as they usually do not want all the files in a
+directory. They then use the @option{--files-from} option to archive
+the files located via @command{find}.
+
+The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
address@hidden (@option{--preserve-permissions},
address@hidden) option does not affect them---while users might really
+like it to. Specifying @option{--no-recursion} is a way to tell
address@hidden to grab only the directory entries given to it, adding
+no new files on its own. To summarize, if you use @command{find} to
+create a list of files to be stored in an archive, use it as follows:
+
address@hidden
address@hidden
+$ @kbd{find @var{dir} @var{tests} | \
+ tar -cf @var{archive} -T - --no-recursion}
address@hidden group
address@hidden smallexample
+
+The @option{--no-recursion} option also applies when extracting: it
+causes @command{tar} to extract only the matched directory entries, not
+the files under those directories.
+
+The @option{--no-recursion} option also affects how globbing patterns
+are interpreted (@pxref{controlling pattern-matching}).
+
+The @option{--no-recursion} and @option{--recursion} options apply to
+later options and operands, and can be overridden by later occurrences
+of @option{--no-recursion} and @option{--recursion}. For example:
+
address@hidden
+$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord}
address@hidden smallexample
+
address@hidden
+creates an archive with one entry for @file{grape}, and the recursive
+contents of @file{grape/concord}, but no entries under @file{grape}
+other than @file{grape/concord}.
+
address@hidden one
address@hidden Crossing File System Boundaries
address@hidden File system boundaries, not crossing
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden will normally automatically cross file system boundaries in
+order to archive files which are part of a directory tree. You can
+change this behavior by running @command{tar} and specifying
address@hidden This option only affects files that are
+archived because they are in a directory that is being archived;
address@hidden will still archive files explicitly named on the command line
+or through @option{--files-from}, regardless of where they reside.
+
address@hidden @option
address@hidden one-file-system
address@hidden --one-file-system
+Prevents @command{tar} from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
address@hidden table
+
+The @option{--one-file-system} option causes @command{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same file system as the directory itself, then
address@hidden will not archive that file. If the file is a directory
+itself, @command{tar} will not archive anything beneath it; in other words,
address@hidden will not cross mount points.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
address@hidden (@option{-v}), files that are excluded are
+mentioned by name on the standard error.
+
address@hidden
+* directory:: Changing Directory
+* absolute:: Absolute File Names
address@hidden menu
+
address@hidden directory
address@hidden Changing the Working Directory
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden Changing directory mid-stream
address@hidden Directory, changing mid-stream
address@hidden Working directory, specifying
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using
address@hidden (@option{-T}), use @option{--directory} (@option{-C}).
+This will change the working directory to the specified directory
+after that point in the list.
+
address@hidden @option
address@hidden directory
address@hidden address@hidden
address@hidden -C @var{directory}
+Changes the working directory in the middle of a command line.
address@hidden table
+
+For example,
+
address@hidden
+$ @kbd{tar -c -f jams.tar grape prune -C food cherry}
address@hidden smallexample
+
address@hidden
+will place the files @file{grape} and @file{prune} from the current
+directory into the archive @file{jams.tar}, followed by the file
address@hidden from the directory @file{food}. This option is especially
+useful when you have several widely separated files that you want to
+store in the same archive.
+
+Note that the file @file{cherry} is recorded in the archive under the
+precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the
+archive will contain three files that all appear to have come from the
+same directory; if the archive is extracted with plain @samp{tar
+--extract}, all three files will be written in the current directory.
+
+Contrast this with the command,
+
address@hidden
+$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
address@hidden smallexample
+
address@hidden
+which records the third file in the archive under the name
address@hidden/cherry} so that, if the archive is extracted using
address@hidden --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.
+The following command places the files @file{/etc/passwd},
address@hidden/etc/hosts}, and @file{/lib/libc.a} into the archive
address@hidden:
+
address@hidden
+$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
address@hidden smallexample
+
address@hidden
+However, the names of the archive members will be exactly what they were
+on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
+They will not appear to be related by file name to the original
+directories where those files were located.
+
+Note that @option{--directory} options are interpreted consecutively. If
address@hidden specifies a relative file name, it is interpreted
+relative to the then current directory, which might not be the same as
+the original current working directory of @command{tar}, due to a previous
address@hidden option.
+
+When using @option{--files-from} (@pxref{files}), you can put various
address@hidden options (including @option{-C}) in the file list. Notice,
+however, that in this case the option and its argument may not be
+separated by whitespace. If you use short option, its argument must
+either follow the option letter immediately, without any intervening
+whitespace, or occupy the next line. Otherwise, if you use long
+option, separate its argument by an equal sign.
+
+For instance, the file list for the above example will be:
+
address@hidden
address@hidden
+-C
+/etc
+passwd
+hosts
+-C
+/lib
+libc.a
address@hidden group
address@hidden smallexample
+
address@hidden
+To use it, you would invoke @command{tar} as follows:
+
address@hidden
+$ @kbd{tar -c -f foo.tar --files-from list}
address@hidden smallexample
+
+Notice also that you can only use the short option variant in the file
+list, i.e., always use @option{-C}, not @option{--directory}.
+
+The interpretation of @option{--directory} is disabled by
address@hidden option.
+
address@hidden absolute
address@hidden Absolute File Names
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @option
address@hidden absolute-names
address@hidden --absolute-names
address@hidden -P
+Do not strip leading slashes from file names, and permit file names
+containing a @file{..} file name component.
address@hidden table
+
+By default, @acronym{GNU} @command{tar} drops a leading @samp{/} on
+input or output, and complains about file names containing a @file{..}
+component. This option turns off this behavior.
+
+When @command{tar} extracts archive members from an archive, it strips any
+leading slashes (@samp{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
address@hidden/etc/passwd}, @command{tar} will extract it as if the name were
+really @file{etc/passwd}.
+
+File names containing @file{..} can cause problems when extracting, so
address@hidden normally warns you about such files when creating an
+archive, and rejects attempts to extracts such files.
+
+Other @command{tar} programs do not do this. As a result, if you
+create an archive whose member names start with a slash, they will be
+difficult for other people with a address@hidden @command{tar}
+program to use. Therefore, @acronym{GNU} @command{tar} also strips
+leading slashes from member names when putting members into the
+archive. For example, if you ask @command{tar} to add the file
address@hidden/bin/ls} to an archive, it will do so, but the member name will
+be @file{bin/address@hidden side effect of this is that when
address@hidden is used with @option{--verbose} the resulting output
+is not, generally speaking, the same as the one you'd get running
address@hidden --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.}
+
+If you use the @option{--absolute-names} (@option{-P}) option,
address@hidden will do none of these transformations.
+
+To archive or extract files relative to the root directory, specify
+the @option{--absolute-names} (@option{-P}) option.
+
+Normally, @command{tar} acts on files relative to the working
+directory---ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+When you specify @option{--absolute-names} (@option{-P}),
address@hidden stores file names including all superior directory
+names, and preserves leading slashes. If you only invoked
address@hidden from the root directory you would never need the
address@hidden option, but using this option
+may be more convenient than switching to root.
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden --absolute-names
+Preserves full file names (including superior directory names) when
+archiving files. Preserves leading slash when extracting files.
+
address@hidden table
+
address@hidden
address@hidden
+
+
address@hidden prints out a message about removing the @samp{/} from
+file names. This message appears once per @acronym{GNU} @command{tar}
+invocation. It represents something which ought to be told; ignoring
+what it means can cause very serious surprises, later.
+
+Some people, nevertheless, do not want to see this message. Wanting to
+play really dangerously, one may of course redirect @command{tar} standard
+error to the sink. For example, under @command{sh}:
+
address@hidden
+$ @kbd{tar -c -f archive.tar /home 2> /dev/null}
address@hidden smallexample
+
address@hidden
+Another solution, both nicer and simpler, would be to change to
+the @file{/} directory first, and then avoid absolute notation.
+For example:
+
address@hidden
+$ @kbd{(cd / && tar -c -f archive.tar home)}
+# @i{or}:
+$ @kbd{tar -c -f archive.tar -C / home}
address@hidden smallexample
+
address@hidden GNU date syntax documentation
+
address@hidden Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
2002,
address@hidden 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+
address@hidden Permission is granted to copy, distribute and/or modify this
document
address@hidden under the terms of the GNU Free Documentation License, Version
1.1 or
address@hidden any later version published by the Free Software Foundation;
with no
address@hidden Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover
address@hidden Texts. A copy of the license is included in the ``GNU Free
address@hidden Documentation License'' file as part of this distribution.
+
address@hidden Date input formats
address@hidden Date input formats
+
address@hidden date input formats
address@hidden get_date
+
+First, a quote:
+
address@hidden
+Our units of temporal measurement, from seconds on up to months, are so
+complicated, asymmetrical and disjunctive so as to make coherent mental
+reckoning in time all but impossible. Indeed, had some tyrannical god
+contrived to enslave our minds to time, to make it all but impossible
+for us to escape subjection to sodden routines and unpleasant surprises,
+he could hardly have done better than handing down our present system.
+It is like a set of trapezoidal building blocks, with no vertical or
+horizontal surfaces, like a language in which the simplest thought
+demands ornate constructions, useless particles and lengthy
+circumlocutions. Unlike the more successful patterns of language and
+science, which enable us to face experience boldly or at least
+level-headedly, our system of temporal calculation silently and
+persistently encourages our terror of time.
+
address@hidden It is as though architects had to measure length in feet, width
+in meters and height in ells; as though basic instruction manuals
+demanded a knowledge of five different languages. It is no wonder then
+that we often look into our own immediate past or future, last Tuesday
+or a week from Sunday, with feelings of helpless confusion. @dots{}
+
+--- Robert Grudin, @cite{Time and the Art of Living}.
address@hidden quotation
+
+This section describes the textual date representations that @sc{gnu}
+programs accept. These are the strings you, as a user, can supply as
+arguments to the various programs. The C interface (via the
address@hidden function) is not described here.
+
address@hidden
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
address@hidden menu
+
+
address@hidden General date syntax
address@hidden General date syntax
+
address@hidden general date syntax
+
address@hidden items in date strings
+A @dfn{date} is a string, possibly empty, containing many items
+separated by whitespace. The whitespace may be omitted when no
+ambiguity arises. The empty string means the beginning of today (i.e.,
+midnight). Order of the items is immaterial. A date string may contain
+many flavors of items:
+
address@hidden @bullet
address@hidden calendar date items
address@hidden time of day items
address@hidden time zone items
address@hidden day of the week items
address@hidden relative items
address@hidden pure numbers.
address@hidden itemize
+
address@hidden We describe each of these item types in turn, below.
+
address@hidden numbers, written-out
address@hidden ordinal numbers
address@hidden first @r{in date strings}
address@hidden next @r{in date strings}
address@hidden last @r{in date strings}
+A few ordinal numbers may be written out in words in some contexts. This is
+most useful for specifying day of the week items or relative items (see
+below). Among the most commonly used ordinal numbers, the word
address@hidden stands for @math{-1}, @samp{this} stands for 0, and
address@hidden and @samp{next} both stand for 1. Because the word
address@hidden stands for the unit of time there is no way to write the
+ordinal number 2, but for convenience @samp{third} stands for 3,
address@hidden for 4, @samp{fifth} for 5,
address@hidden for 6, @samp{seventh} for 7, @samp{eighth} for 8,
address@hidden for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
address@hidden for 12.
+
address@hidden months, written-out
+When a month is written this way, it is still considered to be written
+numerically, instead of being ``spelled in full''; this changes the
+allowed strings.
+
address@hidden language, in dates
+In the current implementation, only English is supported for words and
+abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
address@hidden, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
+
address@hidden language, in dates
address@hidden time zone item
+The output of the @command{date} command
+is not always acceptable as a date string,
+not only because of the language problem, but also because there is no
+standard meaning for time zone items like @samp{IST}. When using
address@hidden to generate a date string intended to be parsed later,
+specify a date format that is independent of language and that does not
+use time zone items other than @samp{UTC} and @samp{Z}. Here are some
+ways to do this:
+
address@hidden
+$ LC_ALL=C TZ=UTC0 date
+Mon Mar 1 00:21:42 UTC 2004
+$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+2004-03-01 00:21:42Z
+$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
+2004-02-29 16:21:42,692722128-0800
+$ date --rfc-2822 # a GNU extension
+Sun, 29 Feb 2004 16:21:42 -0800
+$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
+2004-02-29 16:21:42 -0800
+$ date +'@@%s.%N' # %s and %N are GNU extensions.
+@@1078100502.692722128
address@hidden example
+
address@hidden case, ignored in dates
address@hidden comments, in dates
+Alphabetic case is completely ignored in dates. Comments may be introduced
+between round parentheses, as long as included parentheses are properly
+nested. Hyphens not followed by a digit are currently ignored. Leading
+zeros on numbers are ignored.
+
+Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
+rejected. In the typical case of a host that does not support leap
+seconds, a time like @samp{23:59:60} is rejected even if it
+corresponds to a valid leap second.
+
+
address@hidden Calendar date items
address@hidden Calendar date items
+
address@hidden calendar date item
+
+A @dfn{calendar date item} specifies a day of the year. It is
+specified differently, depending on whether the month is specified
+numerically or literally. All these strings specify the same calendar date:
+
address@hidden
+1972-09-24 # @sc{iso} 8601.
+72-9-24 # Assume 19xx for 69 through 99,
+ # 20xx for 00 through 68.
+72-09-24 # Leading zeros are ignored.
+9/24/72 # Common U.S. writing.
+24 September 1972
+24 Sept 72 # September has a special abbreviation.
+24 Sep 72 # Three-letter abbreviations always allowed.
+Sep 24, 1972
+24-sep-72
+24sep72
address@hidden example
+
+The year can also be omitted. In this case, the last specified year is
+used, or the current year if none. For example:
+
address@hidden
+9/24
+sep 24
address@hidden example
+
+Here are the rules.
+
address@hidden @sc{iso} 8601 date format
address@hidden date format, @sc{iso} 8601
+For numeric months, the @sc{iso} 8601 format
address@hidden@address@hidden@var{day}} is allowed, where @var{year} is
+any positive number, @var{month} is a number between 01 and 12, and
address@hidden is a number between 01 and 31. A leading zero must be present
+if a number is less than ten. If @var{year} is 68 or smaller, then 2000
+is added to it; otherwise, if @var{year} is less than 100,
+then 1900 is added to it. The construct
address@hidden@var{month}/@var{day}/@var{year}}, popular in the United States,
+is accepted. Also @address@hidden/@var{day}}, omitting the year.
+
address@hidden month names in date strings
address@hidden abbreviations for months
+Literal months may be spelled out in full: @samp{January},
address@hidden, @samp{March}, @samp{April}, @samp{May}, @samp{June},
address@hidden, @samp{August}, @samp{September}, @samp{October},
address@hidden or @samp{December}. Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write @samp{Sept} instead of @samp{September}.
+
+When months are written literally, the calendar date may be given as any
+of the following:
+
address@hidden
address@hidden @var{month} @var{year}
address@hidden @var{month}
address@hidden @var{day} @var{year}
address@hidden@address@hidden
address@hidden example
+
+Or, omitting the year:
+
address@hidden
address@hidden @var{day}
address@hidden example
+
+
address@hidden Time of day items
address@hidden Time of day items
+
address@hidden time of day item
+
+A @dfn{time of day item} in date strings specifies the time on a given
+day. Here are some examples, all of which represent the same time:
+
address@hidden
+20:02:00.000000
+20:02
+8:02pm
+20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
address@hidden example
+
+More generally, the time of day may be given as
address@hidden@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
+a number between 0 and 23, @var{minute} is a number between 0 and
+59, and @var{second} is a number between 0 and 59 possibly followed by
address@hidden or @samp{,} and a fraction containing one or more digits.
+Alternatively,
address@hidden:@var{second}} can be omitted, in which case it is taken to
+be zero. On the rare hosts that support leap seconds, @var{second}
+may be 60.
+
address@hidden am @r{in date strings}
address@hidden pm @r{in date strings}
address@hidden midnight @r{in date strings}
address@hidden noon @r{in date strings}
+If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
+or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
address@hidden:@var{minute}} may be omitted (taken to be zero). @samp{am}
+indicates the first half of the day, @samp{pm} indicates the second
+half of the day. In this notation, 12 is the predecessor of 1:
+midnight is @samp{12am} while noon is @samp{12pm}.
+(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
+as opposed to the old tradition derived from Latin
+which uses @samp{12m} for noon and @samp{12pm} for midnight.)
+
address@hidden time zone correction
address@hidden minutes, time zone correction by
+The time may alternatively be followed by a time zone correction,
+expressed as @address@hidden@address@hidden, where @var{s} is @samp{+}
+or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
+of zone minutes. You can also separate @var{hh} from @var{mm} with a colon.
+When a time zone correction is given this way, it
+forces interpretation of the time relative to
+Coordinated Universal Time (@sc{utc}), overriding any previous
+specification for the time zone or the local time zone. For example,
address@hidden and @samp{+05:30} both stand for the time zone 5.5 hours
+ahead of @sc{utc} (e.g., India). The @var{minute}
+part of the time of day may not be elided when a time zone correction
+is used. This is the best way to specify a time zone correction by
+fractional parts of an hour.
+
+Either @samp{am}/@samp{pm} or a time zone correction may be specified,
+but not both.
+
+
address@hidden Time zone items
address@hidden Time zone items
+
address@hidden time zone item
+
+A @dfn{time zone item} specifies an international time zone, indicated
+by a small set of letters, e.g., @samp{UTC} or @samp{Z}
+for Coordinated Universal
+Time. Any included periods are ignored. By following a
+non-daylight-saving time zone by the string @samp{DST} in a separate
+word (that is, separated by some white space), the corresponding
+daylight saving time zone may be specified.
+Alternatively, a non-daylight-saving time zone can be followed by a
+time zone correction, to add the two values. This is normally done
+only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
address@hidden:30}.
+
+Time zone items other than @samp{UTC} and @samp{Z}
+are obsolescent and are not recommended, because they
+are ambiguous; for example, @samp{EST} has a different meaning in
+Australia than in the United States. Instead, it's better to use
+unambiguous numeric time zone corrections like @samp{-0500}, as
+described in the previous section.
+
+If neither a time zone item nor a time zone correction is supplied,
+time stamps are interpreted using the rules of the default time zone
+(@pxref{Specifying time zone rules}).
+
+
address@hidden Day of week items
address@hidden Day of week items
+
address@hidden day of week item
+
+The explicit mention of a day of the week will forward the date
+(only if necessary) to reach that day of the week in the future.
+
+Days of the week may be spelled out in full: @samp{Sunday},
address@hidden, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
address@hidden or @samp{Saturday}. Days may be abbreviated to their
+first three letters, optionally followed by a period. The special
+abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
address@hidden and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
+also allowed.
+
address@hidden next @var{day}
address@hidden last @var{day}
+A number may precede a day of the week item to move forward
+supplementary weeks. It is best used in expression like @samp{third
+monday}. In this context, @samp{last @var{day}} or @samp{next
address@hidden is also acceptable; they move one week before or after
+the day that @var{day} by itself would represent.
+
+A comma following a day of the week item is ignored.
+
+
address@hidden Relative items in date strings
address@hidden Relative items in date strings
+
address@hidden relative items in date strings
address@hidden displacement of dates
+
address@hidden items} adjust a date (or the current date if none) forward
+or backward. The effects of relative items accumulate. Here are some
+examples:
+
address@hidden
+1 year
+1 year ago
+3 years
+2 days
address@hidden example
+
address@hidden year @r{in date strings}
address@hidden month @r{in date strings}
address@hidden fortnight @r{in date strings}
address@hidden week @r{in date strings}
address@hidden day @r{in date strings}
address@hidden hour @r{in date strings}
address@hidden minute @r{in date strings}
+The unit of time displacement may be selected by the string @samp{year}
+or @samp{month} for moving by whole years or months. These are fuzzy
+units, as years and months are not all of equal duration. More precise
+units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
+days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
address@hidden or @samp{min} worth 60 seconds, and @samp{second} or
address@hidden worth one second. An @samp{s} suffix on these units is
+accepted and ignored.
+
address@hidden ago @r{in date strings}
+The unit of time may be preceded by a multiplier, given as an optionally
+signed number. Unsigned numbers are taken as positively signed. No
+number at all implies 1 for a multiplier. Following a relative item by
+the string @samp{ago} is equivalent to preceding the unit by a
+multiplier with value @math{-1}.
+
address@hidden day @r{in date strings}
address@hidden tomorrow @r{in date strings}
address@hidden yesterday @r{in date strings}
+The string @samp{tomorrow} is worth one day in the future (equivalent
+to @samp{day}), the string @samp{yesterday} is worth
+one day in the past (equivalent to @samp{day ago}).
+
address@hidden now @r{in date strings}
address@hidden today @r{in date strings}
address@hidden this @r{in date strings}
+The strings @samp{now} or @samp{today} are relative items corresponding
+to zero-valued time displacement, these strings come from the fact
+a zero-valued time displacement represents the current time when not
+otherwise changed by previous items. They may be used to stress other
+items, like in @samp{12:00 today}. The string @samp{this} also has
+the meaning of a zero-valued time displacement, but is preferred in
+date strings like @samp{this thursday}.
+
+When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time,
+the resulting date and time are adjusted accordingly.
+
+The fuzz in units can cause problems with relative items. For
+example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
+because 2003-06-31 is an invalid date. To determine the previous
+month more reliably, you can ask for the month before the 15th of the
+current month. For example:
+
address@hidden
+$ date -R
+Thu, 31 Jul 2003 13:02:39 -0700
+$ date --date='-1 month' +'Last month was %B?'
+Last month was July?
+$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+Last month was June!
address@hidden example
+
+Also, take care when manipulating dates around clock changes such as
+daylight saving leaps. In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the @env{TZ} environment variable to
address@hidden before embarking on calendrical calculations.
+
address@hidden Pure numbers in date strings
address@hidden Pure numbers in date strings
+
address@hidden pure numbers in date strings
+
+The precise interpretation of a pure decimal number depends
+on the context in the date string.
+
+If the decimal number is of the form @address@hidden@var{dd} and no
+other calendar date item (@pxref{Calendar date items}) appears before it
+in the date string, then @var{yyyy} is read as the year, @var{mm} as the
+month number and @var{dd} as the day of the month, for the specified
+calendar date.
+
+If the decimal number is of the form @address@hidden and no other time
+of day item appears before it in the date string, then @var{hh} is read
+as the hour of the day and @var{mm} as the minute of the hour, for the
+specified time of day. @var{mm} can also be omitted.
+
+If both a calendar date and a time of day appear to the left of a number
+in the date string, but no relative item, then the number overrides the
+year.
+
+
address@hidden Seconds since the Epoch
address@hidden Seconds since the Epoch
+
+If you precede a number with @samp{@@}, it represents an internal time
+stamp as a count of seconds. The number can contain an internal
+decimal point (either @samp{.} or @samp{,}); any excess precision not
+supported by the internal representation is truncated toward minus
+infinity. Such a number cannot be combined with any other date
+item, as it specifies a complete time stamp.
+
address@hidden beginning of time, for @acronym{POSIX}
address@hidden epoch, for @acronym{POSIX}
+Internally, computer times are represented as a count of seconds since
+an epoch---a well-defined point of time. On @acronym{GNU} and
address@hidden systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
address@hidden@@0} represents this time, @samp{@@1} represents 1970-01-01
+00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
address@hidden systems support such times as an extension
+to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
+represents 1969-12-31 23:59:59 @sc{utc}.
+
+Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
+of seconds with nanosecond subcounts, and can represent all the times
+in the known lifetime of the universe to a resolution of 1 nanosecond.
+
+On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts @samp{@@915148799} represents 1998-12-31
+23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
address@hidden, and there is no way to represent the intervening leap second
+1998-12-31 23:59:60 @sc{utc}.
+
address@hidden Specifying time zone rules
address@hidden Specifying time zone rules
+
address@hidden TZ
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the @env{TZ} environment
+variable, or by a system default if @env{TZ} is not set. To specify a
+different set of default time zone rules that apply just to one date,
+start the date with a string of the form @samp{TZ="@var{rule}"}. The
+two quote characters (@samp{"}) must be present in the date, and any
+quotes or backslashes within @var{rule} must be escaped by a
+backslash.
+
+For example, with the @acronym{GNU} @command{date} command you can
+answer the question ``What time is it in New York when a Paris clock
+shows 6:30am on October 31, 2004?'' by using a date beginning with
address@hidden"Europe/Paris"} as shown in the following shell transcript:
+
address@hidden
+$ export TZ="America/New_York"
+$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+Sun Oct 31 01:30:00 EDT 2004
address@hidden example
+
+In this example, the @option{--date} operand begins with its own
address@hidden setting, so the rest of that operand is processed according
+to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
+06:30} as if it were in Paris. However, since the output of the
address@hidden command is processed according to the overall time zone
+rules, it uses New York time. (Paris was normally six hours ahead of
+New York in 2004, but this example refers to a brief Halloween period
+when the gap was five hours.)
+
+A @env{TZ} value is a rule that typically names a location in the
address@hidden://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
+A recent catalog of location names appears in the
address@hidden://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
+Gateway}. A few address@hidden hosts require a colon before a
+location name in a @env{TZ} setting, e.g.,
address@hidden":America/New_York"}.
+
+The @samp{tz} database includes a wide variety of locations ranging
+from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
+if you are at sea and have your own private time zone, or if you are
+using a address@hidden host that does not support the @samp{tz}
+database, you may need to use a @acronym{POSIX} rule instead. Simple
address@hidden rules like @samp{UTC0} specify a time zone without
+daylight saving time; other rules can specify simple daylight saving
+regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
+libc, The GNU C Library}.
+
address@hidden Authors of get_date
address@hidden Authors of @code{get_date}
+
address@hidden authors of @code{get_date}
+
address@hidden Bellovin, Steven M.
address@hidden Salz, Rich
address@hidden Berets, Jim
address@hidden MacKenzie, David
address@hidden Meyering, Jim
address@hidden Eggert, Paul
address@hidden was originally implemented by Steven M. Bellovin
+(@email{smb@@research.att.com}) while at the University of North Carolina
+at Chapel Hill. The code was later tweaked by a couple of people on
+Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
+and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
+revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
+Paul Eggert and others.
+
address@hidden Pinard, F.
address@hidden Berry, K.
+This chapter was originally produced by Fran@,{c}ois Pinard
+(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
+and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
+
address@hidden Formats
address@hidden Controlling the Archive Format
+
address@hidden Tar archive formats
+Due to historical reasons, there are several formats of tar archives.
+All of them are based on the same principles, but have some subtle
+differences that often make them incompatible with each other.
+
+GNU tar is able to create and handle archives in a variety of formats.
+The most frequently used formats are (in alphabetical order):
+
address@hidden @asis
address@hidden gnu
+Format used by @acronym{GNU} @command{tar} versions up to 1.13.25. This
format derived
+from an early @acronym{POSIX} standard, adding some improvements such as
+sparse file handling and incremental archives. Unfortunately these
+features were implemented in a way incompatible with other archive
+formats.
+
+Archives in @samp{gnu} format are able to hold pathnames of unlimited
+length.
+
address@hidden oldgnu
+Format used by @acronym{GNU} @command{tar} of versions prior to 1.12.
+
address@hidden v7
+Archive format, compatible with the V7 implementation of tar. This
+format imposes a number of limitations. The most important of them
+are:
+
address@hidden
address@hidden The maximum length of a file name is limited to 99 characters.
address@hidden The maximum length of a symbolic link is limited to 99
characters.
address@hidden It is impossible to store special files (block and character
+devices, fifos etc.)
address@hidden Maximum value of user or group ID is limited to 2097151 (7777777
+octal)
address@hidden V7 archives do not contain symbolic ownership information (user
+and group name of the file owner).
address@hidden enumerate
+
+This format has traditionally been used by Automake when producing
+Makefiles. This practice will change in the future, in the meantime,
+however this means that projects containing filenames more than 99
+characters long will not be able to use @acronym{GNU} @command{tar} 1.15.92 and
+Automake prior to 1.9.
+
address@hidden ustar
+Archive format defined by @acronym{POSIX.1-1988} specification. It stores
+symbolic ownership information. It is also able to store
+special files. However, it imposes several restrictions as well:
+
address@hidden
address@hidden The maximum length of a file name is limited to 256 characters,
+provided that the filename can be split at directory separator in
+two parts, first of them being at most 155 bytes long. So, in most
+cases the maximum file name length will be shorter than 256
+characters.
address@hidden The maximum length of a symbolic link name is limited to
+100 characters.
address@hidden Maximum size of a file the archive is able to accomodate
+is 8GB
address@hidden Maximum value of UID/GID is 2097151.
address@hidden Maximum number of bits in device major and minor numbers is 21.
address@hidden enumerate
+
address@hidden star
+Format used by J@"org Schilling @command{star}
+implementation. @acronym{GNU} @command{tar} is able to read @samp{star}
archives but
+currently does not produce them.
+
address@hidden posix
+Archive format defined by @acronym{POSIX.1-2001} specification. This is the
+most flexible and feature-rich format. It does not impose any
+restrictions on file sizes or filename lengths. This format is quite
+recent, so not all tar implementations are able to handle it properly.
+However, this format is designed in such a way that any tar
+implementation able to read @samp{ustar} archives will be able to read
+most @samp{posix} archives as well, with the only exception that any
+additional information (such as long file names etc.) will in such
+case be extracted as plain text files along with the files it refers to.
+
+This archive format will be the default format for future versions
+of @acronym{GNU} @command{tar}.
+
address@hidden table
+
+The following table summarizes the limitations of each of these
+formats:
+
address@hidden @columnfractions .10 .20 .20 .20 .20
address@hidden Format @tab UID @tab File Size @tab Path Name @tab Devn
address@hidden gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
address@hidden oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
address@hidden v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
address@hidden ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
address@hidden posix @tab Unlimited @tab Unlimited @tab Unlimited @tab
Unlimited
address@hidden multitable
+
+The default format for @acronym{GNU} @command{tar} is defined at compilation
+time. You may check it by running @command{tar --help}, and examining
+the last lines of its output. Usually, @acronym{GNU} @command{tar} is
configured
+to create archives in @samp{gnu} format, however, future version will
+switch to @samp{posix}.
+
address@hidden
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making @command{tar} Archives More Portable
+* cpio:: Comparison of @command{tar} and @command{cpio}
address@hidden menu
+
address@hidden Compression
address@hidden Using Less Space through Compression
+
address@hidden
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
address@hidden menu
+
address@hidden gzip
address@hidden Creating and Reading Compressed Archives
address@hidden Compressed archives
address@hidden Storing archives in compressed format
+
address@hidden @command{tar} is able to create and read compressed archives.
It supports
address@hidden and @command{bzip2} compression programs. For backward
+compatibilty, 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 less
+effective than @command{gzip} and @command{bzip2}.
+
+Creating a compressed archive is simple: you just specify a
address@hidden 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, and
address@hidden (@option{--compress}) to use @command{compress} program.
+For example:
+
address@hidden
+$ @kbd{tar cfz archive.tar.gz .}
address@hidden smallexample
+
+Reading compressed archive is even simpler: you don't need to specify
+any additional options as @acronym{GNU} @command{tar} recognizes its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+
address@hidden
+# List the compressed archive
+$ @kbd{tar tf archive.tar.gz}
+# Extract the compressed archive
+$ @kbd{tar xf archive.tar.gz}
address@hidden smallexample
+
+The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case @acronym{GNU}
@command{tar}
+will indicate which option you should use. For example:
+
address@hidden
+$ @kbd{cat archive.tar.gz | tar tf -}
+tar: Archive is compressed. Use -z option
+tar: Error is not recoverable: exiting now
address@hidden smallexample
+
+If you see such diagnostics, just add the suggested option to the
+invocation of @acronym{GNU} @command{tar}:
+
address@hidden
+$ @kbd{cat archive.tar.gz | tar tfz -}
address@hidden smallexample
+
+Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e., you cannot update (@option{--update} (@option{-u})) them or
delete
+(@option{--delete}) members from them. Likewise, you cannot append
+another @command{tar} archive to a compressed archive using
address@hidden (@option{-r})). Secondly, multi-volume archives cannot be
+compressed.
+
+The following table summarizes compression options used by @acronym{GNU}
@command{tar}.
+
address@hidden @option
address@hidden gzip
address@hidden ungzip
address@hidden -z
address@hidden --gzip
address@hidden --ungzip
+Filter the archive through @command{gzip}.
+
+You can use @option{--gzip} and @option{--gunzip} on physical devices
+(tape drives, etc.) and remote files as well as on normal files; data
+to or from such devices or remote files is reblocked by another copy
+of the @command{tar} program to enforce the specified (or default) record
+size. The default compression parameters are used; if you need to
+override them, set @env{GZIP} environment variable, e.g.:
+
address@hidden
+$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
address@hidden smallexample
+
address@hidden
+Another way would be to avoid the @option{--gzip} (@option{--gunzip},
@option{--ungzip}, @option{-z}) option and run
address@hidden explicitly:
+
address@hidden
+$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
address@hidden smallexample
+
address@hidden corrupted archives
+About corrupted compressed archives: @command{gzip}'ed files have no
+redundancy, for maximum compression. The adaptive nature of the
+compression scheme means that the compression tables are implicitly
+spread all over the archive. If you lose a few blocks, the dynamic
+construction of the compression tables becomes unsynchronized, and there
+is little chance that you could recover later in the archive.
+
+There are pending suggestions for having a per-volume or per-file
+compression in @acronym{GNU} @command{tar}. This would allow for viewing the
+contents without decompression, and for resynchronizing decompression at
+every volume or file, in case of corrupted archives. Doing so, we might
+lose some compressibility. But this would have make recovering easier.
+So, there are pros and cons. We'll see!
+
address@hidden bzip2
address@hidden -j
address@hidden --bzip2
+Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
+
address@hidden compress
address@hidden uncompress
address@hidden -Z
address@hidden --compress
address@hidden --uncompress
+Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
+
+The @acronym{GNU} Project recommends you not use
address@hidden, because there is a patent covering the algorithm it
+uses. You could be sued for patent infringement merely by running
address@hidden
+
address@hidden use-compress-program
address@hidden address@hidden
+Use external compression program @var{prog}. Use this option if you
+have a compression program that @acronym{GNU} @command{tar} does not support.
There
+are two requirements to which @var{prog} should comply:
+
+First, when called without options, it should read data from standard
+input, compress it and output it on standard output.
+
+Secondly, if called with @option{-d} argument, it should do exactly
+the opposite, i.e., read the compressed data from the standard input
+and produce uncompressed data on the standard output.
address@hidden table
+
address@hidden gpg, using with tar
address@hidden gnupg, using with tar
address@hidden Using encrypted archives
+The @option{--use-compress-program} option, in particular, lets you
+implement your own filters, not necessarily dealing with
+compression/decomression. For example, suppose you wish to implement
+PGP encryption on top of compression, using @command{gpg} (@pxref{Top,
+gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard
+Manual}). The following script does that:
+
address@hidden
address@hidden
+#! /bin/sh
+case $1 in
+-d) gpg --decrypt - | gzip -d -c;;
+'') gzip -c | gpg -s ;;
+*) echo "Unknown option $1">&2; exit 1;;
+esac
address@hidden group
address@hidden smallexample
+
+Suppose you name it @file{gpgz} and save it somewhere in your
address@hidden Then the following command will create a commpressed
+archive signed with your private key:
+
address@hidden
+$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
address@hidden smallexample
+
address@hidden
+Likewise, the following command will list its contents:
+
address@hidden
+$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
address@hidden smallexample
+
+
address@hidden sparse
address@hidden Archiving Sparse Files
address@hidden Sparse Files
+
+Files in the file system occasionally have @dfn{holes}. A @dfn{hole}
+in a file is a section of the file's contents which was never written.
+The contents of a hole reads as all zeros. On many operating systems,
+actual disk storage is not allocated for holes, but they are counted
+in the length of the file. If you archive such a file, @command{tar}
+could create an archive longer than the original. To have @command{tar}
+attempt to recognize the holes in a file, use @option{--sparse}
+(@option{-S}). When you use this option, then, for any file using
+less disk space than would be expected from its length, @command{tar}
+searches the file for consecutive stretches of zeros. It then records
+in the archive for the file where the consecutive stretches of zeros
+are, and only archives the ``real contents'' of the file. On
+extraction (using @option{--sparse} is not needed on extraction) any
+such files have holes created wherever the continuous stretches of zeros
+were found. Thus, if you use @option{--sparse}, @command{tar} archives
+won't take more space than the original.
+
address@hidden @option
address@hidden sparse
address@hidden -S
address@hidden --sparse
+This option istructs @command{tar} to test each file for sparseness
+before attempting to archive it. If the file is found to be sparse it
+is treated specially, thus allowing to decrease the amount of space
+used by its image in the archive.
+
+This option is meaningful only when creating or updating archives. It
+has no effect on extraction.
address@hidden table
+
+Consider using @option{--sparse} when performing file system backups,
+to avoid archiving the expanded forms of files stored sparsely in the
+system.
+
+Even if your system has no sparse files currently, some may be
+created in the future. If you use @option{--sparse} while making file
+system backups as a matter of course, you can be assured the archive
+will never take more space on the media than the files take on disk
+(otherwise, archiving a disk filled with sparse files might take
+hundreds of tapes). @xref{Incremental Dumps}.
+
+However, be aware that @option{--sparse} option presents a serious
+drawback. Namely, in order to determine if the file is sparse
address@hidden has to read it before trying to archive it, so in total
+the file is read @strong{twice}. So, always bear in mind that the
+time needed to process all files with this option is roughly twice
+the time needed to archive them without it.
address@hidden
address@hidden
+
+
address@hidden sparse formats, defined
+When using @samp{POSIX} archive format, @acronym{GNU} @command{tar} is able to
store
+sparse files using in three distinct ways, called @dfn{sparse
+formats}. A sparse format is identified by its @dfn{number},
+consisting, as usual of two decimal numbers, delimited by a dot. By
+default, format @samp{1.0} is used. If, for some reason, you wish to
+use an earlier format, you can select it using
address@hidden option.
+
address@hidden @option
address@hidden sparse-version
address@hidden address@hidden
+
+Select the format to store sparse files in. Valid @var{version} values
+are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats},
+for a detailed description of each format.
address@hidden table
+
+Using @option{--sparse-format} option implies @option{--sparse}.
+
address@hidden Attributes
address@hidden Handling File Attributes
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+When @command{tar} reads files, it updates their access times. To
+avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either
+reset the access time retroactively or avoid changing it in the first
+place.
+
+Handling of file attributes
+
address@hidden @option
address@hidden atime-preserve
address@hidden --atime-preserve
address@hidden --atime-preserve=replace
address@hidden --atime-preserve=system
+Preserve the access times of files that are read. This works only for
+files that you own, unless you have superuser privileges.
+
address@hidden works on most systems, but it also
+restores the data modification time and updates the status change
+time. Hence it doesn't interact with incremental dumps nicely
+(@pxref{Incremental Dumps}), and it can set access or data modification times
+incorrectly if other programs access the file while @command{tar} is
+running.
+
address@hidden avoids changing the access time in
+the first place, if the operating system supports this.
+Unfortunately, this may or may not work on any given operating system
+or file system. If @command{tar} knows for sure it won't work, it
+complains right away.
+
+Currently @option{--atime-preserve} with no operand defaults to
address@hidden, but this is intended to change to
address@hidden when the latter is better-supported.
+
address@hidden touch
address@hidden -m
address@hidden --touch
+Do not extract data modification time.
+
+When this option is used, @command{tar} leaves the data modification times
+of the files it extracts as the times when the files were extracted,
+instead of setting it to the times recorded in the archive.
+
+This option is meaningless with @option{--list} (@option{-t}).
+
address@hidden same-owner
address@hidden --same-owner
+Create extracted files with the same ownership they have in the
+archive.
+
+This is the default behavior for the superuser,
+so this option is meaningful only for non-root users, when @command{tar}
+is executed on those systems able to give files away. This is
+considered as a security flaw by many people, at least because it
+makes quite difficult to correctly account users for the disk space
+they occupy. Also, the @code{suid} or @code{sgid} attributes of
+files are easily and silently lost when files are given away.
+
+When writing an archive, @command{tar} writes the user id and user name
+separately. If it can't find a user name (because the user id is not
+in @file{/etc/passwd}), then it does not write one. When restoring,
+it tries to look the name (if one was written) up in
address@hidden/etc/passwd}. If it fails, then it uses the user id stored in
+the archive instead.
+
address@hidden no-same-owner
address@hidden --no-same-owner
address@hidden -o
+Do not attempt to restore ownership when extracting. This is the
+default behavior for ordinary users, so this option has an effect
+only for the superuser.
+
address@hidden numeric-owner
address@hidden --numeric-owner
+The @option{--numeric-owner} option allows (ANSI) archives to be written
+without user/group name information or such information to be ignored
+when extracting. It effectively disables the generation and/or use
+of user/group name information. This option forces extraction using
+the numeric ids from the archive, ignoring the names.
+
+This is useful in certain circumstances, when restoring a backup from
+an emergency floppy with different passwd/group files for example.
+It is otherwise impossible to extract files with the right ownerships
+if the password file in use during the extraction does not match the
+one belonging to the file system(s) being extracted. This occurs,
+for example, if you are restoring your files after a major crash and
+had booted from an emergency floppy with no password file or put your
+disk into another machine to do the restore.
+
+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
+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.
+
+When making a @command{tar} file for distribution to other sites, it
+is sometimes cleaner to use a single owner for all files in the
+distribution, and nicer to specify the write permission bits of the
+files as stored in the archive independently of their actual value on
+the file system. The way to prepare a clean distribution is usually
+to have some Makefile rule creating a directory, copying all needed
+files in that directory, then setting ownership and permissions as
+wanted (there are a lot of possible schemes), and only then making a
address@hidden archive out of this directory, before cleaning
+everything out. Of course, we could add a lot of options to
address@hidden @command{tar} for fine tuning permissions and ownership.
+This is not the good way, I think. @acronym{GNU} @command{tar} is
+already crowded with options and moreover, the approach just explained
+gives you a great deal of control already.
+
address@hidden address@hidden, short description}
address@hidden address@hidden, short description}
address@hidden -p
address@hidden --same-permissions
address@hidden --preserve-permissions
+Extract all protection information.
+
+This option causes @command{tar} to set the modes (access permissions) of
+extracted files exactly as recorded in the archive. If this option
+is not used, the current @code{umask} setting limits the permissions
+on extracted files. This option is by default enabled when
address@hidden is executed by a superuser.
+
+
+This option is meaningless with @option{--list} (@option{-t}).
+
address@hidden preserve
address@hidden --preserve
+Same as both @option{--same-permissions} and @option{--same-order}.
+
+The @option{--preserve} option has no equivalent short option name.
+It is equivalent to @option{--same-permissions} plus @option{--same-order}.
+
address@hidden
address@hidden
+
+
address@hidden table
+
address@hidden Portability
address@hidden Making @command{tar} Archives More Portable
+
+Creating a @command{tar} archive on a particular system that is meant to be
+useful later on many other machines and with other versions of @command{tar}
+is more challenging than you might think. @command{tar} archive formats
+have been evolving since the first versions of Unix. Many such formats
+are around, and are not always compatible with each other. This section
+discusses a few problems, and gives some advice about making @command{tar}
+archives more portable.
+
+One golden rule is simplicity. For example, limit your @command{tar}
+archives to contain only regular files and directories, avoiding
+other kind of special files. Do not attempt to save sparse files or
+contiguous files as such. Let's discuss a few more problems, in turn.
+
address@hidden
address@hidden
+
+
address@hidden
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
address@hidden menu
+
address@hidden Portable Names
address@hidden Portable Names
+
+Use portable file and member names. A name is portable if it contains
+only ASCII letters and digits, @samp{/}, @samp{.}, @samp{_}, and
address@hidden; it cannot be empty, start with @samp{-} or @samp{//}, or
+contain @samp{/-}. Avoid deep directory nesting. For portability to
+old Unix hosts, limit your file name components to 14 characters or
+less.
+
+If you intend to have your @command{tar} archives to be read under
+MSDOS, you should not rely on case distinction for file names, and you
+might use the @acronym{GNU} @command{doschk} program for helping you
+further diagnosing illegal MSDOS names, which are even more limited
+than System V's.
+
address@hidden dereference
address@hidden Symbolic Links
address@hidden File names, using symbolic links
address@hidden Symbolic link as file name
+
address@hidden dereference
+Normally, when @command{tar} archives a symbolic link, it writes a
+block to the archive naming the target of the link. In that way, the
address@hidden archive is a faithful record of the file system contents.
address@hidden (@option{-h}) is used with @option{--create} (@option{-c}), and
causes
address@hidden to archive the files symbolic links point to, instead of
+the links themselves. When this option is used, when @command{tar}
+encounters a symbolic link, it will archive the linked-to file,
+instead of simply recording the presence of a symbolic link.
+
+The name under which the file is stored in the file system is not
+recorded in the archive. To record both the symbolic link name and
+the file name in the system, archive the file under both names. If
+all links were recorded automatically by @command{tar}, an extracted file
+might be linked to a file name that no longer exists in the file
+system.
+
+If a linked-to file is encountered again by @command{tar} while creating
+the same archive, an entire second copy of it will be stored. (This
address@hidden be considered a bug.)
+
+So, for portable archives, do not archive symbolic links as such,
+and use @option{--dereference} (@option{-h}): many systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
+
address@hidden old
address@hidden Old V7 Archives
address@hidden Format, old style
address@hidden Old style format
address@hidden Old style archives
address@hidden v7 archive format
+
+Certain old versions of @command{tar} cannot handle additional
+information recorded by newer @command{tar} programs. To create an
+archive in V7 format (not ANSI), which can be read by these old
+versions, specify the @option{--format=v7} option in
+conjunction with the @option{--create} (@option{-c}) (@command{tar} also
+accepts @option{--portability} or @option{--old-archive} for this
+option). When you specify it,
address@hidden leaves out information about directories, pipes, fifos,
+contiguous files, and device files, and specifies file ownership by
+group and user IDs instead of group and user names.
+
+When updating an archive, do not use @option{--format=v7}
+unless the archive was created using this option.
+
+In most cases, a @emph{new} format archive can be read by an @emph{old}
address@hidden program without serious trouble, so this option should
+seldom be needed. On the other hand, most modern @command{tar}s are
+able to read old format archives, so it might be safer for you to
+always use @option{--format=v7} for your distributions. Notice,
+however, that @samp{ustar} format is a better alternative, as it is
+free from many of @samp{v7}'s drawbacks.
+
address@hidden ustar
address@hidden Ustar Archive Format
+
address@hidden ustar archive format
+Archive format defined by @acronym{POSIX}.1-1988 specification is called
address@hidden Although it is more flexible than the V7 format, it
+still has many restrictions (@xref{Formats,ustar}, for the detailed
+description of @code{ustar} format). Along with V7 format,
address@hidden format is a good choice for archives intended to be read
+with other implementations of @command{tar}.
+
+To create archive in @code{ustar} format, use @option{--format=ustar}
+option in conjunction with the @option{--create} (@option{-c}).
+
address@hidden gnu
address@hidden @acronym{GNU} and old @acronym{GNU} @command{tar} format
+
address@hidden GNU archive format
address@hidden Old GNU archive format
address@hidden @command{tar} was based on an early draft of the
address@hidden 1003.1 @code{ustar} standard. @acronym{GNU} extensions to
address@hidden, such as the support for file names longer than 100
+characters, use portions of the @command{tar} header record which were
+specified in that @acronym{POSIX} draft as unused. Subsequent changes in
address@hidden have allocated the same parts of the header record for
+other purposes. As a result, @acronym{GNU} @command{tar} format is
+incompatible with the current @acronym{POSIX} specification, and with
address@hidden programs that follow it.
+
+In the majority of cases, @command{tar} will be configured to create
+this format by default. This will change in the future releases, since
+we plan to make @samp{POSIX} format the default.
+
+To force creation a @acronym{GNU} @command{tar} archive, use option
address@hidden
+
address@hidden posix
address@hidden @acronym{GNU} @command{tar} and @acronym{POSIX} @command{tar}
+
address@hidden POSIX archive format
address@hidden PAX archive format
+Starting from version 1.14 @acronym{GNU} @command{tar} features full support
for
address@hidden archives.
+
+A @acronym{POSIX} conformant archive will be created if @command{tar}
+was given @option{--format=posix} (@option{--format=pax}) option. No
+special option is required to read and extract from a @acronym{POSIX}
+archive.
+
address@hidden
+* PAX keywords:: Controlling Extended Header Keywords.
address@hidden menu
+
address@hidden PAX keywords
address@hidden Controlling Extended Header Keywords
+
address@hidden @option
address@hidden pax-option
address@hidden address@hidden
+Handle keywords in @acronym{PAX} extended headers. This option is
+equivalent to @option{-o} option of the @command{pax} utility.
address@hidden table
+
address@hidden is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+
address@hidden @code
address@hidden address@hidden
+When used with one of archive-creation commands,
+this option instructs @command{tar} to omit from extended header records
+that it produces any keywords matching the string @var{pattern}.
+
+When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given @var{pattern} in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in @acronym{POSIX 1003.2}, 3.13
+(@pxref{wildcards}). For example:
+
address@hidden
+--pax-option delete=security.*
address@hidden smallexample
+
+would suppress security-related information.
+
address@hidden address@hidden
+
+This keyword allows user control over the name that is written into the
+ustar header blocks for the extended headers. The name is obtained
+from @var{string} after making the following substitutions:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on the translated pathname.
address@hidden %f @tab The filename of the file, equivalent to the result
+of the @command{basename} utility on the translated pathname.
address@hidden %p @tab The process ID of the @command{tar} process.
address@hidden %% @tab A @samp{%} character.
address@hidden multitable
+
+Any other @samp{%} characters in @var{string} produce undefined
+results.
+
+If no option @samp{exthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
address@hidden
+%d/PaxHeaders.%p/%f
address@hidden smallexample
+
address@hidden address@hidden
+This keyword allows user control over the name that is written into
+the ustar header blocks for global extended header records. The name
+is obtained from the contents of @var{string}, after making
+the following substitutions:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %n @tab An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
address@hidden %p @tab The process ID of the @command{tar} process.
address@hidden %% @tab A @samp{%} character.
address@hidden multitable
+
+Any other @samp{%} characters in @var{string} produce undefined results.
+
+If no option @samp{globexthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
address@hidden
+$TMPDIR/GlobalHead.%p.%n
address@hidden smallexample
+
address@hidden
+where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
+environment variable. If @var{TMPDIR} is not set, @command{tar}
+uses @samp{/tmp}.
+
address@hidden @address@hidden
+When used with one of archive-creation commands, these keyword/value pairs
+will be included at the beginning of the archive in a global extended
+header record. When used with one of archive-reading commands,
address@hidden will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+
address@hidden @var{keyword}:address@hidden
+When used with one of archive-creation commands, these keyword/value pairs
+will be included as records at the beginning of an extended header for
+each file. This is effectively equivalent to @address@hidden
+form except that it creates no global extended header records.
+
+When used with one of archive-reading commands, @command{tar} will
+behave as if these keyword/value pairs were included as records at the
+end of each extended header; thus, they will override any global or
+file-specific extended header record keywords of the same names.
+For example, in the command:
+
address@hidden
+tar --format=posix --create \
+ --file archive --pax-option gname:=user .
address@hidden smallexample
+
+the group name will be forced to a new value for all files
+stored in the archive.
address@hidden table
+
address@hidden Checksumming
address@hidden Checksumming Problems
+
+SunOS and HP-UX @command{tar} fail to accept archives created using
address@hidden @command{tar} and containing non-ASCII file names, that
+is, file names having characters with the eight bit set, because they
+use signed checksums, while @acronym{GNU} @command{tar} uses unsigned
+checksums while creating archives, as per @acronym{POSIX} standards. On
+reading, @acronym{GNU} @command{tar} computes both checksums and
+accept any. It is somewhat worrying that a lot of people may go
+around doing backup of their files using faulty (or at least
+non-standard) software, not learning about it until it's time to
+restore their missing files with an incompatible file extractor, or
+vice versa.
+
address@hidden @command{tar} compute checksums both ways, and accept
+any on read, so @acronym{GNU} tar can read Sun tapes even with their
+wrong checksums. @acronym{GNU} @command{tar} produces the standard
+checksum, however, raising incompatibilities with Sun. That is to
+say, @acronym{GNU} @command{tar} has not been modified to
address@hidden incorrect archives to be read by buggy @command{tar}'s.
+I've been told that more recent Sun @command{tar} now read standard
+archives, so maybe Sun did a similar patch, after all?
+
+The story seems to be that when Sun first imported @command{tar}
+sources on their system, they recompiled it without realizing that
+the checksums were computed differently, because of a change in
+the default signing of @code{char}'s in their compiler. So they
+started computing checksums wrongly. When they later realized their
+mistake, they merely decided to stay compatible with it, and with
+themselves afterwards. Presumably, but I do not really know, HP-UX
+has chosen that their @command{tar} archives to be compatible with Sun's.
+The current standards do not favor Sun @command{tar} format. In any
+case, it now falls on the shoulders of SunOS and HP-UX users to get
+a @command{tar} able to read the good archives they receive.
+
address@hidden Large or Negative Values
address@hidden Large or Negative Values
address@hidden large values
address@hidden future time stamps
address@hidden negative time stamps
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+The above sections suggest to use @samp{oldest possible} archive
+format if in doubt. However, sometimes it is not possible. If you
+attempt to archive a file whose metadata cannot be represented using
+required format, @acronym{GNU} @command{tar} will print error message and
ignore such a
+file. You will than have to switch to a format that is able to
+handle such values. The format summary table (@pxref{Formats}) will
+help you to do so.
+
+In particular, when trying to archive files larger than 8GB or with
+timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
+12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and
address@hidden archive formats. When considering which format to
+choose, bear in mind that the @acronym{GNU} format uses
+two's-complement base-256 notation to store values that do not fit
+into standard @acronym{ustar} range. Such archives can generally be
+read only by a @acronym{GNU} @command{tar} implementation. Moreover, they
sometimes
+cannot be correctly restored on another hosts even by @acronym{GNU}
@command{tar}. For
+example, using two's complement representation for negative time
+stamps that assumes a signed 32-bit @code{time_t} generates archives
+that are not portable to hosts with differing @code{time_t}
+representations.
+
+On the other hand, @acronym{POSIX} archives, generally speaking, can
+be extracted by any tar implementation that understands older
address@hidden format. The only exception are files larger than 8GB.
+
address@hidden
address@hidden
+
+
address@hidden Other Tars
address@hidden How to Extract GNU-Specific Data Using Other @command{tar}
Implementations
+
+In previous sections you became acquainted with various quircks
+necessary to make your archives portable. Sometimes you may need to
+extract archives containing GNU-specific members using some
+third-party @command{tar} implementation or an older version of
address@hidden @command{tar}. Of course your best bet is to have @acronym{GNU}
@command{tar} installed,
+but if it is for some reason impossible, this section will explain
+how to cope without it.
+
+When we speak about @dfn{GNU-specific} members we mean two classes of
+them: members split between the volumes of a multi-volume archive and
+sparse members. You will be able to always recover such members if
+the archive is in PAX format. In addition split members can be
+recovered from archives in old GNU format. The following subsections
+describe the required procedures in detail.
+
address@hidden
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
address@hidden menu
+
address@hidden Split Recovery
address@hidden Extracting Members Split Between Volumes
+
address@hidden Mutli-volume archives, extracting using non-GNU tars
+If a member is split between several volumes of an old GNU format archive
+most third party @command{tar} implementation will fail to extract
+it. To extract it, use @command{tarcat} program (@pxref{Tarcat}).
+This program is available from
address@hidden://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html,
@acronym{GNU} @command{tar}
+home page}. It concatenates several archive volumes into a single
+valid archive. For example, if you have three volumes named from
address@hidden to @file{vol-2.tar}, you can do the following to
+extract them using a third-party @command{tar}:
+
address@hidden
+$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -}
address@hidden smallexample
+
address@hidden Mutli-volume archives in PAX format, extracting using non-GNU
tars
+You could use this approach for many (although not all) PAX
+format archives as well. However, extracting split members from a PAX
+archive is a much easier task, because PAX volumes are constructed in
+such a way that each part of a split member is extracted as a
+different file by @command{tar} implementations that are not aware of
+GNU extensions. More specifically, the very first part retains its
+original name, and all subsequent parts are named using the pattern:
+
address@hidden
+%d/GNUFileParts.%p/%f.%n
address@hidden smallexample
+
address@hidden
+where symbols preceeded by @samp{%} are @dfn{macro characters} that
+have the following meaning:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on its full name.
address@hidden %f @tab The file name of the file, equivalent to the result
+of the @command{basename} utility on its full name.
address@hidden %p @tab The process ID of the @command{tar} process that
+created the archive.
address@hidden %n @tab Ordinal number of this particular part.
address@hidden multitable
+
+For example, if, a file @file{var/longfile} was split during archive
+creation between three volumes, and the creator @command{tar} process
+had process ID @samp{27962}, then the member names will be:
+
address@hidden
+var/longfile
+var/GNUFileParts.27962/longfile.1
+var/GNUFileParts.27962/longfile.2
address@hidden smallexample
+
+When you extract your archive using a third-party @command{tar}, these
+files will be created on your disk, and the only thing you will need
+to do to restore your file in its original form is concatenate them in
+the proper order, for example:
+
address@hidden
address@hidden
+$ @kbd{cd var}
+$ @kbd{cat GNUFileParts.27962/longfile.1 \
+ GNUFileParts.27962/longfile.2 >> longfile}
+$ rm -f GNUFileParts.27962
address@hidden group
address@hidden smallexample
+
+Notice, that if the @command{tar} implementation you use supports PAX
+format archives, it will probably emit warnings about unknown keywords
+during extraction. They will lool like this:
+
address@hidden
address@hidden
+Tar file too small
+Unknown extended header keyword 'GNU.volume.filename' ignored.
+Unknown extended header keyword 'GNU.volume.size' ignored.
+Unknown extended header keyword 'GNU.volume.offset' ignored.
address@hidden group
address@hidden smallexample
+
address@hidden
+You can safely ignore these warnings.
+
+If your @command{tar} implementation is not PAX-aware, you will get
+more warnigns and more files generated on your disk, e.g.:
+
address@hidden
address@hidden
+$ @kbd{tar xf vol-1.tar}
+var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
+normal file
+Unexpected EOF in archive
+$ @kbd{tar xf vol-2.tar}
+tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
+GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
+'x', extracted as normal file
address@hidden group
address@hidden smallexample
+
+Ignore these warnings. The @file{PaxHeaders.*} directories created
+will contain files with @dfn{extended header keywords} describing the
+extracted files. You can delete them, unless they describe sparse
+members. Read further to learn more about them.
+
address@hidden Sparse Recovery
address@hidden Extracting Sparse Members
+
address@hidden sparse files, extracting with non-GNU tars
+Any @command{tar} implementation will be able to extract sparse members from a
+PAX archive. However, the extracted files will be @dfn{condensed},
+i.e. any zero blocks will be removed from them. When we restore such
+a condensed file to its original form, by adding zero bloks (or
address@hidden) back to their original locations, we call this process
address@hidden a compressed sparse file.
+
address@hidden xsparse
+To expand a file, you will need a simple auxiliary program called
address@hidden It is available in source form from
address@hidden://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html,
@acronym{GNU} @command{tar}
+home page}.
+
address@hidden sparse files v.1.0, extracting with non-GNU tars
+Let's begin with archive members in @dfn{sparse format
+version address@hidden@xref{PAX 1}.}, which are the easiest to expand.
+The condensed file will contain both file map and file data, so no
+additional data will be needed to restore it. If the original file
+name was @address@hidden/@var{name}}, then the condensed file will be
+named @address@hidden/@/address@hidden/@/@var{name}}, where
address@hidden is a decimal address@hidden speaking, @var{n} is a
address@hidden ID} of the @command{tar} process which created the
+archive (@pxref{PAX keywords}).}.
+
+To expand a version 1.0 file, run @command{xsparse} as follows:
+
address@hidden
+$ @kbd{xsparse @file{cond-file}}
address@hidden smallexample
+
address@hidden
+where @file{cond-file} is the name of the condensed file. The utility
+will deduce the name for the resulting expanded file using the
+following algorithm:
+
address@hidden 1
address@hidden If @file{cond-file} does not contain any directories,
address@hidden/cond-file} will be used;
+
address@hidden If @file{cond-file} has the form
address@hidden@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name}
+are simple names, with no @samp{/} characters in them, the output file
+name will be @address@hidden/@var{name}}.
+
address@hidden Otherwise, if @file{cond-file} has the form
address@hidden@var{dir}/@var{name}}, the output file name will be
address@hidden@var{name}}.
address@hidden enumerate
+
+In the unlikely case when this algorithm does not suite your needs,
+you can explicitely specify output file name as a second argument to
+the command:
+
address@hidden
+$ @kbd{xsparse @file{cond-file}}
address@hidden smallexample
+
+It is often a good idea to run @command{xsparse} in @dfn{dry run} mode
+first. In this mode, the command does not actually expand the file,
+but verbosely lists all actions it would be taking to do so. The dry
+run mode is enabled by @option{-n} command line argument:
+
address@hidden
address@hidden
+$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Finished dry run
address@hidden group
address@hidden smallexample
+
+To actually expand the file, you would run:
+
address@hidden
+$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile}
address@hidden smallexample
+
address@hidden
+The program behaves the same way all UNIX utilities do: it will keep
+quiet unless it has simething important to tell you (e.g. an error
+condition or something). If you wish it to produce verbose output,
+similar to that from the dry run mode, give it @option{-v} option:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
+Additionally, if your @command{tar} implementation has extracted the
address@hidden headers} for this file, you can instruct @command{xstar}
+to use them in order to verify the integrity of the expanded file.
+The option @option{-x} sets the name of the extended header file to
+use. Continuing our example:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
+ /home/gray/GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.major = 1
+Found variable GNU.sparse.minor = 0
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.realsize = 217481216
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
address@hidden sparse v.0.x}
address@hidden sparse files v.0.1, extracting with non-GNU tars
address@hidden sparse files v.0.0, extracting with non-GNU tars
+An @dfn{extended header} is a special @command{tar} archive header
+that precedes an archive member and contains a set of
address@hidden, describing the member properties that cannot be
+stored in the standard @code{ustar} header. While optional for
+expanding sparse version 1.0 members, use of extended headers is
+mandatory when expanding sparse members in older sparse formats: v.0.0
+and v.0.1 (The sparse formats are described in detail in @pxref{Sparse
+Formats}). So, for this format, the question is: how to obtain
+extended headers from the archive?
+
+If you use a @command{tar} implementation that does not support PAX
+format, extended headers for each member will be extracted as a
+separate file. If we represent the member name as
address@hidden@var{dir}/@var{name}}, then the extended header file will be
+named @address@hidden/@/address@hidden/@/@var{name}}, where
address@hidden is an integer number.
+
+Things become more difficult if your @command{tar} implementation
+does support PAX headers, because in this case you will have to
+manually extract the headers. We recommend the following algorithm:
+
address@hidden 1
address@hidden
+Consult the documentation for your @command{tar} implementation for an
+option that will print @dfn{block numbers} along with the archive
+listing (analogous to @acronym{GNU} @command{tar}'s @option{-R} option). For
example,
address@hidden has @option{-block-number}.
+
address@hidden
+Obtain the verbose listing using the @samp{block number} option, and
+find the position of the sparse member in question and the member
+immediately following it. For example, running @command{star} on our
+archive we obtain:
+
address@hidden
address@hidden
+$ @kbd{star -t -v -block-number -f arc.tar}
address@hidden
+star: Unknown extended header keyword 'GNU.sparse.size' ignored.
+star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
+star: Unknown extended header keyword 'GNU.sparse.name' ignored.
+star: Unknown extended header keyword 'GNU.sparse.map' ignored.
+block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006
GNUSparseFile.28124/sparsefile
+block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
address@hidden
address@hidden group
address@hidden smallexample
+
address@hidden
+(as usual, ignore the warnings about unknown keywords.)
+
address@hidden
+Let @var{size} be the size of the sparse member, @var{Bs} be its block number
+and @var{Bn} be the block number of the next member.
+Compute:
+
address@hidden
address@hidden = @var{Bs} - @var{Bn} - @var{size}/512 - 2
address@hidden smallexample
+
address@hidden
+This number gives the size of the extended header part in tar @dfn{blocks}.
+In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2
+= 7}.
+
address@hidden
+Use @command{dd} to extract the headers:
+
address@hidden
address@hidden address@hidden address@hidden bs=512 address@hidden
address@hidden
address@hidden smallexample
+
address@hidden
+where @var{archive} is the archive name, @var{hname} is a name of the
+file to store the extended header in, @var{Bs} and @var{N} are
+computed in previous steps.
+
+In our example, this command will be
+
address@hidden
+$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7}
address@hidden smallexample
address@hidden enumerate
+
+Finally, you can expand the condensed file, using the obtained header:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.size = 217481216
+Found variable GNU.sparse.numblocks = 208
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
+Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
address@hidden cpio
address@hidden Comparison of @command{tar} and @command{cpio}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
+The @command{cpio} archive formats, like @command{tar}, do have maximum
+pathname lengths. The binary and old ASCII formats have a max path
+length of 256, and the new ASCII and CRC ASCII formats have a max
+path length of 1024. @acronym{GNU} @command{cpio} can read and write archives
+with arbitrary pathname lengths, but other @command{cpio} implementations
+may crash unexplainedly trying to read them.
+
address@hidden handles symbolic links in the form in which it comes in BSD;
address@hidden doesn't handle symbolic links in the form in which it comes
+in System V prior to SVR4, and some vendors may have added symlinks
+to their system without enhancing @command{cpio} to know about them.
+Others may have enhanced it in a way other than the way I did it
+at Sun, and which was adopted by AT&T (and which is, I think, also
+present in the @command{cpio} that Berkeley picked up from AT&T and put
+into a later BSD release---I think I gave them my changes).
+
+(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio}
+can handle @command{tar} format input, and write it on output, and it
+probably handles symbolic links. They may not have bothered doing
+anything to enhance @command{tar} as a result.)
+
address@hidden handles special files; traditional @command{tar} doesn't.
+
address@hidden comes with V7, System III, System V, and BSD source;
address@hidden comes only with System III, System V, and later BSD
+(4.3-tahoe and later).
+
address@hidden's way of handling multiple hard links to a file can handle
+file systems that support 32-bit inumbers (e.g., the BSD file system);
address@hidden way requires you to play some games (in its "binary"
+format, i-numbers are only 16 bits, and in its "portable ASCII" format,
+they're 18 bits---it would have to play games with the "file system ID"
+field of the header to make sure that the file system ID/i-number pairs
+of different files were always different), and I don't know which
address@hidden, if any, play those games. Those that don't might get
+confused and think two files are the same file when they're not, and
+make hard links between them.
+
address@hidden way of handling multiple hard links to a file places only
+one copy of the link on the tape, but the name attached to that copy
+is the @emph{only} one you can use to retrieve the file; @command{cpio}s
+way puts one copy for every link, but you can retrieve it using any
+of the names.
+
address@hidden
+What type of check sum (if any) is used, and how is this calculated.
address@hidden quotation
+
+See the attached manual pages for @command{tar} and @command{cpio} format.
address@hidden uses a checksum which is the sum of all the bytes in the
address@hidden header for a file; @command{cpio} uses no checksum.
+
address@hidden
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene,
address@hidden quotation
+
+It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no
+generally-available version of UNIX had @command{tar} at the time. I don't
+know whether any version that was generally available @emph{within AT&T}
+had @command{tar}, or, if so, whether the people within AT&T who did
address@hidden knew about it.
+
+On restore, if there is a corruption on a tape @command{tar} will stop at
+that point, while @command{cpio} will skip over it and try to restore the
+rest of the files.
+
+The main difference is just in the command syntax and header format.
+
address@hidden is a little more tape-oriented in that everything is blocked
+to start on a record boundary.
+
address@hidden
+Is there any differences between the ability to recover crashed
+archives between the two of them. (Is there any chance of recovering
+crashed archives at all.)
address@hidden quotation
+
+Theoretically it should be easier under @command{tar} since the blocking
+lets you find a header with some variation of @samp{dd address@hidden
+However, modern @command{cpio}'s and variations have an option to just
+search for the next file header after an error with a reasonable chance
+of resyncing. However, lots of tape driver software won't allow you to
+continue past a media error which should be the only reason for getting
+out of sync unless a file changed sizes while you were writing the
+archive.
+
address@hidden
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene, please tell me about this too.
address@hidden quotation
+
+Probably because it is more media efficient (by not blocking everything
+and using only the space needed for the headers where @command{tar}
+always uses 512 bytes per file header) and it knows how to archive
+special files.
+
+You might want to look at the freely available alternatives. The
+major ones are @command{afio}, @acronym{GNU} @command{tar}, and
address@hidden, each of which have their own extensions with some
+backwards compatibility.
+
+Sparse files were @command{tar}red as sparse files (which you can
+easily test, because the resulting archive gets smaller, and
address@hidden @command{cpio} can no longer read it).
+
address@hidden Media
address@hidden Tapes and Other Archive Media
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+A few special cases about tape handling warrant more detailed
+description. These special cases are discussed below.
+
+Many complexities surround the use of @command{tar} on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of @command{tar}, it contains many features making
+such manipulation easier.
+
+Archives are usually written on dismountable media---tape cartridges,
+mag tapes, or floppy disks.
+
+The amount of data a tape or disk holds depends not only on its size,
+but also on how it is formatted. A 2400 foot long reel of mag tape
+holds 40 megabytes of data when formatted at 1600 bits per inch. The
+physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
+
+Magnetic media are re-usable---once the archive on a tape is no longer
+needed, the archive can be erased and the tape or disk used over.
+Media quality does deteriorate with use, however. Most tapes or disks
+should be discarded when they begin to produce data errors. EXABYTE
+tape cartridges should be discarded when they generate an @dfn{error
+count} (number of non-usable bits) of more than 10k.
+
+Magnetic media are written and erased using magnetic fields, and
+should be protected from such fields to avoid damage to stored data.
+Sticking a floppy disk to a filing cabinet using a magnet is probably
+not a good idea.
+
address@hidden
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
address@hidden menu
+
address@hidden Device
address@hidden Device Selection and Switching
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @option
address@hidden -f address@hidden:address@hidden
address@hidden address@hidden:address@hidden
+Use archive file or device @var{file} on @var{hostname}.
address@hidden table
+
+This option is used to specify the file name of the archive @command{tar}
+works on.
+
+If the file name is @samp{-}, @command{tar} reads the archive from standard
+input (when listing or extracting), or writes it to standard output
+(when creating). If the @samp{-} file name is given when updating an
+archive, @command{tar} will read the original archive from its standard
+input, and will write the entire new archive to its standard output.
+
+If the file name contains a @samp{:}, it is interpreted as
address@hidden:file name}. If the @var{hostname} contains an @dfn{at}
+sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In
+either case, @command{tar} will invoke the command @command{rsh} (or
address@hidden) 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
address@hidden
+Naturally, the remote machine must have an executable
address@hidden/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 @address@hidden/libexec/rmt}, where @var{prefix} stands for
+your installation prefix. This location may also be overridden at
+runtime by using @address@hidden 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}
+used a default archive name (which was picked when @command{tar} was
+compiled). The default is normally set up to be the @dfn{first} tape
+drive or other transportable I/O medium on the system.
+
+Starting with version 1.11.5, @acronym{GNU} @command{tar} uses
+standard input and standard output as the default device, and I will
+not try anymore supporting automatic device detection at installation
+time. This was failing really in too many cases, it was hopeless.
+This is now completely left to the installer to override standard
+input and standard output for default device, if this seems
+preferable. Further, I think @emph{most} actual usages of
address@hidden are done with pipes or disks, not really tapes,
+cartridges or diskettes.
+
+Some users think that using standard input and output is running
+after trouble. This could lead to a nasty surprise on your screen if
+you forget to specify an output file name---especially if you are going
+through a network or terminal server capable of buffering large amounts
+of output. We had so many bug reports in that area of configuring
+default tapes automatically, and so many contradicting requests, that
+we finally consider the problem to be portably intractable. We could
+of course use something like @samp{/dev/tape} as a default, but this
+is @emph{also} running after various kind of trouble, going from hung
+processes to accidental destruction of real tapes. After having seen
+all this mess, using standard input and output as a default really
+sounds like the only clean choice left, and a very useful one too.
+
address@hidden @command{tar} reads and writes archive in records, I
+suspect this is the main reason why block devices are preferred over
+character devices. Most probably, block devices are more efficient
+too. The installer could also check for @samp{DEFTAPE} in
address@hidden<sys/mtio.h>}.
+
address@hidden @option
address@hidden address@hidden, short description}
address@hidden --force-local
+Archive file is local even if it contains a colon.
+
address@hidden rsh-command
address@hidden address@hidden
+Use remote @var{command} instead of @command{rsh}. This option exists
+so that people who use something other than the standard @command{rsh}
+(e.g., a Kerberized @command{rsh}) can access a remote device.
+
+When this command is not used, the shell command found when
+the @command{tar} program was installed is used instead. This is
+the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh},
address@hidden/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}.
+The installer may have overridden this by defining the environment
+variable @env{RSH} @emph{at installation time}.
+
address@hidden -[0-7][lmh]
+Specify drive and density.
+
address@hidden address@hidden, short description}
address@hidden -M
address@hidden --multi-volume
+Create/list/extract multi-volume archive.
+
+This option causes @command{tar} to write a @dfn{multi-volume} archive---one
+that may be larger than will fit on the medium used to hold it.
address@hidden Archives}.
+
address@hidden address@hidden, short description}
address@hidden -L @var{num}
address@hidden address@hidden
+Change tape after writing @var{num} x 1024 bytes.
+
+This option might be useful when your tape drivers do not properly
+detect end of physical tapes. By being slightly conservative on the
+maximum tape length, you might avoid the problem entirely.
+
address@hidden address@hidden, short description}
address@hidden address@hidden, short description}
address@hidden -F @var{file}
address@hidden address@hidden
address@hidden address@hidden
+Execute @file{file} at end of each tape. This implies
address@hidden (@option{-M}). @xref{info-script}, for a detailed
+description of this option.
address@hidden table
+
address@hidden Remote Tape Server
address@hidden The Remote Tape Server
+
address@hidden remote tape drive
address@hidden 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
address@hidden@var{prefix}/libexec/rmt} on any machine whose tape drive you
+want to use. @command{tar} calls @command{rmt} by running an
address@hidden or @command{remsh} to the remote machine, optionally
+using a different login name if one is supplied.
+
+A copy of the source for the remote tape server is provided. It is
+Copyright @copyright{} 1983 by the Regents of the University of
+California, but can be freely distributed. It is compiled and
+installed by default.
+
address@hidden absolute file names
+Unless you use the @option{--absolute-names} (@option{-P}) option,
address@hidden @command{tar} will not allow you to create an archive that
contains
+absolute file names (a file name beginning with @samp{/}.) If you try,
address@hidden will automatically remove the leading @samp{/} from the
+file names it stores in the archive. It will also type a warning
+message telling you what it is doing.
+
+When reading an archive that was created with a different
address@hidden program, @acronym{GNU} @command{tar} automatically
+extracts entries in the archive which have absolute file names as if
+the file names were not absolute. This is an important feature. A
+visitor here once gave a @command{tar} tape to an operator to restore;
+the operator used Sun @command{tar} instead of @acronym{GNU} @command{tar},
+and the result was that it replaced large portions of
+our @file{/bin} and friends with versions from the tape; needless to
+say, we were unhappy about having to recover the file system from
+backup tapes.
+
+For example, if the archive contained a file @file{/usr/bin/computoy},
address@hidden @command{tar} would extract the file to @file{usr/bin/computoy},
+relative to the current directory. If you want to extract the files in
+an archive to the same absolute names that they had when the archive
+was created, you should do a @samp{cd /} before extracting the files
+from the archive, or you should either use the @option{--absolute-names}
+option, or use the command @samp{tar -C / @dots{}}.
+
address@hidden Ultrix 3.1 and write failure
+Some versions of Unix (Ultrix 3.1 is known to have this problem),
+can claim that a short write near the end of a tape succeeded,
+when it actually failed. This will result in the -M option not
+working correctly. The best workaround at the moment is to use a
+significantly larger blocking factor than the default 20.
+
+In order to update an archive, @command{tar} must be able to backspace the
+archive in order to reread or rewrite a record that was just read (or
+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}.
+
+This means that the @option{--append}, @option{--concatenate}, and
address@hidden commands will not work on any other kind of file.
+Some media simply cannot be backspaced, which means these commands and
+options will never be able to work on them. These non-backspacing
+media include pipes and cartridge tape drives.
+
+Some other media can be backspaced, and @command{tar} will work on them
+once @command{tar} is modified to do so.
+
+Archives created with the @option{--multi-volume}, @option{--label}, and
address@hidden (@option{-G}) options may not be readable by other version
+of @command{tar}. In particular, restoring a file that was split over
+a volume boundary will require some careful work with @command{dd}, if
+it can be done at all. Other versions of @command{tar} may also create
+an empty file whose name is that of the volume header. Some versions
+of @command{tar} may create normal files instead of directories archived
+with the @option{--incremental} (@option{-G}) option.
+
address@hidden Common Problems and Solutions
address@hidden Some Common Problems and their Solutions
+
+
address@hidden
+errors from system:
+permission denied
+no such file or directory
+not owner
+
+errors from @command{tar}:
+directory checksum error
+header format error
+
+errors from media/system:
+i/o error
+device busy
address@hidden format
+
+
address@hidden Blocking
address@hidden Blocking
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden and @dfn{record} terminology is rather confused, and it
+is also confusing to the expert reader. On the other hand, readers
+who are new to the field have a fresh mind, and they may safely skip
+the next two paragraphs, as the remainder of this manual uses those
+two terms in a quite consistent way.
+
+John Gilmore, the writer of the public domain @command{tar} from which
address@hidden @command{tar} was originally derived, wrote (June 1995):
+
address@hidden
+The nomenclature of tape drives comes from IBM, where I believe
+they were invented for the IBM 650 or so. On IBM mainframes, what
+is recorded on tape are tape blocks. The logical organization of
+data is into records. There are various ways of putting records into
+blocks, including @code{F} (fixed sized records), @code{V} (variable
+sized records), @code{FB} (fixed blocked: fixed size records, @var{n}
+to a block), @code{VB} (variable size records, @var{n} to a block),
address@hidden (variable spanned blocked: variable sized records that can
+occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=}
+parameter specified this to the operating system.
+
+The Unix man page on @command{tar} was totally confused about this.
+When I wrote @code{PD TAR}, I used the historically correct terminology
+(@command{tar} writes data records, which are grouped into blocks).
+It appears that the bogus terminology made it into @acronym{POSIX} (no surprise
+here), and now Fran@,{c}ois has migrated that terminology back
+into the source code too.
address@hidden quotation
+
+The term @dfn{physical block} means the basic transfer chunk from or
+to a device, after which reading or writing may stop without anything
+being lost. In this manual, the term @dfn{block} usually refers to
+a disk physical block, @emph{assuming} that each disk block is 512
+bytes in length. It is true that some disk devices have different
+physical blocks, but @command{tar} ignore these differences in its own
+format, which is meant to be portable, so a @command{tar} block is always
+512 bytes in length, and @dfn{block} always mean a @command{tar} block.
+The term @dfn{logical block} often represents the basic chunk of
+allocation of many disk blocks as a single entity, which the operating
+system treats somewhat atomically; this concept is only barely used
+in @acronym{GNU} @command{tar}.
+
+The term @dfn{physical record} is another way to speak of a physical
+block, those two terms are somewhat interchangeable. In this manual,
+the term @dfn{record} usually refers to a tape physical block,
address@hidden that the @command{tar} archive is kept on magnetic tape.
+It is true that archives may be put on disk or used with pipes,
+but nevertheless, @command{tar} tries to read and write the archive one
address@hidden at a time, whatever the medium in use. One record is made
+up of an integral number of blocks, and this operation of putting many
+disk blocks into a single tape block is called @dfn{reblocking}, or
+more simply, @dfn{blocking}. The term @dfn{logical record} refers to
+the logical organization of many characters into something meaningful
+to the application. The term @dfn{unit record} describes a small set
+of characters which are transmitted whole to or by the application,
+and often refers to a line of text. Those two last terms are unrelated
+to what we call a @dfn{record} in @acronym{GNU} @command{tar}.
+
+When writing to tapes, @command{tar} writes the contents of the archive
+in chunks known as @dfn{records}. To change the default blocking
+factor, use the @address@hidden (@option{-b
address@hidden) option. Each record will then be composed of
address@hidden blocks. (Each @command{tar} block is 512 bytes.
address@hidden) Each file written to the archive uses at least one
+full record. As a result, using a larger record size can result in
+more wasted space for small files. On the other hand, a larger record
+size can often be read and written much more efficiently.
+
+Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger record size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+When reading an archive, @command{tar} can usually figure out the
+record size on itself. When this is the case, and a non-standard
+record size was used when the archive was created, @command{tar} will
+print a message about a non-standard blocking factor, and then operate
+normally. On some tape devices, however, @command{tar} cannot figure
+out the record size itself. On most of those, you can specify a
+blocking factor (with @option{--blocking-factor}) larger than the
+actual blocking factor, and then use the @option{--read-full-records}
+(@option{-B}) option. (If you specify a blocking factor with
address@hidden and don't use the
address@hidden option, then @command{tar} will not
+attempt to figure out the recording size itself.) On some devices,
+you must always specify the record size exactly with
address@hidden when reading, because @command{tar} cannot
+figure it out. In any case, use @option{--list} (@option{-t}) before
+doing any extractions to see whether @command{tar} is reading the archive
+correctly.
+
address@hidden blocks are all fixed size (512 bytes), and its scheme for
+putting them into records is to put a whole number of them (one or
+more) into each record. @command{tar} records are all the same size;
+at the end of the file there's a block containing all zeros, which
+is how you tell that the remainder of the last record(s) are garbage.
+
+In a standard @command{tar} file (no options), the block size is 512
+and the record size is 10240, for a blocking factor of 20. What the
address@hidden option does is sets the blocking factor,
+changing the record size while leaving the block size at 512 bytes.
+20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives;
+most tape drives these days prefer much bigger records in order to
+stream and not waste tape. When writing tapes for myself, some tend
+to use a factor of the order of 2048, say, giving a record size of
+around one megabyte.
+
+If you use a blocking factor larger than 20, older @command{tar}
+programs might not be able to read the archive, so we recommend this
+as a limit to use in practice. @acronym{GNU} @command{tar}, however,
+will support arbitrarily large record sizes, limited only by the
+amount of virtual memory or the physical characteristics of the tape
+device.
+
address@hidden
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
address@hidden menu
+
address@hidden Format Variations
address@hidden Format Variations
address@hidden Format Parameters
address@hidden Format Options
address@hidden Options, archive format specifying
address@hidden Options, format specifying
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Format parameters specify how an archive is written on the archive
+media. The best choice of format parameters will vary depending on
+the type and number of files being archived, and on the media used to
+store the archive.
+
+To specify format parameters when accessing or creating an archive,
+you can use the options described in the following sections.
+If you do not specify any format parameters, @command{tar} uses
+default parameters. You cannot modify a compressed archive.
+If you create an archive with the @option{--blocking-factor} option
+specified (@pxref{Blocking Factor}), you must specify that
+blocking-factor when operating on the archive. @xref{Formats}, for other
+examples of format parameter considerations.
+
address@hidden Blocking Factor
address@hidden The Blocking Factor of an Archive
address@hidden Blocking Factor
address@hidden Record Size
address@hidden Number of blocks per record
address@hidden Number of bytes per record
address@hidden Bytes per record
address@hidden Blocks per record
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden blocking-factor
+The data in an archive is grouped into blocks, which are 512 bytes.
+Blocks are read and written in whole number multiples called
address@hidden The number of blocks in a record (i.e. the size of a
+record in units of 512 bytes) is called the @dfn{blocking factor}.
+The @address@hidden (@option{-b
address@hidden) option specifies the blocking factor of an archive.
+The default blocking factor is typically 20 (i.e., 10240 bytes), but
+can be specified at installation. To find out the blocking factor of
+an existing archive, use @samp{tar --list address@hidden
+This may not work on some devices.
+
+Records are separated by gaps, which waste space on the archive media.
+If you are archiving on magnetic tape, using a larger blocking factor
+(and therefore larger records) provides faster throughput and allows you
+to fit more data on a tape (because there are fewer gaps). If you are
+archiving on cartridge, a very large blocking factor (say 126 or more)
+greatly increases performance. A smaller blocking factor, on the other
+hand, may be useful when archiving small files, to avoid archiving lots
+of nulls as @command{tar} fills out the archive to the end of the record.
+In general, the ideal record size depends on the size of the
+inter-record gaps on the tape you are using, and the average size of the
+files you are archiving. @xref{create}, for information on
+writing archives.
+
address@hidden
address@hidden
+
+
+Archives with blocking factors larger than 20 cannot be read
+by very old versions of @command{tar}, or by some newer versions
+of @command{tar} running on old machines with small address spaces.
+With @acronym{GNU} @command{tar}, the blocking factor of an archive is limited
+only by the maximum record size of the device containing the archive,
+or by the amount of available virtual memory.
+
+Also, on some systems, not using adequate blocking factors, as sometimes
+imposed by the device drivers, may yield unexpected diagnostics. For
+example, this has been reported:
+
address@hidden
+Cannot write to /dev/dlt: Invalid argument
address@hidden smallexample
+
address@hidden
+In such cases, it sometimes happen that the @command{tar} bundled by
+the system is aware of block size idiosyncrasies, while @acronym{GNU}
@command{tar}
+requires an explicit specification for the block size,
+which it cannot guess. This yields some people to consider
address@hidden @command{tar} is misbehaving, because by comparison,
address@hidden bundle @command{tar} works OK}. Adding @address@hidden 256}},
+for example, might resolve the problem.
+
+If you use a non-default blocking factor when you create an archive, you
+must specify the same blocking factor when you modify that archive. Some
+archive devices will also require you to specify the blocking factor when
+reading that archive, however this is not typically the case. Usually, you
+can use @option{--list} (@option{-t}) without specifying a blocking
address@hidden
+reports a non-default record size and then lists the archive members as
+it would normally. To extract files from an archive with a non-standard
+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}.
address@hidden, for more information on the @option{--list} (@option{-t})
+operation. @xref{Reading}, for a more detailed explanation of that option.
+
address@hidden @option
address@hidden address@hidden
address@hidden -b @var{number}
+Specifies the blocking factor of an archive. Can be used with any
+operation, but is usually not necessary with @option{--list} (@option{-t}).
address@hidden table
+
+Device blocking
+
address@hidden @option
address@hidden -b @var{blocks}
address@hidden address@hidden
+Set record size to @address@hidden * 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
+of the archive in records of @address@hidden bytes. This is true
+even when the archive is compressed. Some devices requires that all
+write operations be a multiple of a certain size, and so, @command{tar}
+pads the archive out to the next record boundary.
+
+The default blocking factor is set when @command{tar} is compiled, and is
+typically 20. Blocking factors larger than 20 cannot be read by very
+old versions of @command{tar}, or by some newer versions of @command{tar}
+running on old machines with small address spaces.
+
+With a magnetic tape, larger records give faster throughput and fit
+more data on a tape (because there are fewer inter-record gaps).
+If the archive is in a disk file or a pipe, you may want to specify
+a smaller blocking factor, since a large one will result in a large
+number of null bytes at the end of the archive.
+
+When writing cartridge or other streaming tapes, a much larger
+blocking factor (say 126 or more) will greatly increase performance.
+However, you must specify the same blocking factor when reading or
+updating the archive.
+
+Apparently, Exabyte drives have a physical block size of 8K bytes.
+If we choose our blocksize as a multiple of 8k bytes, then the problem
+seems to disappear. Id est, we are using block size of 112 right
+now, and we haven't had the problem since we address@hidden
+
+With @acronym{GNU} @command{tar} the blocking factor is limited only
+by the maximum record size of the device containing the archive, or by
+the amount of available virtual memory.
+
+However, deblocking or reblocking is virtually avoided in a special
+case which often occurs in practice, but which requires all the
+following conditions to be simultaneously true:
address@hidden @bullet
address@hidden
+the archive is subject to a compression option,
address@hidden
+the archive is not handled through standard input or output, nor
+redirected nor piped,
address@hidden
+the archive is directly handled to a local disk, instead of any special
+device,
address@hidden
address@hidden is not explicitly specified on the @command{tar}
+invocation.
address@hidden itemize
+
+If the output goes directly to a local disk, and not through
+stdout, then the last write is not extended to a full record size.
+Otherwise, reblocking occurs. Here are a few other remarks on this
+topic:
+
address@hidden @bullet
+
address@hidden
address@hidden will complain about trailing garbage if asked to
+uncompress a compressed archive on tape, there is an option to turn
+the message off, but it breaks the regularity of simply having to use
address@hidden@var{prog} -d} for decompression. It would be nice if gzip was
+silently ignoring any number of trailing zeros. I'll ask Jean-loup
+Gailly, by sending a copy of this message to him.
+
address@hidden
address@hidden does not show this problem, but as Jean-loup pointed
+out to Michael, @samp{compress -d} silently adds garbage after
+the result of decompression, which tar ignores because it already
+recognized its end-of-file indicator. So this bug may be safely
+ignored.
+
address@hidden
address@hidden -d -q} will be silent about the trailing zeros indeed,
+but will still return an exit status of 2 which tar reports in turn.
address@hidden might ignore the exit status returned, but I hate doing
+that, as it weakens the protection @command{tar} offers users against
+other possible problems at decompression time. If @command{gzip} was
+silently skipping trailing zeros @emph{and} also avoiding setting the
+exit status in this innocuous case, that would solve this situation.
+
address@hidden
address@hidden should become more solid at not stopping to read a pipe at
+the first null block encountered. This inelegantly breaks the pipe.
address@hidden should rather drain the pipe out before exiting itself.
address@hidden itemize
+
address@hidden address@hidden, short description}
address@hidden -i
address@hidden --ignore-zeros
+Ignore blocks of zeros in archive (means EOF).
+
+The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to
ignore blocks
+of zeros in the archive. Normally a block of zeros indicates the
+end of the archive, but when reading a damaged archive, or one which
+was created by concatenating several archives together, this option
+allows @command{tar} to read the entire archive. This option is not on
+by default because many versions of @command{tar} write garbage after
+the zeroed blocks.
+
+Note that this option causes @command{tar} to read to the end of the
+archive file, which may sometimes avoid problems when multiple files
+are stored on a single physical tape.
+
address@hidden address@hidden, short description}
address@hidden -B
address@hidden --read-full-records
+Reblock as we read (for reading 4.2BSD pipes).
+
+If @option{--read-full-records} is used, @command{tar}
+will not panic if an attempt to read a record from the archive does
+not return a full record. Instead, @command{tar} will keep reading
+until it has obtained a full
+record.
+
+This option is turned on by default when @command{tar} is reading
+an archive from standard input, or from a remote machine. This is
+because on BSD Unix systems, a read of a pipe will return however
+much happens to be in the pipe, even if it is less than @command{tar}
+requested. If this option was not used, @command{tar} would fail as
+soon as it read an incomplete record from the pipe.
+
+This option is also useful with the commands for updating an archive.
+
address@hidden table
+
+Tape blocking
+
address@hidden
address@hidden
+
+
address@hidden blocking factor
address@hidden tape blocking
+
+When handling various tapes or cartridges, you have to take care of
+selecting a proper blocking, that is, the number of disk blocks you
+put together as a single tape block on the tape, without intervening
+tape gaps. A @dfn{tape gap} is a small landing area on the tape
+with no information on it, used for decelerating the tape to a
+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.
+
address@hidden Exabyte blocking
address@hidden DAT blocking
+Using higher blocking (putting more disk blocks per tape block) will use
+the tape more efficiently as there will be less tape gaps. But reading
+such tapes may be more difficult for the system, as more memory will be
+required to receive at once the whole record. Further, if there is a
+reading error on a huge record, this is less likely that the system will
+succeed in recovering the information. So, blocking should not be too
+low, nor it should be too high. @command{tar} uses by default a blocking of
+20 for historical reasons, and it does not really matter when reading or
+writing to disk. Current tape technology would easily accommodate higher
+blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs.
+We were told that for some DLT drives, the blocking should be a multiple
+of 4Kb, preferably 64Kb (@address@hidden 128}}) or 256 for decent performance.
+Other manufacturers may use different recommendations for the same tapes.
+This might also depends of the buffering techniques used inside modern
+tape controllers. Some imposes a minimum blocking, or a maximum blocking.
+Others request blocking to be some exponent of two.
+
+So, there is no fixed rule for blocking. But blocking at read time
+should ideally be the same as blocking used at write time. At one place
+I know, with a wide variety of equipment, they found it best to use a
+blocking of 32 to guarantee that their tapes are fully interchangeable.
+
+I was also told that, for recycled tapes, prior erasure (by the same
+drive unit that will be used to create the archives) sometimes lowers
+the error rates observed at rewriting time.
+
+I might also use @option{--number-blocks} instead of
address@hidden, so @option{--block} will then expand to
address@hidden unambiguously.
+
address@hidden Many
address@hidden Many Archives on One Tape
+
address@hidden
address@hidden
+
+
address@hidden ntape @r{device}
+Most tape devices have two entries in the @file{/dev} directory, or
+entries that come in pairs, which differ only in the minor number for
+this device. Let's take for example @file{/dev/tape}, which often
+points to the only or usual tape device of a given system. There might
+be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler
+name is the @emph{rewinding} version of the device, while the name
+having @samp{nr} in it is the @emph{no rewinding} version of the same
+device.
+
+A rewinding tape device will bring back the tape to its beginning point
+automatically when this device is opened or closed. Since @command{tar}
+opens the archive file before using it and closes it afterwards, this
+means that a simple:
+
address@hidden
+$ @kbd{tar cf /dev/tape @var{directory}}
address@hidden smallexample
+
address@hidden
+will reposition the tape to its beginning both prior and after saving
address@hidden contents to it, thus erasing prior tape contents and
+making it so that any subsequent write operation will destroy what has
+just been saved.
+
address@hidden tape positioning
+So, a rewinding device is normally meant to hold one and only one file.
+If you want to put more than one @command{tar} archive on a given tape, you
+will need to avoid using the rewinding version of the tape device. You
+will also have to pay special attention to tape positioning. Errors in
+positioning may overwrite the valuable data already on your tape. Many
+people, burnt by past experiences, will only use rewinding devices and
+limit themselves to one file per tape, precisely to avoid the risk of
+such errors. Be fully aware that writing at the wrong position on a
+tape loses all information past this point and most probably until the
+end of the tape, and this destroyed information @emph{cannot} be
+recovered.
+
+To save @var{directory-1} as a first archive at the beginning of a
+tape, and leave that tape ready for a second archive, you should use:
+
address@hidden
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{tar cf /dev/nrtape @var{directory-1}}
address@hidden smallexample
+
address@hidden tape marks
address@hidden marks} are special magnetic patterns written on the tape
+media, which are later recognizable by the reading hardware. These
+marks are used after each file, when there are many on a single tape.
+An empty file (that is to say, two tape marks in a row) signal the
+logical end of the tape, after which no file exist. Usually,
+non-rewinding tape device drivers will react to the close request issued
+by @command{tar} by first writing two tape marks after your archive, and by
+backspacing over one of these. So, if you remove the tape at that time
+from the tape drive, it is properly terminated. But if you write
+another file at the current position, the second tape mark will be
+erased by the new information, leaving only one tape mark between files.
+
+So, you may now save @var{directory-2} as a second archive after the
+first on the same tape by issuing the command:
+
address@hidden
+$ @kbd{tar cf /dev/nrtape @var{directory-2}}
address@hidden smallexample
+
address@hidden
+and so on for all the archives you want to put on the same tape.
+
+Another usual case is that you do not write all the archives the same
+day, and you need to remove and store the tape between two archive
+sessions. In general, you must remember how many files are already
+saved on your tape. Suppose your tape already has 16 files on it, and
+that you are ready to write the 17th. You have to take care of skipping
+the first 16 tape marks before saving @var{directory-17}, say, by using
+these commands:
+
address@hidden
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{mt -f /dev/nrtape fsf 16}
+$ @kbd{tar cf /dev/nrtape @var{directory-17}}
address@hidden smallexample
+
+In all the previous examples, we put aside blocking considerations, but
+you should do the proper things for that as well. @xref{Blocking}.
+
address@hidden
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
address@hidden menu
+
address@hidden Tape Positioning
address@hidden Tape Positions and Tape Marks
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Just as archives can store more than one file from the file system,
+tapes can store more than one archive file. To keep track of where
+archive files (or any other type of file stored on tape) begin and
+end, tape archive devices write magnetic @dfn{tape marks} on the
+archive media. Tape drives write one tape mark between files,
+two at the end of all the file entries.
+
+If you think of data as a series of records "rrrr"'s, and tape marks as
+"*"'s, a tape might look like the following:
+
address@hidden
+rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
address@hidden smallexample
+
+Tape devices read and write tapes using a read/write @dfn{tape
+head}---a physical part of the device which can only access one
+point on the tape at a time. When you use @command{tar} to read or
+write archive data from a tape device, the device will begin reading
+or writing from wherever on the tape the tape head happens to be,
+regardless of which archive or what part of the archive the tape
+head is on. Before writing an archive, you should make sure that no
+data on the tape will be overwritten (unless it is no longer needed).
+Before reading an archive, you should make sure the tape head is at
+the beginning of the archive you want to read. You can do it manually
+via @code{mt} utility (@pxref{mt}). The @code{restore} script does
+that automatically (@pxref{Scripted Restoration}).
+
+If you want to add new archive file entries to a tape, you should
+advance the tape to the end of the existing file entries, backspace
+over the last tape mark, and write the new archive file. If you were
+to add two archives to the example above, the tape might look like the
+following:
+
address@hidden
+rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
address@hidden smallexample
+
address@hidden mt
address@hidden The @command{mt} Utility
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
address@hidden Factor}.
+
+You can use the @command{mt} utility to advance or rewind a tape past a
+specified number of archive files on the tape. This will allow you
+to move to the beginning of an archive before extracting or reading
+it, or to the end of all the archives before writing a new one.
address@hidden
address@hidden
+
+
+The syntax of the @command{mt} command is:
+
address@hidden
address@hidden [-f @var{tapename}] @var{operation} address@hidden
address@hidden smallexample
+
+where @var{tapename} is the name of the tape device, @var{number} is
+the number of times an operation is performed (with a default of one),
+and @var{operation} is one of the following:
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden eof
address@hidden weof
+Writes @var{number} tape marks at the current position on the tape.
+
address@hidden fsf
+Moves tape position forward @var{number} files.
+
address@hidden bsf
+Moves tape position back @var{number} files.
+
address@hidden rewind
+Rewinds the tape. (Ignores @var{number}).
+
address@hidden offline
address@hidden rewoff1
+Rewinds the tape and takes the tape device off-line. (Ignores @var{number}).
+
address@hidden status
+Prints status information about the tape unit.
+
address@hidden table
+
address@hidden
address@hidden
+
+
+If you don't specify a @var{tapename}, @command{mt} uses the environment
+variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
+the default device specified in your @file{sys/mtio.h} file
+(@code{DEFTAPE} variable). If this is not defined, the program will
+display a descriptive error message and exit with code 1.
+
address@hidden returns a 0 exit status when the operation(s) were
+successful, 1 if the command was unrecognized, and 2 if an operation
+failed.
+
address@hidden Using Multiple Tapes
address@hidden Using Multiple Tapes
+
+Often you might want to write a large archive, one larger than will fit
+on the actual tape you are using. In such a case, you can run multiple
address@hidden commands, but this can be inconvenient, particularly if you
+are using options like @address@hidden or dumping entire file systems.
+Therefore, @command{tar} provides a special mode for creating
+multi-volume archives.
+
address@hidden archive is a single @command{tar} archive, stored
+on several media volumes of fixed size. Although in this section we will
+often call @samp{volume} a @dfn{tape}, there is absolutely no
+requirement for multi-volume archives to be stored on tapes. Instead,
+they can use whatever media type the user finds convenient, they can
+even be located on files.
+
+When creating a multi-volume arvhive, @acronym{GNU} @command{tar} continues to
fill
+current volume until it runs out of space, then it switches to
+next volume (usually the operator is queried to replace the tape on
+this point), and continues working on the new volume. This operation
+continues untill all requested files are dumped. If @acronym{GNU}
@command{tar} detects
+end of media while dumping a file, such a file is archived in split
+form. Some very big files can even be split across several volumes.
+
+Each volume is itself a valid @acronym{GNU} @command{tar} archive, so it can
be read
+without any special options. Consequently any file member residing
+entirely on one volume can be extracted or otherwise operated upon
+without needing the other volume. Sure enough, to extract a split
+member you would need all volumes its parts reside on.
+
+Multi-volume archives suffer from several limitations. In particular,
+they cannot be compressed.
+
address@hidden @command{tar} is able to create multi-volume archives of two
formats
+(@pxref{Formats}): @samp{GNU} and @samp{POSIX}.
+
address@hidden
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
address@hidden menu
+
address@hidden Multi-Volume Archives
address@hidden Archives Longer than One Tape or Disk
address@hidden Multi-volume archives
+
address@hidden multi-volume
+To create an archive that is larger than will fit on a single unit of
+the media, use the @option{--multi-volume} (@option{-M}) option in conjunction
with
+the @option{--create} option (@pxref{create}). A @dfn{multi-volume}
+archive can be manipulated like any other archive (provided the
address@hidden option is specified), but is stored on more
+than one tape or disk.
+
+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
+the end of the media (when writing). Instead, it prompts you to load
+a new storage volume. If the archive is on a magnetic tape, you
+should change tapes when you see the prompt; if the archive is on a
+floppy disk, you should change disks; etc.
+
address@hidden @option
address@hidden --multi-volume
address@hidden -M
+Creates a multi-volume archive, when used in conjunction with
address@hidden (@option{-c}). To perform any other operation on a multi-volume
+archive, specify @option{--multi-volume} in conjunction with that
+operation.
+For example:
+
address@hidden
+$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}}
address@hidden smallexample
address@hidden table
+
+The method @command{tar} uses to detect end of tape is not perfect, and
+fails on some operating systems or on some devices. If @command{tar}
+cannot detect the end of the tape itself, you can use
address@hidden option to inform it about the capacity of the
+tape:
+
address@hidden
address@hidden @option
address@hidden tape-length
address@hidden address@hidden
address@hidden -L @var{size}
+Set maximum length of a volume. The @var{size} argument should then
+be the usable size of the tape in units of 1024 bytes. This option
+selects @option{--multi-volume} automatically. For example:
+
address@hidden
+$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}}
address@hidden smallexample
address@hidden table
+
address@hidden volume prompt}
+When @acronym{GNU} @command{tar} comes to the end of a storage media, it asks
you to
+change the volume. The built-in prompt for POSIX locale
address@hidden you run @acronym{GNU} @command{tar} under a different locale, the
+translation to the locale's language will be used.}:
+
address@hidden
+Prepare volume address@hidden for address@hidden' and hit return:
address@hidden smallexample
+
address@hidden
+where @var{n} is the ordinal number of the volume to be created and
address@hidden is archive file or device name.
+
+When prompting for a new tape, @command{tar} accepts any of the following
+responses:
+
address@hidden @kbd
address@hidden ?
+Request @command{tar} to explain possible responses
address@hidden q
+Request @command{tar} to exit immediately.
address@hidden n @var{file-name}
+Request @command{tar} to write the next volume on the file @var{file-name}.
address@hidden !
+Request @command{tar} to run a subshell. This option can be disabled
+by giving @option{--restrict} command line option to
address@hidden@address@hidden, for more information about
+this option}.
address@hidden y
+Request @command{tar} to begin writing the next volume.
address@hidden table
+
+(You should only type @samp{y} after you have changed the tape;
+otherwise @command{tar} will write over the volume it just finished.)
+
address@hidden Volume number file
address@hidden volno file
address@hidden
address@hidden volno-file
+The volume number used by @command{tar} in its tape-changing prompt
+can be changed; if you give the
address@hidden@var{file-of-number}} option, then
address@hidden should be an unexisting file to be created, or
+else, a file already containing a decimal number. That number will be
+used as the volume number of the first volume written. When
address@hidden is finished, it will rewrite the file with the
+now-current volume number. (This does not change the volume number
+written on a tape label, as per @ref{label}, it @emph{only} affects
+the number used in the prompt.)
+
address@hidden End-of-archive info script
address@hidden Info script
address@hidden
address@hidden info-script
address@hidden new-volume-script
+If you want more elaborate behavior than this, you can write a special
address@hidden volume script}, that will be responsible for changing the
+volume, and instruct @command{tar} to use it instead of its normal
+prompting procedure:
+
address@hidden @option
address@hidden address@hidden
address@hidden address@hidden
address@hidden -F @var{script-name}
+Specify the full name of the volume script to use. The script can be
+used to eject cassettes, or to broadcast messages such as
address@hidden please come change my tape} when performing unattended
+backups.
address@hidden table
+
+The @var{script-name} is executed without any command line
+arguments. It inherits @command{tar}'s shell environment.
+Additional data is passed to it via the following
+environment variables:
+
address@hidden @env
address@hidden TAR_VERSION, info script environment variable
address@hidden TAR_VERSION
address@hidden @command{tar} version number.
+
address@hidden TAR_ARCHIVE, info script environment variable
address@hidden TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
address@hidden TAR_VOLUME, info script environment variable
address@hidden TAR_VOLUME
+Ordinal number of the volume @command{tar} is about to start.
+
address@hidden TAR_SUBCOMMAND, info script environment variable
address@hidden TAR_SUBCOMMAND
+Short option describing the operation @command{tar} is executing
address@hidden, for a complete list of subcommand options.
+
address@hidden TAR_FORMAT, info script environment variable
address@hidden TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
address@hidden table
+
+The volume script can instruct @command{tar} to use new archive name,
+by writing in to file descriptor 3 (see below for an example).
+
+If the info script fails, @command{tar} exits; otherwise, it begins
+writing the next volume.
+
+If you want @command{tar} to cycle through a series of files or tape
+drives, there are three approaches to choose from. First of all, you
+can give @command{tar} multiple @option{--file} options. In this case
+the specified files will be used, in sequence, as the successive
+volumes of the archive. Only when the first one in the sequence needs
+to be used again will @command{tar} prompt for a tape change (or run
+the info script). For example, suppose someone has two tape drives on
+a system named @file{/dev/tape0} and @file{/dev/tape1}. For having
address@hidden @command{tar} to switch to the second drive when it needs to
write the
+second tape, and then back to the first tape, etc., just do either of:
+
address@hidden
+$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1
@var{files}}
+$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
address@hidden smallexample
+
+The second method is to use the @samp{n} response to the tape-change
+prompt.
+
+Finally, the most flexible approach is to use a volume script, that
+writes new archive name to the file descriptor #3. For example, the
+following volume script will create a series of archive files, named
address@hidden@address@hidden, where @var{archive} is the name of the
+archive being created (as given by @option{--file} option) and
address@hidden is the ordinal number of the archive being created:
+
address@hidden
address@hidden
+#! /bin/sh
+echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+
+name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+case $TAR_SUBCOMMAND in
+-c) ;;
+-d|-x|-t) test -r address@hidden:address@hidden || exit 1
+ ;;
+*) exit 1
+esac
+
+echo address@hidden:address@hidden >&3
address@hidden group
address@hidden smallexample
+
+The same script cant be used while listing, comparing or extracting
+from the created archive. For example:
+
address@hidden
address@hidden
+# @r{Create a multi-volume archive:}
+$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .}
+# @r{Extract from the created archive:}
+$ @kbd{tar -x -f archive.tar -F new-volume .}
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that the first command had to use @option{-L} option, since
+otherwise @acronym{GNU} @command{tar} will end up writing everything to file
address@hidden
+
+You can read each individual volume of a multi-volume archive as if it
+were an archive by itself. For example, to list the contents of one
+volume, use @option{--list}, without @option{--multi-volume} specified.
+To extract an archive member from one volume (assuming it is described
+that volume), use @option{--extract}, again without
address@hidden
+
+If an archive member is split across volumes (i.e. its entry begins on
+one volume of the media and ends on another), you need to specify
address@hidden to extract it successfully. In this case, you
+should load the volume where the archive member starts, and use
address@hidden --extract address@hidden will prompt for later
+volumes as it needs them. @xref{extracting archives}, for more
+information about extracting archives.
+
+Multi-volume archives can be modified like any other archive. To add
+files to a multi-volume archive, you need to only mount the last
+volume of the archive media (and new volumes, if needed). For all
+other operations, you need to use the entire archive.
+
+If a multi-volume archive was labeled using
address@hidden@var{archive-label}} (@pxref{label}) when it was
+created, @command{tar} will not automatically label volumes which are
+added later. To label subsequent volumes, specify
address@hidden@var{archive-label}} again in conjunction with the
address@hidden, @option{--update} or @option{--concatenate} operation.
+
+Notice that multi-volume support is a GNU extension and the archives
+created in this mode should be read only using @acronym{GNU} @command{tar}.
If you
+absolutely have to process such archives using a third-party @command{tar}
+implementation, read @ref{Split Recovery}.
+
address@hidden Tape Files
address@hidden Tape Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+To give the archive a name which will be recorded in it, use the
address@hidden@var{volume-label}} (@option{-V @var{volume-label}})
+option. This will write a special block identifying
address@hidden as the name of the archive to the front of the
+archive which will be displayed when the archive is listed with
address@hidden If you are creating a multi-volume archive with
address@hidden (@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 @address@hidden) option when
+reading an archive, it checks to make sure the label on the tape
+matches the one you give. @xref{label}.
+
+When @command{tar} writes an archive to tape, it creates a single
+tape file. If multiple archives are written to the same tape, one
+after the other, they each get written as separate tape files. When
+extracting, it is necessary to position the tape at the right place
+before running @command{tar}. To do this, use the @command{mt} command.
+For more information on the @command{mt} command and on the organization
+of tapes into a sequence of tape files, see @ref{mt}.
+
+People seem to often do:
+
address@hidden
address@hidden"@var{some-prefix} `date address@hidden"}
address@hidden smallexample
+
+or such, for pushing a common date in all volumes or an archive set.
+
address@hidden Tarcat
address@hidden Concatenate Volumes into a Single Archive
+
address@hidden tarcat
+ Sometimes it is necessary to convert existing @acronym{GNU} @command{tar}
multi-volume
+archive to a single @command{tar} archive. Simply concatenating all
+volumes into one will not work, since each volume carries an additional
+information at the beginning. @acronym{GNU} @command{tar} is shipped with the
shell
+script @command{tarcat} designed for this purpose.
+
+ The script takes a list of files comprising a multi-volume archive
+and creates the resulting archive at the standard output. For example:
+
address@hidden
address@hidden vol.1 vol.2 vol.3 | tar tf -}
address@hidden smallexample
+
+ The script implements a simple heuristics to determine the format of
+the first volume file and to decide how to process the rest of the
+files. However, it makes no attempt to verify whether the files are
+given in order or even if they are valid @command{tar} archives.
+It uses @command{dd} and does not filter its standard error, so you
+will usually see lots of spurious messages.
+
address@hidden
address@hidden
+
+
address@hidden label
address@hidden Including a Label in the Archive
address@hidden Labeling an archive
address@hidden Labels on the archive media
address@hidden Labeling multi-volume archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden label
+ To avoid problems caused by misplaced paper labels on the archive
+media, you can include a @dfn{label} entry---an archive member which
+contains the name of the archive---in the archive itself. Use the
address@hidden@var{archive-label}} (@option{-V @var{archive-label}})
+option in conjunction with the @option{--create} operation to include
+a label entry in the archive as it is being created.
+
address@hidden @option
address@hidden address@hidden
address@hidden -V @var{archive-label}
+Includes an @dfn{archive-label} at the beginning of the archive when
+the archive is being created, when used in conjunction with the
address@hidden operation. Checks to make sure the archive label
+matches the one specified (when used in conjunction with any other
+operation.
address@hidden table
+
+ If you create an archive using both
address@hidden@var{archive-label}} (@option{-V @var{archive-label}})
+and @option{--multi-volume} (@option{-M}), each volume of the archive
+will have an archive label of the form @address@hidden
+Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
+next, and so on. @xref{Using Multiple Tapes}, for information on
+creating multiple volume archives.
+
address@hidden Volume label, listing
address@hidden Listing volume label
+ The volume label will be displayed by @option{--list} along with
+the file contents. If verbose display is requested, it will also be
+explicitely marked as in the example below:
+
address@hidden
address@hidden
+$ @kbd{tar --verbose --list --file=iamanarchive}
+V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
address@hidden group
address@hidden smallexample
+
address@hidden test-label
address@hidden option}
+ However, @option{--list} option will cause listing entire
+contents of the archive, which may be undesirable (for example, if the
+archive is stored on a tape). You can request checking only the volume
+by specifying @option{--test-label} option. This option reads only the
+first block of an archive, so it can be used with slow storage
+devices. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --test-label --file=iamanarchive}
+iamalabel
address@hidden group
address@hidden smallexample
+
+ If @option{--test-label} is used with a single command line
+argument, @command{tar} compares the volume label with the
+argument. It exits with code 0 if the two strings match, and with code
+2 otherwise. In this case no output is displayed. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
address@hidden 0
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
address@hidden 1
address@hidden group
address@hidden smallexample
+
+ If you request any operation, other than @option{--create}, along
+with using @option{--label} option, @command{tar} will first check if
+the archive label matches the one specified and will refuse to proceed
+if it does not. Use this as a safety precaution to avoid accidentally
+overwriting existing archives. For example, if you wish to add files
+to @file{archive}, presumably labelled with string @samp{My volume},
+you will get:
+
address@hidden
address@hidden
+$ @kbd{tar -rf archive --label 'My volume' .}
+tar: Archive not labeled to match `My volume'
address@hidden group
address@hidden smallexample
+
address@hidden
+in case its label does not match. This will work even if
address@hidden is not labelled at all.
+
+ Similarly, @command{tar} will refuse to list or extract the
+archive if its label doesn't match the @var{archive-label}
+specified. In those cases, @var{archive-label} argument is interpreted
+as a globbing-style pattern which must match the actual magnetic
+volume label. @xref{exclude}, for a precise description of how match
+is address@hidden versions of @command{tar} used full
+regular expression matching, or before that, only exact string
+matching, instead of wildcard matchers. We decided for the sake of
+simplicity to use a uniform matching device through
address@hidden If the switch @option{--multi-volume} (@option{-M}) is being
used,
+the volume label matcher will also suffix @var{archive-label} by
address@hidden@samp{ Volume [1-9]*}} if the initial match fails, before giving
+up. Since the volume numbering is automatically added in labels at
+creation time, it sounded logical to equally help the user taking care
+of it when the archive is being read.
+
+ The @option{--label} was once called @option{--volume}, but is not
+available under that name anymore.
+
+ You can also use @option{--label} to get a common information on
+all tapes of a series. For having this information different in each
+series created through a single script used on a regular basis, just
+manage to get some date string as part of the label. For example:
+
address@hidden
address@hidden
+$ @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`"}
address@hidden group
address@hidden smallexample
+
+ Also note that each label has its own date and time, which corresponds
+to when @acronym{GNU} @command{tar} initially attempted to write it,
+often soon after the operator launches @command{tar} or types the
+carriage return telling that the next tape is ready. Comparing date
+labels does give an idea of tape throughput only if the delays for
+rewinding tapes and the operator switching them were negligible, which
+is usually not the case.
+
address@hidden verify
address@hidden Verifying Data as It is Stored
address@hidden Verifying a write operation
address@hidden Double-checking a write operation
+
address@hidden @option
address@hidden -W
address@hidden --verify
address@hidden verify, short description
+Attempt to verify the archive after writing.
address@hidden table
+
+This option causes @command{tar} to verify the archive after writing it.
+Each volume is checked after it is written, and any discrepancies
+are recorded on the standard error output.
+
+Verification requires that the archive be on a back-space-able medium.
+This means pipes, some cartridge tape drives, and some other devices
+cannot be verified.
+
+You can insure the accuracy of an archive by comparing files in the
+system with archive members. @command{tar} can compare an archive to the
+file system as the archive is being written, to verify a write
+operation, or can compare a previously written archive, to insure that
+it is up to date.
+
address@hidden address@hidden, using with @option{--create}}
address@hidden address@hidden, using with @option{--verify}}
+To check for discrepancies in an archive immediately after it is
+written, use the @option{--verify} (@option{-W}) option in conjunction with
+the @option{--create} operation. When this option is
+specified, @command{tar} checks archive members against their counterparts
+in the file system, and reports discrepancies on the standard error.
+
+To verify an archive, you must be able to read it from before the end
+of the last written entry. This option is useful for detecting data
+errors on some tapes. Archives written to pipes, some cartridge tape
+drives, and some other devices cannot be verified.
+
+One can explicitly compare an already made archive with the file
+system by using the @option{--compare} (@option{--diff}, @option{-d})
+option, instead of using the more automatic @option{--verify} option.
address@hidden
+
+Note that these two options have a slightly different intent. The
address@hidden option checks how identical are the logical contents of some
+archive with what is on your disks, while the @option{--verify} option is
+really for checking if the physical contents agree and if the recording
+media itself is of dependable quality. So, for the @option{--verify}
+operation, @command{tar} tries to defeat all in-memory cache pertaining to
+the archive, while it lets the speed optimization undisturbed for the
address@hidden option. If you nevertheless use @option{--compare} for
+media verification, you may have to defeat the in-memory cache yourself,
+maybe by opening and reclosing the door latch of your recording unit,
+forcing some doubt in your operating system about the fact this is really
+the same volume as the one just written or read.
+
+The @option{--verify} option would not be necessary if drivers were indeed
+able to detect dependably all write failures. This sometimes require many
+magnetic heads, some able to read after the writes occurred. One would
+not say that drivers unable to detect all cases are necessarily flawed,
+as long as programming is concerned.
+
+The @option{--verify} (@option{-W}) option will not work in
+conjunction with the @option{--multi-volume} (@option{-M}) option or
+the @option{--append} (@option{-r}), @option{--update} (@option{-u})
+and @option{--delete} operations. @xref{Operations}, for more
+information on these operations.
+
+Also, since @command{tar} normally strips leading @samp{/} from file
+names (@pxref{absolute}), a command like @samp{tar --verify -cf
+/tmp/foo.tar /etc} will work as desired only if the working directory is
address@hidden/}, as @command{tar} uses the archive's relative member names
+(e.g., @file{etc/motd}) when verifying the archive.
+
address@hidden Write Protection
address@hidden Write Protection
+
+Almost all tapes and diskettes, and in a few rare cases, even disks can
+be @dfn{write protected}, to protect data on them from being changed.
+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).
+
+The write protection device itself is usually an integral part of the
+physical media, and can be a two position (write enabled/write
+disabled) switch, a notch which can be popped out or covered, a ring
+which can be removed from the center of a tape reel, or some other
+changeable feature.
+
address@hidden Changes
address@hidden Changes
+
+This appendix lists some important user-visible changes between
+version @acronym{GNU} @command{tar} 1.15.92 and previous versions. An
up-to-date
+version of this document is available at
address@hidden://www.gnu.org/@/software/@/tar/manual/changes.html,the
address@hidden @command{tar} documentation page}.
+
address@hidden @asis
address@hidden Use of globbing patterns when listing and extracting.
+
+Previous versions of GNU tar assumed shell-style globbing when
+extracting from or listing an archive. For example:
+
address@hidden
+$ @kbd{tar xf foo.tar '*.c'}
address@hidden smallexample
+
+would extract all files whose names end in @samp{.c}. This behavior
+was not documented and was incompatible with traditional tar
+implementations. Therefore, starting from version 1.15.91, GNU tar
+no longer uses globbing by default. For example, the above invocation
+is now interpreted as a request to extract from the archive the file
+named @file{*.c}.
+
+To facilitate transition to the new behavior for those users who got
+used to the previous incorrect one, @command{tar} will print a warning
+if it finds out that a requested member was not found in the archive
+and its name looks like a globbing pattern. For example:
+
address@hidden
+$ @kbd{tar xf foo.tar '*.c'}
+tar: Pattern matching characters used in file names. Please,
+tar: use --wildcards to enable pattern matching, or --no-wildcards to
+tar: suppress this warning.
+tar: *.c: Not found in archive
+tar: Error exit delayed from previous errors
address@hidden smallexample
+
+To treat member names as globbing patterns, use --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.
+
address@hidden, for the detailed discussion of the use of globbing
+patterns by @acronym{GNU} @command{tar}.
+
address@hidden Use of short option @option{-o}.
+
+Earlier versions of @acronym{GNU} @command{tar} understood @option{-o} command
line
+option as a synonym for @option{--old-archive}.
+
address@hidden @command{tar} starting from version 1.13.90 understands this
option as
+a synonym for @option{--no-same-owner}. This is compatible with
+UNIX98 @command{tar} implementations.
+
+However, to facilitate transition, @option{-o} option retains its
+old semantics when it is used with one of archive-creation commands.
+Users are encouraged to use @option{--format=oldgnu} instead.
+
+It is especially important, since versions of @acronym{GNU} Automake
+up to and including 1.8.4 invoke tar with this option to produce
+distribution tarballs. @xref{Formats,v7}, for the detailed discussion
+of this issue and its implications.
+
address@hidden
address@hidden
+.
address@hidden, tar-v7, Changing Automake's Behavior,
+automake, GNU Automake}, for a description on how to use various
+archive formats with @command{automake}.
+
+Future versions of @acronym{GNU} @command{tar} will understand @option{-o}
only as a
+synonym for @option{--no-same-owner}.
+
address@hidden Use of short option @option{-l}
+
+Earlier versions of @acronym{GNU} @command{tar} 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,
+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.
+
address@hidden Use of options @option{--portability} and @option{--old-archive}
+
+These options are deprecated. Please use @option{--format=v7} instead.
+
address@hidden Use of option @option{--posix}
+
+This option is deprecated. Please use @option{--format=posix} instead.
address@hidden table
+
address@hidden Configuring Help Summary
address@hidden Configuring Help Summary
+
+Running @kbd{tar --help} displays the short @command{tar} option
+summary (@pxref{help}). This summary is organised by @dfn{groups} of
+semantically close options. The options within each group are printed
+in the following order: a short option, eventually followed by a list
+of corresponding long option names, followed by a short description of
+the option. For example, here is an excerpt from the actual @kbd{tar
+--help} output:
+
address@hidden
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to an archive
+ -c, --create create a new archive
+ -d, --diff, --compare find differences between archive and
+ file system
+ --delete delete from the archive
address@hidden verbatim
+
address@hidden ARGP_HELP_FMT, environment variable
+The exact visual representation of the help output is configurable via
address@hidden environment variable. The value of this variable
+is a comma-separated list of @dfn{format variable} assignments. There
+are two kinds of format variables. An @dfn{offset variable} keeps the
+offset of some part of help output text from the leftmost column on
+the screen. A @dfn{boolean} variable is a flag that toggles some
+output feature on or off. Depending on the type of the corresponding
+variable, there are two kinds of assignments:
+
address@hidden @asis
address@hidden Offset assignment
+
+The assignment to an offset variable has the following syntax:
+
address@hidden
address@hidden@var{value}
address@hidden smallexample
+
address@hidden
+where @var{variable} is the variable name, and @var{value} is a
+numeric value to be assigned to the variable.
+
address@hidden Boolean assignment
+
+To assign @code{true} value to a variable, simply put this variable name. To
+assign @code{false} value, prefix the variable name with @samp{no-}. For
+example:
+
address@hidden
address@hidden
+# Assign @code{true} value:
+dup-args
+# Assign @code{false} value:
+no-dup-args
address@hidden group
address@hidden smallexample
address@hidden table
+
+Following variables are declared:
+
address@hidden {Help Output} boolean dup-args
+If true, arguments for an option are shown with both short and long
+options, even when a given option has both forms, for example:
+
address@hidden
+ -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden smallexample
+
+If false, then if an option has both short and long forms, the
+argument is only shown with the long one, for example:
+
address@hidden
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden smallexample
+
address@hidden
+and a message indicating that the argument is applicable to both
+forms is printed below the options. This message can be disabled
+using @code{dup-args-note} (see below).
+
+The default is false.
address@hidden deftypevr
+
address@hidden {Help Output} boolean dup-args-note
+If this variable is true, which is the default, the following notice
+is displayed at the end of the help output:
+
address@hidden
+Mandatory or optional arguments to long options are also mandatory or
+optional for any corresponding short options.
address@hidden quotation
+
+Setting @code{no-dup-args-note} inhibits this message. Normally, only one of
+variables @code{dup-args} or @code{dup-args-note} should be set.
address@hidden deftypevr
+
address@hidden {Help Output} offset short-opt-col
+Column in which short options start. Default is 2.
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset long-opt-col
+Column in which long options start. Default is 6. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset doc-opt-col
+Column in which @dfn{doc options} start. A doc option isn't actually
+an option, but rather an arbitrary piece of documentation that is
+displayed in much the same manner as the options. For example, in
+the description of @option{--format} option:
+
address@hidden
address@hidden
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
address@hidden group
address@hidden smallexample
+
address@hidden
+the format names are doc options. Thus, if you set
address@hidden the above part of the help output
+will look as follows:
+
address@hidden
address@hidden
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset opt-doc-col
+Column in which option description starts. Default is 29.
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE
+ use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that the description starts on a separate line if
address@hidden value is too small.
address@hidden deftypevr
+
address@hidden {Help Output} offset header-col
+Column in which @dfn{group headers} are printed. A group header is a
+descriptive text preceding an option group. For example, in the
+following text:
+
address@hidden
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to
+ an archive
+ -c, --create create a new archive
address@hidden verbatim
address@hidden
address@hidden operation mode:} is the group header.
+
+The default value is 1.
address@hidden deftypevr
+
address@hidden {Help Output} offset usage-indent
+Indentation of wrapped usage lines. Affects @option{--usage}
+output. Default is 12.
address@hidden deftypevr
+
address@hidden {Help Output} offset rmargin
+Right margin of the text output. Used for wrapping.
address@hidden deftypevr
+
address@hidden Tar Internals
address@hidden Tar Internals
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
address@hidden menu
+
address@hidden Standard
address@hidden Basic Tar Format
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+While an archive may contain many files, the archive itself is a
+single ordinary file. Like any other file, an archive file can be
+written to a storage device such as a tape or disk, sent through a
+pipe or over a network, saved on the active file system, or even
+stored in another archive. An archive file is not easy to read or
+manipulate without using the @command{tar} utility or Tar mode in
address@hidden Emacs.
+
+Physically, an archive consists of a series of file entries terminated
+by an end-of-archive entry, which consists of two 512 blocks of zero
+bytes. A file
+entry usually describes one of the files in the archive (an
address@hidden member}), and consists of a file header and the contents
+of the file. File headers contain file names and statistics, checksum
+information which @command{tar} uses to detect file corruption, and
+information about file types.
+
+Archives are permitted to have more than one member with the same
+member name. One way this situation can occur is if more than one
+version of a file has been stored in the archive. For information
+about adding new versions of a file to an archive, see @ref{update}.
address@hidden
+
+In addition to entries describing archive members, an archive may
+contain entries which @command{tar} itself uses to store information.
address@hidden, for an example of such an archive entry.
+
+A @command{tar} archive file contains a series of blocks. Each block
+contains @code{BLOCKSIZE} bytes. Although this format may be thought
+of as being on magnetic tape, other media are often used.
+
+Each file archived is represented by a header block which describes
+the file, followed by zero or more blocks which give the contents
+of the file. At the end of the archive file there are two 512-byte blocks
+filled with binary zeros as an end-of-file marker. A reasonable system
+should write such end-of-file marker at the end of an archive, but
+must not assume that such a block exists when reading an archive. In
+particular @acronym{GNU} @command{tar} always issues a warning if it does not
encounter it.
+
+The blocks may be @dfn{blocked} for physical I/O operations.
+Each record of @var{n} blocks (where @var{n} is set by the
address@hidden@var{512-size}} (@option{-b @var{512-size}}) option to
@command{tar}) is written with a single
address@hidden@samp{write ()}} operation. On magnetic tapes, the result of
+such a write is a single record. When writing an archive,
+the last record of blocks should be written at the full size, with
+blocks after the zero block containing all zeros. When reading
+an archive, a reasonable system should properly handle an archive
+whose last record is shorter than the rest, or which contains garbage
+records after a zero block.
+
+The header block is defined in C as follows. In the @acronym{GNU}
@command{tar}
+distribution, this is part of file @file{src/tar.h}:
+
address@hidden
address@hidden GNU tar Archive Format description.
address@hidden
address@hidden Copyright (C) 1988, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
1997,
address@hidden 2000, 2001, 2003, 2004, 2005, 2006 Free Software Foundation,
Inc.
address@hidden
address@hidden This program is free software; you can redistribute it and/or
modify it
address@hidden under the terms of the GNU General Public License as published
by the
address@hidden Free Software Foundation; either version 2, or (at your
option) any later
address@hidden version.
address@hidden
address@hidden This program is distributed in the hope that it will be
useful, but
address@hidden WITHOUT ANY WARRANTY; without even the implied warranty of
address@hidden MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General
address@hidden Public License for more details.
address@hidden
address@hidden You should have received a copy of the GNU General Public
License along
address@hidden with this program; if not, write to the Free Software
Foundation, Inc.,
address@hidden 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+/address@hidden tar Header Block, from POSIX 1003.1-1990. }*/
+
+/address@hidden POSIX header. }*/
+
+struct posix_header
address@hidden /address@hidden byte offset }*/
+ char name[100]; /address@hidden 0 }*/
+ char mode[8]; /address@hidden 100 }*/
+ char uid[8]; /address@hidden 108 }*/
+ char gid[8]; /address@hidden 116 }*/
+ char size[12]; /address@hidden 124 }*/
+ char mtime[12]; /address@hidden 136 }*/
+ char chksum[8]; /address@hidden 148 }*/
+ char typeflag; /address@hidden 156 }*/
+ char linkname[100]; /address@hidden 157 }*/
+ char magic[6]; /address@hidden 257 }*/
+ char version[2]; /address@hidden 263 }*/
+ char uname[32]; /address@hidden 265 }*/
+ char gname[32]; /address@hidden 297 }*/
+ char devmajor[8]; /address@hidden 329 }*/
+ char devminor[8]; /address@hidden 337 }*/
+ char prefix[155]; /address@hidden 345 }*/
+ /address@hidden 500 }*/
address@hidden;
+
+#define TMAGIC "ustar" /address@hidden ustar and a null }*/
+#define TMAGLEN 6
+#define TVERSION "00" /address@hidden 00 and no null }*/
+#define TVERSLEN 2
+
+/address@hidden Values used in typeflag field. }*/
+#define REGTYPE '0' /address@hidden regular file }*/
+#define AREGTYPE '\0' /address@hidden regular file }*/
+#define LNKTYPE '1' /address@hidden link }*/
+#define SYMTYPE '2' /address@hidden reserved }*/
+#define CHRTYPE '3' /address@hidden character special }*/
+#define BLKTYPE '4' /address@hidden block special }*/
+#define DIRTYPE '5' /address@hidden directory }*/
+#define FIFOTYPE '6' /address@hidden FIFO special }*/
+#define CONTTYPE '7' /address@hidden reserved }*/
+
+#define XHDTYPE 'x' /address@hidden Extended header referring to
the
+ next file in the archive }*/
+#define XGLTYPE 'g' /address@hidden Global extended header }*/
+
+/address@hidden Bits used in the mode field, values in octal. }*/
+#define TSUID 04000 /address@hidden set UID on execution }*/
+#define TSGID 02000 /address@hidden set GID on execution }*/
+#define TSVTX 01000 /address@hidden reserved }*/
+ /address@hidden file permissions }*/
+#define TUREAD 00400 /address@hidden read by owner }*/
+#define TUWRITE 00200 /address@hidden write by owner }*/
+#define TUEXEC 00100 /address@hidden execute/search by owner }*/
+#define TGREAD 00040 /address@hidden read by group }*/
+#define TGWRITE 00020 /address@hidden write by group }*/
+#define TGEXEC 00010 /address@hidden execute/search by group }*/
+#define TOREAD 00004 /address@hidden read by other }*/
+#define TOWRITE 00002 /address@hidden write by other }*/
+#define TOEXEC 00001 /address@hidden execute/search by other }*/
+
+/address@hidden tar Header Block, GNU extensions. }*/
+
+/address@hidden In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is
for
+ contiguous files, so maybe disobeying the `reserved' comment in POSIX
+ header description. I suspect these were meant to be used this way, and
+ should not have really been `reserved' in the published standards. }*/
+
+/address@hidden *BEWARE* *BEWARE* *BEWARE* that the following information is
still
+ boiling, and may change. Even if the OLDGNU format description should be
+ accurate, the so-called GNU format is not yet fully decided. It is
+ surely meant to use only extensions allowed by POSIX, but the sketch
+ below repeats some ugliness from the OLDGNU format, which should rather
+ go away. Sparse files should be saved in such a way that they do *not*
+ require two passes at archive creation time. Huge files get some POSIX
+ fields to overflow, alternate solutions have to be sought for this. }*/
+
+/address@hidden Descriptor for a single file hole. }*/
+
+struct sparse
address@hidden /address@hidden byte offset }*/
+ char offset[12]; /address@hidden 0 }*/
+ char numbytes[12]; /address@hidden 12 }*/
+ /address@hidden 24 }*/
address@hidden;
+
+/address@hidden Sparse files are not supported in POSIX ustar format. For
sparse files
+ with a POSIX header, a GNU extra header is provided which holds overall
+ sparse information and a few sparse descriptors. When an old GNU header
+ replaces both the POSIX header and the GNU extra header, it holds some
+ sparse descriptors too. Whether POSIX or not, if more sparse descriptors
+ are still needed, they are put into as many successive sparse headers as
+ necessary. The following constants tell how many sparse descriptors fit
+ in each kind of header able to hold them. }*/
+
+#define SPARSES_IN_EXTRA_HEADER 16
+#define SPARSES_IN_OLDGNU_HEADER 4
+#define SPARSES_IN_SPARSE_HEADER 21
+
+/address@hidden Extension header for sparse files, used immediately after the
GNU extra
+ header, and used only if all sparse information cannot fit into that
+ extra header. There might even be many such extension headers, one after
+ the other, until all sparse information has been recorded. }*/
+
+struct sparse_header
address@hidden /address@hidden byte offset }*/
+ struct sparse sp[SPARSES_IN_SPARSE_HEADER];
+ /address@hidden 0 }*/
+ char isextended; /address@hidden 504 }*/
+ /address@hidden 505 }*/
address@hidden;
+
+/address@hidden The old GNU format header conflicts with POSIX format in such
a way that
+ POSIX archives may fool old GNU tar's, and POSIX tar's might well be
+ fooled by old GNU tar archives. An old GNU format header uses the space
+ used by the prefix field in a POSIX header, and cumulates information
+ normally found in a GNU extra header. With an old GNU tar header, we
+ never see any POSIX header nor GNU extra header. Supplementary sparse
+ headers are allowed, however. }*/
+
+struct oldgnu_header
address@hidden /address@hidden byte offset }*/
+ char unused_pad1[345]; /address@hidden 0 }*/
+ char atime[12]; /address@hidden 345 Incr. archive: atime of
the file }*/
+ char ctime[12]; /address@hidden 357 Incr. archive: ctime of
the file }*/
+ char offset[12]; /address@hidden 369 Multivolume archive: the
offset of
+ the start of this volume }*/
+ char longnames[4]; /address@hidden 381 Not used }*/
+ char unused_pad2; /address@hidden 385 }*/
+ struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
+ /address@hidden 386 }*/
+ char isextended; /address@hidden 482 Sparse file: Extension
sparse header
+ follows }*/
+ char realsize[12]; /address@hidden 483 Sparse file: Real size}*/
+ /address@hidden 495 }*/
address@hidden;
+
+/address@hidden OLDGNU_MAGIC uses both magic and version fields, which are
contiguous.
+ Found in an archive, it indicates an old GNU header format, which will be
+ hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are
+ valid, though the header is not truly POSIX conforming. }*/
+#define OLDGNU_MAGIC "ustar " /address@hidden 7 chars and a null }*/
+
+/address@hidden The standards committee allows only capital A through capital
Z for
+ user-defined expansion. Other letters in use include:
+
+ 'A' Solaris Access Control List
+ 'E' Solaris Extended Attribute File
+ 'I' Inode only, as in 'star'
+ 'X' POSIX 1003.1-2001 eXtended (VU version) }*/
+
+/address@hidden This is a dir entry that contains the names of files that were
in the
+ dir at the time the dump was made. }*/
+#define GNUTYPE_DUMPDIR 'D'
+
+/address@hidden Identifies the *next* file on the tape as having a long
linkname. }*/
+#define GNUTYPE_LONGLINK 'K'
+
+/address@hidden Identifies the *next* file on the tape as having a long name.
}*/
+#define GNUTYPE_LONGNAME 'L'
+
+/address@hidden This is the continuation of a file that began on another
volume. }*/
+#define GNUTYPE_MULTIVOL 'M'
+
+/address@hidden For storing filenames that do not fit into the main header.
}*/
+#define GNUTYPE_NAMES 'N'
+
+/address@hidden This is for sparse files. }*/
+#define GNUTYPE_SPARSE 'S'
+
+/address@hidden This file is a tape/volume header. Ignore it on extraction.
}*/
+#define GNUTYPE_VOLHDR 'V'
+
+/address@hidden Solaris extended header }*/
+#define SOLARIS_XHDTYPE 'X'
+
+/address@hidden J@"org Schilling star header }*/
+
+struct star_header
address@hidden /address@hidden byte offset }*/
+ char name[100]; /address@hidden 0 }*/
+ char mode[8]; /address@hidden 100 }*/
+ char uid[8]; /address@hidden 108 }*/
+ char gid[8]; /address@hidden 116 }*/
+ char size[12]; /address@hidden 124 }*/
+ char mtime[12]; /address@hidden 136 }*/
+ char chksum[8]; /address@hidden 148 }*/
+ char typeflag; /address@hidden 156 }*/
+ char linkname[100]; /address@hidden 157 }*/
+ char magic[6]; /address@hidden 257 }*/
+ char version[2]; /address@hidden 263 }*/
+ char uname[32]; /address@hidden 265 }*/
+ char gname[32]; /address@hidden 297 }*/
+ char devmajor[8]; /address@hidden 329 }*/
+ char devminor[8]; /address@hidden 337 }*/
+ char prefix[131]; /address@hidden 345 }*/
+ char atime[12]; /address@hidden 476 }*/
+ char ctime[12]; /address@hidden 488 }*/
+ /address@hidden 500 }*/
address@hidden;
+
+#define SPARSES_IN_STAR_HEADER 4
+#define SPARSES_IN_STAR_EXT_HEADER 21
+
+struct star_in_header
address@hidden
+ char fill[345]; /address@hidden 0 Everything that is before
t_prefix }*/
+ char prefix[1]; /address@hidden 345 t_name prefix }*/
+ char fill2; /address@hidden 346 }*/
+ char fill3[8]; /address@hidden 347 }*/
+ char isextended; /address@hidden 355 }*/
+ struct sparse sp[SPARSES_IN_STAR_HEADER]; /address@hidden 356 }*/
+ char realsize[12]; /address@hidden 452 Actual size of the file }*/
+ char offset[12]; /address@hidden 464 Offset of multivolume contents }*/
+ char atime[12]; /address@hidden 476 }*/
+ char ctime[12]; /address@hidden 488 }*/
+ char mfill[8]; /address@hidden 500 }*/
+ char xmagic[4]; /address@hidden 508 "tar" }*/
address@hidden;
+
+struct star_ext_header
address@hidden
+ struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
+ char isextended;
address@hidden;
+
address@hidden smallexample
+
+All characters in header blocks are represented by using 8-bit
+characters in the local variant of ASCII. Each field within the
+structure is contiguous; that is, there is no padding used within
+the structure. Each character on the archive medium is stored
+contiguously.
+
+Bytes representing the contents of files (after the header block
+of each file) are not translated in any way and are not constrained
+to represent characters in any character set. The @command{tar} format
+does not distinguish text files from binary files, and no translation
+of file contents is performed.
+
+The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
address@hidden are null-terminated character strings. All other fields
+are zero-filled octal numbers in ASCII. Each numeric field of width
address@hidden contains @var{w} minus 1 digits, and a null.
+
+The @code{name} field is the file name of the file, with directory names
+(if any) preceding the file name, separated by slashes.
+
address@hidden
address@hidden
+
+
+The @code{mode} field provides nine bits specifying file permissions
+and three bits to specify the Set UID, Set GID, and Save Text
+(@dfn{sticky}) modes. Values for these bits are defined above.
+When special permissions are required to create a file with a given
+mode, and the user restoring files from the archive does not hold such
+permissions, the mode bit(s) specifying those special permissions
+are ignored. Modes which are not supported by the operating system
+restoring files from the archive will be ignored. Unsupported modes
+should be faked up when creating or updating an archive; e.g., the
+group permission could be copied from the @emph{other} permission.
+
+The @code{uid} and @code{gid} fields are the numeric user and group
+ID of the file owners, respectively. If the operating system does
+not support numeric user or group IDs, these fields should be ignored.
+
+The @code{size} field is the size of the file in bytes; linked files
+are archived with this field specified as zero. @quote-arg
+
+The @code{mtime} field is the data modification time of the file at
+the time it was archived. It is the ASCII representation of the octal
+value of the last time the file's contents were modified, represented
+as an integer number of
+seconds since January 1, 1970, 00:00 Coordinated Universal Time.
+
+The @code{chksum} field is the ASCII representation of the octal value
+of the simple sum of all bytes in the header block. Each 8-bit
+byte in the header is added to an unsigned integer, initialized to
+zero, the precision of which shall be no less than seventeen bits.
+When calculating the checksum, the @code{chksum} field is treated as
+if it were all blanks.
+
+The @code{typeflag} field specifies the type of file archived. If a
+particular implementation does not recognize or permit the specified
+type, the file will be extracted as if it were a regular file. As this
+action occurs, @command{tar} issues a warning to the standard error.
+
+The @code{atime} and @code{ctime} fields are used in making incremental
+backups; they store, respectively, the particular file's access and
+status change times.
+
+The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option,
when
+making a multi-volume archive. The offset is number of bytes into
+the file that we need to restart at to continue the file on the next
+tape, i.e., where we store the location that a continued file is
+continued at.
+
+The following fields were added to deal with sparse files. A file
+is @dfn{sparse} if it takes in unallocated blocks which end up being
+represented as zeros, i.e., no useful data. A test to see if a file
+is sparse is to look at the number blocks allocated for it versus the
+number of characters in the file; if there are fewer blocks allocated
+for the file than would normally be allocated for a file of that
+size, then the file is sparse. This is the method @command{tar} uses to
+detect a sparse file, and once such a file is detected, it is treated
+differently from non-sparse files.
+
+Sparse files are often @code{dbm} files, or other database-type files
+which have data at some points and emptiness in the greater part of
+the file. Such files can appear to be very large when an @samp{ls
+-l} is done on them, when in truth, there may be a very small amount
+of important data contained in the file. It is thus undesirable
+to have @command{tar} think that it must back up this entire file, as
+great quantities of room are wasted on empty blocks, which can lead
+to running out of room on a tape far earlier than is necessary.
+Thus, sparse files are dealt with so that these empty blocks are
+not written to the tape. Instead, what is written to the tape is a
+description, of sorts, of the sparse file: where the holes are, how
+big the holes are, and how much data is found at the end of the hole.
+This way, the file takes up potentially far less room on the tape,
+and when the file is extracted later on, it will look exactly the way
+it looked beforehand. The following is a description of the fields
+used to handle a sparse file:
+
+The @code{sp} is an array of @code{struct sparse}. Each @code{struct
+sparse} contains two 12-character strings which represent an offset
+into the file and a number of bytes to be written at that offset.
+The offset is absolute, and not relative to the offset in preceding
+array element.
+
+The header can hold four of these @code{struct sparse} at the moment;
+if more are needed, they are not stored in the header.
+
+The @code{isextended} flag is set when an @code{extended_header}
+is needed to deal with a file. Note that this means that this flag
+can only be set when dealing with a sparse file, and it is only set
+in the event that the description of the file will not fit in the
+allotted room for sparse structures in the header. In other words,
+an extended_header is needed.
+
+The @code{extended_header} structure is used for sparse files which
+need more sparse structures than can fit in the header. The header can
+fit 4 such structures; if more are needed, the flag @code{isextended}
+gets set and the next block is an @code{extended_header}.
+
+Each @code{extended_header} structure contains an array of 21
+sparse structures, along with a similar @code{isextended} flag
+that the header had. There can be an indeterminate number of such
address@hidden to describe a sparse file.
+
address@hidden @asis
+
address@hidden @code{REGTYPE}
address@hidden @code{AREGTYPE}
+These flags represent a regular file. In order to be compatible
+with older versions of @command{tar}, a @code{typeflag} value of
address@hidden should be silently recognized as a regular file.
+New archives should be created using @code{REGTYPE}. Also, for
+backward compatibility, @command{tar} treats a regular file whose name
+ends with a slash as a directory.
+
address@hidden @code{LNKTYPE}
+This flag represents a file linked to another file, of any type,
+previously archived. Such files are identified in Unix by each
+file having the same device and inode number. The linked-to name is
+specified in the @code{linkname} field with a trailing null.
+
address@hidden @code{SYMTYPE}
+This represents a symbolic link to another file. The linked-to name
+is specified in the @code{linkname} field with a trailing null.
+
address@hidden @code{CHRTYPE}
address@hidden @code{BLKTYPE}
+These represent character special files and block special files
+respectively. In this case the @code{devmajor} and @code{devminor}
+fields will contain the major and minor device numbers respectively.
+Operating systems may map the device specifications to their own
+local specification, or may ignore the entry.
+
address@hidden @code{DIRTYPE}
+This flag specifies a directory or sub-directory. The directory
+name in the @code{name} field should end with a slash. On systems where
+disk allocation is performed on a directory basis, the @code{size} field
+will contain the maximum number of bytes (which may be rounded to
+the nearest disk block allocation unit) which the directory may
+hold. A @code{size} field of zero indicates no such limiting. Systems
+which do not support limiting in this manner should ignore the
address@hidden field.
+
address@hidden @code{FIFOTYPE}
+This specifies a FIFO special file. Note that the archiving of a
+FIFO file archives the existence of this file and not its contents.
+
address@hidden @code{CONTTYPE}
+This specifies a contiguous file, which is the same as a normal
+file except that, in operating systems which support it, all its
+space is allocated contiguously on the disk. Operating systems
+which do not allow contiguous allocation should silently treat this
+type as a normal file.
+
address@hidden @code{A} @dots{} @code{Z}
+These are reserved for custom implementations. Some of these are
+used in the @acronym{GNU} modified format, as described below.
+
address@hidden table
+
+Other values are reserved for specification in future revisions of
+the P1003 standard, and should not be used by any @command{tar} program.
+
+The @code{magic} field indicates that this archive was output in
+the P1003 archive format. If this field contains @code{TMAGIC},
+the @code{uname} and @code{gname} fields will contain the ASCII
+representation of the owner and group of the file respectively.
+If found, the user and group IDs are used rather than the values in
+the @code{uid} and @code{gid} fields.
+
+For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
+169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
+IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
+(section E.4.48) for @cite{pax - Portable archive interchange}.
+
address@hidden Extensions
address@hidden @acronym{GNU} Extensions to the Archive Format
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+The @acronym{GNU} format uses additional file types to describe new types of
+files in an archive. These are listed below.
+
address@hidden @code
address@hidden GNUTYPE_DUMPDIR
address@hidden 'D'
+This represents a directory and a list of files created by the
address@hidden (@option{-G}) option. The @code{size} field gives the total
+size of the associated list of files. Each file name is preceded by
+either a @samp{Y} (the file should be in this archive) or an @samp{N}.
+(The file is a directory, or is not stored in the archive.) Each file
+name is terminated by a null. There is an additional null after the
+last file name.
+
address@hidden GNUTYPE_MULTIVOL
address@hidden 'M'
+This represents a file continued from another volume of a multi-volume
+archive created with the @option{--multi-volume} (@option{-M}) option. The
original
+type of the file is not given here. The @code{size} field gives the
+maximum size of this piece of the file (assuming the volume does
+not end before the file is written out). The @code{offset} field
+gives the offset from the beginning of the file where this part of
+the file begins. Thus @code{size} plus @code{offset} should equal
+the original size of the file.
+
address@hidden GNUTYPE_SPARSE
address@hidden 'S'
+This flag indicates that we are dealing with a sparse file. Note
+that archiving a sparse file requires special operations to find
+holes in the file, which mark the positions of these holes, along
+with the number of bytes of data to be found after the hole.
+
address@hidden GNUTYPE_VOLHDR
address@hidden 'V'
+This file type is used to mark the volume header that was given with
+the @address@hidden (@option{-V @var{archive-label}}) option when the archive
was created. The @code{name}
+field contains the @code{name} given after the @address@hidden (@option{-V
@var{archive-label}}) option.
+The @code{size} field is zero. Only the first file in each volume
+of an archive should have this type.
+
address@hidden table
+
+You may have trouble reading a @acronym{GNU} format archive on a
address@hidden system if the options @option{--incremental} (@option{-G}),
address@hidden (@option{-M}), @option{--sparse} (@option{-S}), or
@address@hidden (@option{-V @var{archive-label}}) were
+used when writing the archive. In general, if @command{tar} does not
+use the @acronym{GNU}-added fields of the header, other versions of
address@hidden should be able to read the archive. Otherwise, the
address@hidden program will give an error, the most likely one being a
+checksum error.
+
address@hidden Sparse Formats
address@hidden Storing Sparse Files
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden sparse formats
address@hidden sparse versions
+The notion of sparse file, and the ways of handling it from the point
+of view of @acronym{GNU} @command{tar} user have been described in detail in
address@hidden This chapter describes the internal format @acronym{GNU}
@command{tar}
+uses to store such files.
+
+The support for sparse files in @acronym{GNU} @command{tar} has a long
history. The
+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
address@hidden GNU} sparse format and in spite of the fact that its design
+contained many flaws, it was the only format @acronym{GNU} @command{tar}
supported
+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
+improved in versions 1.15.2 (November, 2005) and 1.15.92 (June,
+2006).
+
+In addition to GNU sparse format, @acronym{GNU} @command{tar} is able to read
and
+extract sparse files archived by @command{star}.
+
+The following subsections describe each format in detail.
+
address@hidden
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
address@hidden menu
+
address@hidden Old GNU Format
address@hidden Old GNU Format
+
address@hidden sparse formats, Old GNU
address@hidden Old GNU sparse format
+The format introduced some time around 1990 (v. 1.09). It was
+designed on top of standard @code{ustar} headers in such an
+unfortunate way that some of its fields overwrote fields required by
+POSIX.
+
+An old GNU sparse header is designated by type @samp{S}
+(@code{GNUTYPE_SPARSE}) and has the following layout:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.20 0.40
address@hidden Offset @tab Size @tab Name @tab Data type @tab Contents
address@hidden 0 @tab 345 @tab @tab N/A @tab Not used.
address@hidden 345 @tab 12 @tab atime @tab Number @tab
@code{atime} of the file.
address@hidden 357 @tab 12 @tab ctime @tab Number @tab
@code{ctime} of the file .
address@hidden 369 @tab 12 @tab offset @tab Number @tab For
+multivolume archives: the offset of the start of this volume.
address@hidden 381 @tab 4 @tab @tab N/A @tab Not used.
address@hidden 385 @tab 1 @tab @tab N/A @tab Not used.
address@hidden 386 @tab 96 @tab sp @tab @code{sparse_header} @tab
(4 entries) File map.
address@hidden 482 @tab 1 @tab isextended @tab Bool @tab
@code{1} if an
+extension sparse header follows, @code{0} otherwise.
address@hidden 483 @tab 12 @tab realsize @tab Number @tab Real
size of the file.
address@hidden multitable
+
+Each of @code{sparse_header} object at offset 386 describes a single
+data chunk. It has the following structure:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.60
address@hidden Offset @tab Size @tab Data type @tab Contents
address@hidden 0 @tab 12 @tab Number @tab Offset of the
+beginning of the chunk.
address@hidden 12 @tab 12 @tab Number @tab Size of the chunk.
address@hidden multitable
+
+If the member contains more than four chunks, the @code{isextended}
+field of the header has the value @code{1} and the main header is
+followed by one or more @dfn{extension headers}. Each such header has
+the following structure:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.20 0.40
address@hidden Offset @tab Size @tab Name @tab Data type @tab Contents
address@hidden 0 @tab 21 @tab sp @tab @code{sparse_header} @tab
+(21 entires) File map.
address@hidden 504 @tab 1 @tab isextended @tab Bool @tab @code{1}
if an
+extension sparse header follows, or @code{0} otherwise.
address@hidden multitable
+
+A header with @code{isextended=0} ends the map.
+
address@hidden PAX 0
address@hidden PAX Format, Versions 0.0 and 0.1
+
address@hidden sparse formats, v.0.0
+There are two formats available in this branch. The version @code{0.0}
+is the initial version of sparse format used by @command{tar}
+versions 1.14--1.15.1. The sparse file map is kept in extended
+(@code{x}) PAX header variables:
+
address@hidden @code
address@hidden GNU.sparse.size, extended header variable
address@hidden GNU.sparse.size
+Real size of the stored file
+
address@hidden GNU.sparse.numblocks
address@hidden GNU.sparse.numblocks, extended header variable
+Number of blocks in the sparse map
+
address@hidden GNU.sparse.offset
address@hidden GNU.sparse.offset, extended header variable
+Offset of the data block
+
address@hidden GNU.sparse.numbytes
address@hidden GNU.sparse.numbytes, extended header variable
+Size of the data block
address@hidden table
+
+The latter two variables repeat for each data block, so the overall
+structure is like this:
+
address@hidden
address@hidden
address@hidden
address@hidden
+repeat @var{numblocks} times
+ address@hidden
+ address@hidden
+end repeat
address@hidden group
address@hidden smallexample
+
+This format presented the following two problems:
+
address@hidden 1
address@hidden
+Whereas the POSIX specification allows a variable to appear multiple
+times in a header, it requires that only the last occurrence be
+meaningful. Thus, multiple ocurrences of @code{GNU.sparse.offset} and
address@hidden are conficting with the POSIX specs.
+
address@hidden
+Attempting to extract such archives using a third-party @command{tar}s
+results in extraction of sparse files in @emph{compressed 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
+state. However, posix-aware @command{tar}s will usually ignore the
+unknown variables, which makes restoring the file more
+difficult. @xref{extracting sparse v.0.x, Extraction of sparse
+members in v.0.0 format}, for the detailed description of how to
+restore such members using non-GNU @command{tar}s.
address@hidden enumerate
+
address@hidden sparse formats, v.0.1
address@hidden @command{tar} 1.15.2 introduced sparse format version
@code{0.1}, which
+attempted to solve these problems. As its predecessor, this format
+stores sparse map in the extended POSIX header. It retains
address@hidden and @code{GNU.sparse.numblocks} variables, but
+instead of @code{GNU.sparse.offset}/@code{GNU.sparse.numbytes} pairs
+it uses a single variable:
+
address@hidden @code
address@hidden GNU.sparse.map
address@hidden 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}...]"
address@hidden table
+
+To address the 2nd problem, the @code{name} field in @code{ustar}
+is replaced with a special name, constructed using the following pattern:
+
address@hidden
+%d/GNUSparseFile.%p/%f
address@hidden smallexample
+
address@hidden GNU.sparse.name, extended header variable
+The real name of the sparse file is stored in the variable
address@hidden Thus, those @command{tar} implementations
+that are not aware of GNU extensions will at least extract the files
+into separate directories, giving the user a possibility to expand it
+afterwards. @xref{extracting sparse v.0.x, Extraction of sparse
+members in v.0.1 format}, for the detailed description of how to
+restore such members using non-GNU @command{tar}s.
+
+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.
+
address@hidden PAX 1
address@hidden PAX Format, Version 1.0
+
address@hidden sparse formats, v.1.0
+The version @code{1.0} of sparse format was introduced with @acronym{GNU}
@command{tar}
+1.15.92. Its main objective was to make the resulting file
+extractable with little effort even by non-posix aware @command{tar}
+implementations. Starting from this version, the extended header
+preceding a sparse member always contains the following variables that
+identify the format being used:
+
address@hidden @code
address@hidden GNU.sparse.major
address@hidden GNU.sparse.major, extended header variable
+Major version
+
address@hidden GNU.sparse.minor
address@hidden GNU.sparse.minor, extended header variable
+Minor version
address@hidden table
+
+The @code{name} field in @code{ustar} header contains a special name,
+constructed using the following pattern:
+
address@hidden
+%d/GNUSparseFile.%p/%f
address@hidden smallexample
+
address@hidden GNU.sparse.name, extended header variable, in v.1.0
address@hidden GNU.sparse.realsize, extended header variable
+The real name of the sparse file is stored in the variable
address@hidden The real size of the file is stored in the
+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
+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
+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 @acronym{GNU}
@command{tar}.
address@hidden Recovery}, for the detailed information on how to extract
+sparse members without @acronym{GNU} @command{tar}.
+
+
address@hidden Snapshot Files
address@hidden Format of the Incremental Snapshot Files
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2005 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
+ A @dfn{snapshot file} (or @dfn{directory file}) is created during
+incremental backups (@pxref{Incremental Dumps}). It
+contains the status of the filesystem at the time of the dump and is
+used to determine which files were modified since the last backup.
+
+ @acronym{GNU} @command{tar} version 1.15.92 supports two snapshot file
+formats. The first format, called @dfn{format 0}, is the one used by
address@hidden @command{tar} versions up to 1.15.1. The second format, called
@dfn{format
+1} is an extended version of this format, that contains more metadata
+and allows for further extensions.
+
+ @samp{Format 0} snapshot file begins with a line containing a
+decimal number that represents the UNIX timestamp of the beginning of
+the last archivation. This line is followed by directory metadata
+descriptions, one per line. Each description has the following format:
+
address@hidden
address@hidden@var{dev} @var{inode} @var{name}
address@hidden smallexample
+
address@hidden
+where optional @var{nfs} is a single plus character (@samp{+}) if this
+directory is located on an NFS-mounted partition, @var{dev} and
address@hidden are the device and inode numbers of the directory, and
address@hidden is the directory name.
+
+ @samp{Format 1} snapshot file begins with a line specifying the
+format of the file. This line has the following structure:
+
address@hidden
address@hidden address@hidden@address@hidden
address@hidden smallexample
+
address@hidden
+where @var{tar-version} is the version of @acronym{GNU} @command{tar}
implementation
+that created this snapshot, and @var{incr-format-version} is the
+version number of the snapshot format (in this case @samp{1}).
+
+ The following line contains two decimal numbers, representing the
+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.
+
+ Following lines contain directory metadate, one line per
+directory. The line format is:
+
address@hidden
address@hidden@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
address@hidden smallexample
+
address@hidden
+where @var{mtime-sec} and @var{mtime-nsec} represent the last
+modification time of this directory with nanosecond precision;
address@hidden, @var{dev}, @var{inode} and @var{name} have the same meaning
+as with @samp{format 0}.
+
+
address@hidden End of snapshot.texi
+
+
+
address@hidden Dumpdir
address@hidden Dumpdir
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
+ Incremental archives keep information about contents of each
+dumped directory in special data blocks called @dfn{dumpdirs}.
+
+ Dumpdir is a sequence of entries of the following form:
+
address@hidden
address@hidden @var{filename} \0
address@hidden smallexample
+
address@hidden
+where @var{C} is one of the @dfn{control codes} described below,
address@hidden is the name of the file @var{C} operates upon, and
address@hidden represents a nul character (ASCII 0). The white space
+characters were added for readability, real dumpdirs do not contain
+them.
+
+ Each dumpdir ends with a single nul character.
+
+ The following table describes control codes and their meanings:
+
address@hidden @samp
address@hidden Y
address@hidden is contained in the archive.
+
address@hidden N
address@hidden was present in the directory at the time the archive
+was made, yet it was not dumped to the archive, because it had not
+changed since the last backup.
+
address@hidden D
address@hidden is a directory.
+
address@hidden R
+This code requests renaming of the @var{filename} to the name
+specified with the following @samp{T} command.
+
address@hidden T
+Specify target file name for @samp{R} command (see below).
+
address@hidden X
+Specify @dfn{temporary directory} name for a rename operation (see below).
address@hidden table
+
+ Codes @samp{Y}, @samp{N} and @samp{D} require @var{filename} argument
+to be a relative file name to the directory this dumpdir describes,
+whereas codes @samp{R}, @samp{T} and @samp{X} require their argument
+to be an absolute file name.
+
+ The three codes @samp{R}, @samp{T} and @samp{X} specify a
address@hidden operation}. In the simplest case it is:
+
address@hidden
address@hidden@file{dest}\0
address@hidden smallexample
+
address@hidden
+which means ``rename file @file{source} to file @file{dest}''.
+
+ However, there are cases that require using a @dfn{temporary
+directory}. For example, consider the following scenario:
+
address@hidden 1
address@hidden
+Previous run dumped a directory @file{foo} which contained the
+following three directories:
+
address@hidden
+a
+b
+c
address@hidden smallexample
+
address@hidden
+They were renamed @emph{cyclically}, so that:
+
address@hidden
address@hidden became @file{b}
address@hidden became @file{c}
address@hidden became @file{a}
address@hidden example
+
address@hidden
+New incremental dump was made.
address@hidden enumerate
+
+ This case cannot be handled by three successive renames, since
+renaming @file{a} to @file{b} will destroy existing directory.
+To handle such case a temporary directory is required. @acronym{GNU}
@command{tar}
+will create the following dumpdir (newlines have been added for
+readability):
+
address@hidden
address@hidden
+Xfoo\0
+Rfoo/a\0T\0
+Rfoo/b\0Tfoo/c\0
+Rfoo/c\0Tfoo/a\0
+R\0Tfoo/a\0
address@hidden group
address@hidden smallexample
+
+ The first command, @samp{Xfoo\0}, instructs the extractor to create a
+temporary directory in the directory @file{foo}. Second command,
address@hidden/aT\0}, says ``rename file @file{foo/a} to the temporary
+directory that has just been created'' (empty file name after a
+command means use temporary directory). Third and fourth commands
+work as usual, and, finally, the last command, @samp{R\0Tfoo/a\0}
+tells tar to rename the temporary directory to @file{foo/a}.
+
+ The exact placement of a dumpdir in the archive depends on the
+archive format (@pxref{Formats}):
+
address@hidden
address@hidden PAX archives
+
+In PAX archives, dumpdir is stored in the extended header of the
+corresponding directory, in variable @code{GNU.dumpdir}.
+
address@hidden GNU and old GNU archives
+
+These formats implement special header type @samp{D}, which is similar
+to ustar header @samp{5} (directory), except that it preceeds a data
+block containing the dumpdir.
address@hidden itemize
+
address@hidden End of dumpdir.texi
+
+
address@hidden Genfile
address@hidden Genfile
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2005, 2006 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden genfile
+ This appendix describes @command{genfile}, an auxiliary program
+used in the GNU tar testsuite. If you are not interested in developing
+GNU tar, skip this appendix.
+
+ Initially, @command{genfile} was used to generate data files for
+the testsuite, hence its name. However, new operation modes were being
+implemented as the testsuite grew more sophisticated, and now
address@hidden is a multi-purpose instrument.
+
+ There are three basic operation modes:
+
address@hidden @asis
address@hidden File Generation
+ This is the default mode. In this mode, @command{genfile}
+generates data files.
+
address@hidden File Status
+ In this mode @command{genfile} displays status of specified files.
+
address@hidden Synchronous Execution.
+ In this mode @command{genfile} executes the given program with
address@hidden option and executes a set of actions when
+specified checkpoints are reached.
address@hidden table
+
address@hidden
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
address@hidden menu
+
address@hidden Generate Mode
address@hidden Generate Mode
+
address@hidden Generate Mode, @command{genfile}
address@hidden @command{genfile}, generate mode
address@hidden @command{genfile}, create file
+ In this mode @command{genfile} creates a data file for the test
+suite. The size of the file is given with the @option{--length}
+(@option{-l}) option. By default the file contents is written to the
+standard output, this can be changed using @option{--file}
+(@option{-f}) command line option. Thus, the following two commands
+are equivalent:
+
address@hidden
address@hidden
+genfile --length 100 > outfile
+genfile --length 100 --file outfile
address@hidden group
address@hidden smallexample
+
+ If @option{--length} is not given, @command{genfile} will
+generate an empty (zero-length) file.
+
address@hidden @command{genfile}, reading a list of file names
+ You can instruct @command{genfile} to create several files at one
+go, by giving it @option{--files-from} (@option{-T}) option followed
+by a name of file containing a list of file names. Using dash
+(@samp{-}) instead of the file name causes @command{genfile} to read
+file list from the standard input. For example:
+
address@hidden
address@hidden
+# Read file names from file @file{file.list}
+genfile --files-from file.list
+# Read file names from standard input
+genfile --files-from -
address@hidden group
address@hidden smallexample
+
address@hidden File lists separated by NUL characters
+ The list file is supposed to contain one file name per line. To
+use file lists separated by ASCII NUL character, use @option{--null}
+(@option{-0}) command line option:
+
address@hidden
+genfile --null --files-from file.list
address@hidden smallexample
+
address@hidden pattern, @command{genfile}
+ The default data pattern for filling the generated file consists
+of first 256 letters of ASCII code, repeated enough times to fill the
+entire file. This behavior can be changed with @option{--pattern}
+option. This option takes a mandatory argument, specifying pattern
+name to use. Currently two patterns are implemented:
+
address@hidden @option
address@hidden --pattern=default
+ The default pattern as described above.
+
address@hidden --pattern=zero
+ Fills the file with zeroes.
address@hidden table
+
+ If no file name was given, the program exits with the code
address@hidden Otherwise, it exits with @code{0} only if it was able to
+create a file of the specified length.
+
address@hidden Sparse files, creating using @command{genfile}
address@hidden @command{genfile}, creating sparse files
+ Special option @option{--sparse} (@option{-s}) instructs
address@hidden to create a sparse file. Sparse files consist of
address@hidden fragments}, separated by @dfn{holes} or blocks of zeros. On
+many operating systems, actual disk storage is not allocated for
+holes, but they are counted in the length of the file. To create a
+sparse file, @command{genfile} should know where to put data fragments,
+and what data to use to fill them. So, when @option{--sparse} is given
+the rest of the command line specifies a so-called @dfn{file map}.
+
+ The file map consists of any number of @dfn{fragment
+descriptors}. Each descriptor is composed of two values: a number,
+specifying fragment offset from the end of the previous fragment or,
+for the very first fragment, from the beginning of the file, and
address@hidden string}, i.e. a string of characters, specifying the
+pattern to fill the fragment with. File offset can be suffixed with
+the following quantifiers:
+
address@hidden @samp
address@hidden k
address@hidden K
+The number is expressed in kilobytes.
address@hidden m
address@hidden M
+The number is expressed in megabytes.
address@hidden g
address@hidden G
+The number is expressed in gigabytes.
address@hidden table
+
+ For each letter in contents string @command{genfile} will generate
+a @dfn{block} of data, filled with this letter and will write it to
+the fragment. The size of block is given by @option{--block-size}
+option. It defaults to 512. Thus, if the string consists of @var{n}
+characters, the resulting file fragment will contain
address@hidden@address@hidden of data.
+
+ Last fragment descriptor can have only file offset part. In this
+case @command{genfile} will create a hole at the end of the file up to
+the given offset.
+
+ For example, consider the following invocation:
+
address@hidden
+genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
address@hidden smallexample
+
address@hidden
+It will create 3101184-bytes long file of the following structure:
+
address@hidden @columnfractions .35 .20 .45
address@hidden Offset @tab Length @tab Contents
address@hidden 0 @tab 4*512=2048 @tab Four 512-byte blocks, filled with
+letters @samp{A}, @samp{B}, @samp{C} and @samp{D}.
address@hidden 2048 @tab 1046528 @tab Zero bytes
address@hidden 1050624 @tab 5*512=2560 @tab Five blocks, filled with letters
address@hidden, @samp{F}, @samp{G}, @samp{H}, @samp{I}.
address@hidden 1053184 @tab 2048000 @tab Zero bytes
address@hidden multitable
+
+ The exit code of @command{genfile --status} command is @code{0}
+only if created file is actually sparse.
+
address@hidden Status Mode
address@hidden Status Mode
+
+ In status mode, @command{genfile} prints file system status for
+each file specified in the command line. This mode is toggled by
address@hidden (@option{-S}) command line option. An optional argument to this
+option specifies output @dfn{format}: a comma-separated list of
address@hidden stat} fields to be displayed. This list can contain
+following identifiers @allow-recursion
address@hidden
+:
+
address@hidden @asis
address@hidden name
+ The file name.
+
address@hidden dev
address@hidden st_dev
+ Device number in decimal.
+
address@hidden ino
address@hidden st_ino
+ Inode number.
+
address@hidden address@hidden
address@hidden address@hidden
+ File mode in octal. Optional @var{number} specifies octal mask to
+be applied to the mode before outputting. For example, @code{--stat
+mode.777} will preserve lower nine bits of it. Notice, that you can
+use any punctuation caracter in place of @samp{.}.
+
address@hidden nlink
address@hidden st_nlink
+ Number of hard links.
+
address@hidden uid
address@hidden st_uid
+ User ID of owner.
+
address@hidden gid
address@hidden st_gid
+ Group ID of owner.
+
address@hidden size
address@hidden st_size
+ File size in decimal.
+
address@hidden blksize
address@hidden st_blksize
+ The size in bytes of each file block.
+
address@hidden blocks
address@hidden st_blocks
+ Number of blocks allocated.
+
address@hidden atime
address@hidden st_atime
+ Time of last access.
+
address@hidden mtime
address@hidden st_mtime
+ Time of last modification
+
address@hidden ctime
address@hidden st_ctime
+ Time of last status change
+
address@hidden sparse
+ A boolean value indicating whether the file is @samp{sparse}.
address@hidden table
+
+ Modification times are displayed in @acronym{UTC} as
address@hidden timestamps, unless suffixed with @samp{H} (for
+``human-readable''), as in @samp{ctimeH}, in which case usual
address@hidden tv} output format is used.
+
+ The default output format is: @samp{name,dev,ino,mode,
+nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}.
+
+ For example, the following command will display file names and
+corresponding times of last access for each file in the current working
+directory:
+
address@hidden
+genfile --stat=name,atime *
address@hidden smallexample
+
address@hidden Exec Mode
address@hidden Exec Mode
+
address@hidden Exec Mode, @command{genfile}
+ This mode is designed for testing the behavior of @code{paxutils}
+commands when some of the files change during archiving. It is an
+experimental mode.
+
+ The @samp{Exec Mode} is toggled by @option{--run} command line
+option (or its alias @option{-r}). The argument to this option gives
+the command line to be executed. The actual command line is
+constructed by inserting @option{--checkpoint} option between the
+command name and its first argument (if any). Due to this, the
+argument to @option{--run} may not use traditional @command{tar}
+option syntax, i.e. the following is wrong:
+
address@hidden
+# Wrong!
+genfile --run 'tar cf foo bar'
address@hidden smallexample
+
address@hidden
+
+Use the following syntax instead:
+
address@hidden
+genfile --run 'tar -cf foo bar'
address@hidden smallexample
+
+ The rest of command line after @option{--run} or its equivalent
+specifies checkpoint values and actions to be executed upon reaching
+them. Checkpoint values are introduced with @option{--checkpoint}
+command line option. Argument to this option is the number of
+checkpoint in decimal.
+
+ Any number of @dfn{actions} may be specified after a
+checkpoint. Available actions are
+
address@hidden @option
address@hidden --cut @var{file}
address@hidden --truncate @var{file}
+ Truncate @var{file} to the size specified by previous
address@hidden option (or 0, if it is not given).
+
address@hidden --append @var{file}
+ Append data to @var{file}. The size of data and its pattern are
+given by previous @option{--length} and @option{pattern} options.
+
address@hidden --touch @var{file}
+ Update the access and modification times of @var{file}. These
+timestamps are changed to the current time, unless @option{--date}
+option was given, in which case they are changed to the specified
+time. Argument to @option{--date} option is a date specification in
+an almost arbitrary format (@pxref{Date input formats}).
+
address@hidden --exec @var{command}
+ Execute given shell command.
+
address@hidden table
+
+ Option @option{--verbose} instructs @command{genfile} to print on
+standard output notifications about checkpoints being executed and to
+verbosely describe exit status of the command.
+
+ While the command is being executed its standard output remains
+connected to descriptor 1. All messages it prints to file descriptor
+2, except checkpoint notifications, are forwarded to standard
+error.
+
+ @command{Genfile} exits with the exit status of the executed command.
+
address@hidden Free Software Needs Free Documentation
address@hidden Free Software Needs Free Documentation
address@hidden free documentation
+
+The biggest deficiency in the free software community today is not in
+the software---it is the lack of good free documentation that we can
+include with the free software. Many of our most important
+programs do not come with free reference manuals and free introductory
+texts. Documentation is an essential part of any software package;
+when an important free software package does not come with a free
+manual and a free tutorial, that is a major gap. We have many such
+gaps today.
+
+Consider Perl, for instance. The tutorial manuals that people
+normally use are non-free. How did this come about? Because the
+authors of those manuals published them with restrictive terms---no
+copying, no modification, source files not available---which exclude
+them from the free software world.
+
+That wasn't the first time this sort of thing happened, and it was far
+from the last. Many times we have heard a GNU user eagerly describe a
+manual that he is writing, his intended contribution to the community,
+only to learn that he had ruined everything by signing a publication
+contract to make it non-free.
+
+Free documentation, like free software, is a matter of freedom, not
+price. The problem with the non-free manual is not that publishers
+charge a price for printed copies---that in itself is fine. (The Free
+Software Foundation sells printed copies of manuals, too.) The
+problem is the restrictions on the use of the manual. Free manuals
+are available in source code form, and give you permission to copy and
+modify. Non-free manuals do not allow this.
+
+The criteria of freedom for a free manual are roughly the same as for
+free software. Redistribution (including the normal kinds of
+commercial redistribution) must be permitted, so that the manual can
+accompany every copy of the program, both on-line and on paper.
+
+Permission for modification of the technical content is crucial too.
+When people modify the software, adding or changing features, if they
+are conscientious they will change the manual too---so they can
+provide accurate and clear documentation for the modified program. A
+manual that leaves you no choice but to write a new manual to document
+a changed version of the program is not really available to our
+community.
+
+Some kinds of limits on the way modification is handled are
+acceptable. For example, requirements to preserve the original
+author's copyright notice, the distribution terms, or the list of
+authors, are ok. It is also no problem to require modified versions
+to include notice that they were modified. Even entire sections that
+may not be deleted or changed are acceptable, as long as they deal
+with nontechnical topics (like this one). These kinds of restrictions
+are acceptable because they don't obstruct the community's normal use
+of the manual.
+
+However, it must be possible to modify all the @emph{technical}
+content of the manual, and then distribute the result in all the usual
+media, through all the usual channels. Otherwise, the restrictions
+obstruct the use of the manual, it is not free, and we need another
+manual to replace it.
+
+Please spread the word about this issue. Our community continues to
+lose manuals to proprietary publishing. If we spread the word that
+free software needs free reference manuals and free tutorials, perhaps
+the next person who wants to contribute by writing documentation will
+realize, before it is too late, that only free manuals contribute to
+the free software community.
+
+If you are writing documentation, please insist on publishing it under
+the GNU Free Documentation License or another free documentation
+license. Remember that this decision requires your approval---you
+don't have to let the publisher decide. Some commercial publishers
+will use a free license if you insist, but they will not propose the
+option; it is up to you to raise the issue and say firmly that this is
+what you want. If the publisher you are dealing with refuses, please
+try other publishers. If you're not sure whether a proposed license
+is free, write to @email{licensing@@gnu.org}.
+
+You can encourage commercial publishers to sell more free, copylefted
+manuals and tutorials by buying them, and particularly by buying
+copies from the publishers that paid for their writing or for major
+improvements. Meanwhile, try to avoid buying non-free documentation
+at all. Check the distribution terms of a manual before you buy it,
+and insist that whoever seeks your business must respect your freedom.
+Check the history of the book, and try reward the publishers that have
+paid or pay the authors to work on it.
+
+The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
address@hidden://www.fsf.org/doc/other-free-books.html}.
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.2, November 2002
+
address@hidden
+Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
+51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
address@hidden Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
address@hidden for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
address@hidden
+Preserve any Warranty Disclaimers.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with...Texts.'' line with this:
+
address@hidden
address@hidden
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
address@hidden Index of Command Line Options
address@hidden Index of Command Line Options
+
+This appendix contains an index of all @acronym{GNU} @command{tar} long
command line
+options. The options are listed without the preceeding double-dash.
+For a cross-reference of short command line options, @ref{Short Option
Summary}.
+
address@hidden op
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
address@hidden
address@hidden
Index: res_info/texi_tar/tar.texi.first
===================================================================
RCS file: res_info/texi_tar/tar.texi.first
diff -N res_info/texi_tar/tar.texi.first
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ res_info/texi_tar/tar.texi.first 2 Aug 2009 13:46:16 -0000 1.1
@@ -0,0 +1,13592 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden tar.info
address@hidden UPDATED 26 June 2006
address@hidden UPDATED-MONTH June 2006
address@hidden EDITION 1.15.92
address@hidden VERSION 1.15.92
address@hidden GNU tar 1.15.92
address@hidden odd
+
address@hidden
+
address@hidden
address@hidden %**end of header
+
address@hidden Maintenance notes:
address@hidden 1. Pay attention to @FIXME{}s and @UNREVISED{}s
address@hidden 2. Before creating final variant:
address@hidden 2.1. Run `make check-options' to make sure all options are
properly
address@hidden documented;
address@hidden 2.2. Run `make master-menu' (see comment before the master
menu).
+
address@hidden This is part of GNU tar manual.
address@hidden Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
address@hidden 2003, 2004, 2006 Free Software Foundation, Inc.
address@hidden See file tar.texi for copying conditions.
+
address@hidden This file contains support for 'renditions' by Fran@,{c}ois
Pinard
address@hidden I extended it by adding a FIXME_FOOTNOTE variable, which controls
address@hidden whether FIXME information should be placed in footnotes or
address@hidden inlined. --gray
+
address@hidden
======================================================================
address@hidden This document has three levels of rendition: PUBLISH, DISTRIB or
PROOF,
address@hidden as decided by @set symbols. The PUBLISH rendition does not show
address@hidden notes or marks asking for revision. Most users will prefer
having more
address@hidden information, even if this information is not fully revised for
adequacy,
address@hidden so DISTRIB is the default for distributions. The PROOF rendition
address@hidden show all marks to the point of ugliness, but is nevertheless
useful to
address@hidden those working on the manual itself.
address@hidden
======================================================================
+
address@hidden Set this symbol if you wish FIXMEs to appear in footnotes,
instead
address@hidden of being inserted into the text.
address@hidden @set PROOF_FOOTNOTED
+
address@hidden DISTRIB
+
+
address@hidden RENDITION FTP release, version
+
+
address@hidden Output marks for nodes needing revision, but not in PUBLISH
rendition.
+
address@hidden UNREVISED
address@hidden PUBLISH
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden ifclear
address@hidden macro
+
address@hidden Output various FIXME information only in PROOF rendition.
+
address@hidden FIXME{string}
address@hidden
address@hidden
address@hidden PROOF
address@hidden PROOF_FOOTNOTED
address@hidden@strong{FIXME:} \string\}
address@hidden ifset
address@hidden PROOF_FOOTNOTED
address@hidden
address@hidden<FIXME>} \string\ @strong{</>}
address@hidden cartouche
address@hidden ifclear
address@hidden ifset
+
address@hidden macro
+
address@hidden FIXME-ref{string}
address@hidden
address@hidden PROOF
address@hidden<REF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden FIXME-pxref{string}
address@hidden
address@hidden PROOF
address@hidden<PXREF>} \string\ @strong{</>}
address@hidden ifset
+
address@hidden macro
+
address@hidden FIXME-xref{string}
address@hidden
address@hidden PROOF
address@hidden<XREF>} \string\ @strong{</>}
address@hidden ifset
address@hidden macro
+
address@hidden End of rendition.texi
address@hidden This is part of GNU tar manual.
address@hidden Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
address@hidden 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
address@hidden See file tar.texi for copying conditions.
+
address@hidden GNUTAR
address@hidden @command{tar}
address@hidden macro
+
address@hidden xopindex{option,text}
address@hidden address@hidden, \text\}
address@hidden macro
+
address@hidden opsummary{option}
address@hidden ANCHOR--\option\
address@hidden ANCHOR--\option\ 1
address@hidden
address@hidden ifclear
address@hidden, summary}
address@hidden macro
+
+
+
address@hidden op
+
address@hidden Put everything in one index (arbitrarily chosen to be the
concept index).
address@hidden fn cp
address@hidden ky cp
address@hidden pg cp
address@hidden vr cp
+
+
address@hidden Archiving
address@hidden
+* Tar: (tar). Making tape (or disk) archives.
address@hidden direntry
+
address@hidden Individual utilities
address@hidden
+* tar: (tar)tar invocation. Invoking @acronym{GNU}
@command{tar}.
address@hidden direntry
+
address@hidden @acronym{GNU} @command{tar}
+
+
address@hidden Top
address@hidden @acronym{GNU} tar: an archiver tool
+
+
+This manual is for @acronym{GNU} @command{tar} (version
+1.15.92, 26 June 2006), which creates and extracts files
+from archives.
+
+Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
+2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled "GNU Free Documentation License".
+
+(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
+this GNU Manual. Buying copies from GNU Press supports the FSF in
+developing GNU and promoting software freedom.''
address@hidden quotation
+
address@hidden file archival
address@hidden archiving files
+
+The first part of this master menu lists the major nodes in this Info
+document. The rest of the menu lists all the lower level nodes.
+
address@hidden The master menu goes here.
address@hidden
address@hidden NOTE: To update it from within Emacs, make sure mastermenu.el is
address@hidden loaded and run texinfo-master-menu.
address@hidden To update it from the command line, run
address@hidden
address@hidden make master-menu
+
address@hidden
+* Introduction::
+* Tutorial::
+* tar invocation::
+* operations::
+* Backups::
+* Choosing::
+* Date input formats::
+* Formats::
+* Media::
+
+Appendices
+
+* Changes::
+* Configuring Help Summary::
+* Tar Internals::
+* Genfile::
+* Free Software Needs Free Documentation::
+* Copying This Manual::
+* Index of Command Line Options::
+* Index::
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @acronym{GNU} @command{tar} Authors
+* Reports:: Reporting bugs or suggestions
+
+Tutorial Introduction to @command{tar}
+
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
+
+Two Frequently Used Options
+
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
+
+How to Create Archives
+
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
+
+How to List Archives
+
+* list dir::
+
+How to Extract Members from an Archive
+
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
+
+Invoking @acronym{GNU} @command{tar}
+
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
+
+The Three Option Styles
+
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
+
+All @command{tar} Options
+
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
+
address@hidden @command{tar} Operations
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+Advanced @acronym{GNU} @command{tar} Operations
+
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
+
+How to Add Files to Existing Archives: @option{--append}
+
+* appending files:: Appending Files to an Archive
+* multiple::
+
+Updating an Archive
+
+* how to update::
+
+Options Used by @option{--create}
+
+* override:: Overriding File Metadata.
+* Ignore Failed Read::
+
+Options Used by @option{--extract}
+
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+
+Options to Help Read Archives
+
+* read full records::
+* Ignore Zeros::
+
+Changing How @command{tar} Writes Files
+
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
+
+Coping with Scarce Resources
+
+* Starting File::
+* Same Order::
+
+Performing Backups and Restoring Files
+
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental
Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
+
+Setting Parameters for Backups and Restoration
+
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+
+Choosing Files and Names for @command{tar}
+
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+
+Reading Names from a File
+
+* nul::
+
+Excluding Some Files
+
+* problems with exclude::
+
+Wildcards Patterns and Matching
+
+* controlling pattern-matching::
+
+Crossing File System Boundaries
+
+* directory:: Changing Directory
+* absolute:: Absolute File Names
+
+Date input formats
+
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
+
+Controlling the Archive Format
+
+* Portability:: Making @command{tar} Archives More Portable
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* cpio:: Comparison of @command{tar} and @command{cpio}
+
+Making @command{tar} Archives More Portable
+
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
+
address@hidden @command{tar} and @acronym{POSIX} @command{tar}
+
+* PAX keywords:: Controlling Extended Header Keywords.
+
+How to Extract GNU-Specific Data Using Other @command{tar} Implementations
+
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
+
+Using Less Space through Compression
+
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+
+Tapes and Other Archive Media
+
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
+
+Blocking
+
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
+
+Many Archives on One Tape
+
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
+
+Using Multiple Tapes
+
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
+
+Tar Internals
+
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
+
+Storing Sparse Files
+
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
+
+Genfile
+
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
address@hidden detailmenu
address@hidden menu
+
address@hidden Introduction
address@hidden Introduction
+
address@hidden @command{tar} creates
+and manipulates @dfn{archives} which are actually collections of
+many other files; the program provides users with an organized and
+systematic method for controlling a large amount of data.
+The name ``tar'' originally came from the phrase ``Tape ARchive'', but
+archives need not (and these days, typically do not) reside on tapes.
+
address@hidden
+* Book Contents:: What this Book Contains
+* Definitions:: Some Definitions
+* What tar Does:: What @command{tar} Does
+* Naming tar Archives:: How @command{tar} Archives are Named
+* Authors:: @acronym{GNU} @command{tar} Authors
+* Reports:: Reporting bugs or suggestions
address@hidden menu
+
address@hidden Book Contents
address@hidden What this Book Contains
+
+The first part of this chapter introduces you to various terms that will
+recur throughout the book. It also tells you who has worked on @acronym{GNU}
@command{tar}
+and its documentation, and where you should send bug reports
+or comments.
+
+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
+chapters to make sense. It moves from topic to topic in a logical,
+progressive order, building on information already explained.
+
+Although the tutorial is paced and structured to allow beginners to
+learn how to use @command{tar}, it is not intended solely for beginners.
+The tutorial explains how to use the three most frequently used
+operations (@samp{create}, @samp{list}, and @samp{extract}) as well as
+two frequently used options (@samp{file} and @samp{verbose}). The other
+chapters do not refer to the tutorial frequently; however, if a section
+discusses something which is a complex variant of a basic concept, there
+may be a cross reference to that basic concept. (The entire book,
+including the tutorial, assumes that the reader understands some basic
+concepts of using a Unix-type operating system; @pxref{Tutorial}.)
+
+The third chapter presents the remaining five operations, and
+information about using @command{tar} options and option syntax.
+
address@hidden
address@hidden
+ The other chapters are meant to be used as a
+reference. Each chapter presents everything that needs to be said
+about a specific topic.
+
+One of the chapters (@pxref{Date input formats}) exists in its
+entirety in other @acronym{GNU} manuals, and is mostly self-contained.
+In addition, one section of this manual (@pxref{Standard}) contains a
+big quote which is taken directly from @command{tar} sources.
+
+In general, we give both long and short (abbreviated) option names
+at least once in each section where the relevant option is covered, so
+that novice readers will become familiar with both styles. (A few
+options have no short versions, and the relevant sections will
+indicate this.)
+
address@hidden Definitions
address@hidden Some Definitions
+
address@hidden archive
address@hidden tar archive
+The @command{tar} program is used to create and manipulate @command{tar}
+archives. An @dfn{archive} is a single file which contains the contents
+of many files, while still identifying the names of the files, their
+owner(s), and so forth. (In addition, archives record access
+permissions, user and group, size in bytes, and data modification time.
+Some archives also record the file names in each archived directory, as
+well as other file and directory information.) You can use @command{tar}
+to @dfn{create} a new archive in a specified directory.
+
address@hidden member
address@hidden archive member
address@hidden file name
address@hidden member name
+The files inside an archive are called @dfn{members}. Within this
+manual, we use the term @dfn{file} to refer only to files accessible in
+the normal ways (by @command{ls}, @command{cat}, and so forth), and the term
address@hidden to refer only to the members of an archive. Similarly, a
address@hidden name} is the name of a file, as it resides in the file system,
+and a @dfn{member name} is the name of an archive member within the
+archive.
+
address@hidden extraction
address@hidden unpacking
+The term @dfn{extraction} refers to the process of copying an archive
+member (or multiple members) into a file in the file system. Extracting
+all the members of an archive is often called @dfn{extracting the
+archive}. The term @dfn{unpack} can also be used to refer to the
+extraction of many or all the members of an archive. Extracting an
+archive does not destroy the archive's structure, just as creating an
+archive does not destroy the copies of the files that exist outside of
+the archive. You may also @dfn{list} the members in a given archive
+(this is often thought of as ``printing'' them to the standard output,
+or the command line), or @dfn{append} members to a pre-existing archive.
+All of these operations can be performed using @command{tar}.
+
address@hidden What tar Does
address@hidden What @command{tar} Does
+
address@hidden tar
+The @command{tar} program provides the ability to create @command{tar}
+archives, as well as various other kinds of manipulation. For example,
+you can use @command{tar} on previously created archives to extract files,
+to store additional files, or to update or list files which were already
+stored.
+
+Initially, @command{tar} archives were used to store files conveniently on
+magnetic tape. The name @command{tar} comes from this use; it stands for
address@hidden @code{ar}chiver. Despite the utility's name, @command{tar} can
+direct its output to available devices, files, or other programs (using
+pipes). @command{tar} may even access remote devices or files (as archives).
+
+You can use @command{tar} archives in many ways. We want to stress a few
+of them: storage, backup, and transportation.
+
address@hidden
address@hidden
+
address@hidden @asis
address@hidden Storage
+Often, @command{tar} archives are used to store related files for
+convenient file transfer over a network. For example, the
address@hidden Project distributes its software bundled into
address@hidden archives, so that all the files relating to a particular
+program (or set of related programs) can be transferred as a single
+unit.
+
+A magnetic tape can store several files in sequence. However, the tape
+has no names for these files; it only knows their relative position on
+the tape. One way to store several files on one tape and retain their
+names is by creating a @command{tar} archive. Even when the basic transfer
+mechanism can keep track of names, as FTP can, the nuisance of handling
+multiple files, directories, and multiple links makes @command{tar}
+archives useful.
+
+Archive files are also used for long-term storage. You can think of
+this as transportation from the present into the future. (It is a
+science-fiction idiom that you can move through time as well as in
+space; the idea here is that @command{tar} can be used to move archives in
+all dimensions, even time!)
+
address@hidden Backup
+Because the archive created by @command{tar} is capable of preserving
+file information and directory structure, @command{tar} is commonly
+used for performing full and incremental backups of disks. A backup
+puts a collection of files (possibly pertaining to many users and
+projects) together on a disk or a tape. This guards against
+accidental destruction of the information in those files.
address@hidden @command{tar} has special features that allow it to be
+used to make incremental and full dumps of all the files in a
+file system.
+
address@hidden Transportation
+You can create an archive on one system, transfer it to another system,
+and extract the contents there. This allows you to transport a group of
+files from one system to another.
address@hidden table
+
address@hidden Naming tar Archives
address@hidden How @command{tar} Archives are Named
+
+Conventionally, @command{tar} archives are given names ending with
address@hidden This is not necessary for @command{tar} to operate properly,
+but this manual follows that convention in order to accustom readers to
+it and to make examples more clear.
+
address@hidden tar file
address@hidden entry
address@hidden tar entry
+Often, people refer to @command{tar} archives as address@hidden files,'' and
+archive members as ``files'' or ``entries''. For people familiar with
+the operation of @command{tar}, this causes no difficulty. However, in
+this manual, we consistently refer to ``archives'' and ``archive
+members'' to make learning to use @command{tar} easier for novice users.
+
address@hidden Authors
address@hidden @acronym{GNU} @command{tar} Authors
+
address@hidden @command{tar} was originally written by John Gilmore,
+and modified by many people. The @acronym{GNU} enhancements were
+written by Jay Fenlason, then Joy Kendall, and the whole package has
+been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois
+Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
+numerous and kind users.
+
+We wish to stress that @command{tar} is a collective work, and owes much to
+all those people who reported problems, offered solutions and other
+insights, or shared their thoughts and suggestions. An impressive, yet
+partial list of those contributors can be found in the @file{THANKS}
+file from the @acronym{GNU} @command{tar} distribution.
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
+Jay Fenlason put together a draft of a @acronym{GNU} @command{tar}
+manual, borrowing notes from the original man page from John Gilmore.
+This was withdrawn in version 1.11. Thomas Bushnell, n/BSG and Amy
+Gorin worked on a tutorial and manual for @acronym{GNU} @command{tar}.
+Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
+taking information from all these sources and merging them. Melissa
+Weisshaus finally edited and redesigned the book to create version
+1.12. The book for versions from 1.14 up to 1.15.92 were edited
+by the current maintainer, Sergey Poznyakoff.
+
+For version 1.12, Daniel Hagerty contributed a great deal of technical
+consulting. In particular, he is the primary author of @ref{Backups}.
+
+In July, 2003 @acronym{GNU} @command{tar} was put on CVS at savannah.gnu.org
+(see @url{http://savannah.gnu.org/projects/tar}), and
+active development and maintenance work has started
+again. Currently @acronym{GNU} @command{tar} is being maintained by Paul
Eggert, Sergey
+Poznyakoff and Jeff Bailey.
+
+Support for @acronym{POSIX} archives was added by Sergey Poznyakoff.
+
address@hidden Reports
address@hidden Reporting bugs or suggestions
+
address@hidden bug reports
address@hidden reporting bugs
+If you find problems or have suggestions about this program or manual,
+please report them to @file{bug-tar@@gnu.org}.
+
+When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it. @allow-recursion
address@hidden
+.
+
address@hidden Tutorial
address@hidden Tutorial Introduction to @command{tar}
+
+This chapter guides you through some basic examples of three @command{tar}
+operations: @option{--create}, @option{--list}, and @option{--extract}. If
+you already know how to use some other version of @command{tar}, then you
+may not need to read this chapter. This chapter omits most complicated
+details about how @command{tar} works.
+
address@hidden
+* assumptions::
+* stylistic conventions::
+* basic tar options:: Basic @command{tar} Operations and Options
+* frequent operations::
+* Two Frequent Options::
+* create:: How to Create Archives
+* list:: How to List Archives
+* extract:: How to Extract Members from an Archive
+* going further::
address@hidden menu
+
address@hidden assumptions
address@hidden Assumptions this Tutorial Makes
+
+This chapter is paced to allow beginners to learn about @command{tar}
+slowly. At the same time, we will try to cover all the basic aspects of
+these three operations. In order to accomplish both of these tasks, we
+have made certain assumptions about your knowledge before reading this
+manual, and the hardware you will be using:
+
address@hidden @bullet
address@hidden
+Before you start to work through this tutorial, you should understand
+what the terms ``archive'' and ``archive member'' mean
+(@pxref{Definitions}). In addition, you should understand something
+about how Unix-type operating systems work, and you should know how to
+use some basic utilities. For example, you should know how to create,
+list, copy, rename, edit, and delete files and directories; how to
+change between directories; and how to figure out where you are in the
+file system. You should have some basic understanding of directory
+structure and how files are named according to which directory they are
+in. You should understand concepts such as standard output and standard
+input, what various definitions of the term ``argument'' mean, and the
+differences between relative and absolute path names. @allow-recursion
address@hidden
+
+
address@hidden
+This manual assumes that you are working from your own home directory
+(unless we state otherwise). In this tutorial, you will create a
+directory to practice @command{tar} commands in. When we show path names,
+we will assume that those paths are relative to your home directory.
+For example, my home directory path is @file{/home/fsf/melissa}. All of
+my examples are in a subdirectory of the directory named by that path
+name; the subdirectory is called @file{practice}.
+
address@hidden
+In general, we show examples of archives which exist on (or can be
+written to, or worked with from) a directory on a hard disk. In most
+cases, you could write those archives to, or work with them on any other
+device, such as a tape drive. However, some of the later examples in
+the tutorial and next chapter will not work on tape drives.
+Additionally, working with tapes is much more complicated than working
+with hard disks. For these reasons, the tutorial does not cover working
+with tape drives. @xref{Media}, for complete information on using
address@hidden archives with tape drives.
+
address@hidden
address@hidden
+
address@hidden itemize
+
address@hidden stylistic conventions
address@hidden Stylistic Conventions
+
+In the examples, @samp{$} represents a typical shell prompt. It
+precedes lines you should type; to make this more clear, those lines are
+shown in @kbd{this font}, as opposed to lines which represent the
+computer's response; those lines are shown in @code{this font}, or
+sometimes @samp{like this}.
+
address@hidden When we have lines which are too long to be
address@hidden displayed in any other way, we will show them like this:
+
address@hidden basic tar options
address@hidden Basic @command{tar} Operations and Options
+
address@hidden can take a wide variety of arguments which specify and define
+the actions it will have on the particular set of files or the archive.
+The main types of arguments to @command{tar} fall into one of two classes:
+operations, and options.
+
+Some arguments fall into a class called @dfn{operations}; exactly one of
+these is both allowed and required for any instance of using @command{tar};
+you may @emph{not} specify more than one. People sometimes speak of
address@hidden modes}. You are in a particular operating mode when you
+have specified the operation which specifies it; there are eight
+operations in total, and thus there are eight operating modes.
+
+The other arguments fall into the class known as @dfn{options}. You are
+not required to specify any options, and you are allowed to specify more
+than one at a time (depending on the way you are using @command{tar} at
+that time). Some options are used so frequently, and are so useful for
+helping you type commands more carefully that they are effectively
+``required''. We will discuss them in this chapter.
+
+You can write most of the @command{tar} operations and options in any
+of three forms: long (mnemonic) form, short form, and old style. Some
+of the operations and options have no short or ``old'' forms; however,
+the operations and options which we will cover in this tutorial have
+corresponding abbreviations. @allow-recursion
address@hidden
+We will indicate those abbreviations appropriately to get
+you used to seeing them. (Note that the ``old style'' option forms
+exist in @acronym{GNU} @command{tar} for compatibility with Unix
address@hidden In this book we present a full discussion of this way
+of writing options and operations (@pxref{Old Options}), and we discuss
+the other two styles of writing options (@xref{Long Options}, and
address@hidden Options}).
+
+In the examples and in the text of this tutorial, we usually use the
+long forms of operations and options; but the ``short'' forms produce
+the same result and can make typing long @command{tar} commands easier.
+For example, instead of typing
+
address@hidden
address@hidden --create --verbose --file=afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+you can type
address@hidden
address@hidden -c -v -f afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+or even
address@hidden
address@hidden -cvf afiles.tar apple angst aspic}
address@hidden smallexample
+
address@hidden
+For more information on option syntax, see @ref{Advanced tar}. In
+discussions in the text, when we name an option by its long form, we
+also give the corresponding short option in parentheses.
+
+The term, ``option'', can be confusing at times, since ``operations''
+are often lumped in with the actual, @emph{optional} ``options'' in certain
+general class statements. For example, we just talked about ``short and
+long forms of options and operations''. However, experienced @command{tar}
+users often refer to these by shorthand terms such as, ``short and long
+options''. This term assumes that the ``operations'' are included, also.
+Context will help you determine which definition of ``options'' to use.
+
+Similarly, the term ``command'' can be confusing, as it is often used in
+two different ways. People sometimes refer to @command{tar} ``commands''.
+A @command{tar} @dfn{command} is the entire command line of user input
+which tells @command{tar} what to do --- including the operation, options,
+and any arguments (file names, pipes, other commands, etc). However,
+you will also sometimes hear the term ``the @command{tar} command''. When
+the word ``command'' is used specifically like this, a person is usually
+referring to the @command{tar} @emph{operation}, not the whole line.
+Again, use context to figure out which of the meanings the speaker
+intends.
+
address@hidden frequent operations
address@hidden The Three Most Frequently Used Operations
+
+Here are the three most frequently used operations (both short and long
+forms), as well as a brief description of their meanings. The rest of
+this chapter will cover how to use these operations in detail. We will
+present the rest of the operations in the next chapter.
+
address@hidden @option
address@hidden --create
address@hidden -c
+Create a new @command{tar} archive.
address@hidden --list
address@hidden -t
+List the contents of an archive.
address@hidden --extract
address@hidden -x
+Extract one or more members from an archive.
address@hidden table
+
address@hidden Two Frequent Options
address@hidden Two Frequently Used Options
+
+To understand how to run @command{tar} in the three operating modes listed
+previously, you also need to understand how to use two of the options to
address@hidden: @option{--file} (which takes an archive file as an argument)
+and @option{--verbose}. (You are usually not @emph{required} to specify
+either of these options when you run @command{tar}, but they can be very
+useful in making things more clear and helping you avoid errors.)
+
address@hidden
+* file tutorial::
+* verbose tutorial::
+* help tutorial::
address@hidden menu
+
address@hidden file tutorial
address@hidden The @option{--file} Option
+
address@hidden @option
address@hidden address@hidden, tutorial}
address@hidden address@hidden
address@hidden -f @var{archive-name}
+Specify the name of an archive file.
address@hidden table
+
+You can specify an argument for the @address@hidden (@option{-f
@var{archive-name}}) option whenever you
+use @command{tar}; this option determines the name of the archive file
+that @command{tar} will work on.
+
address@hidden TAPE
+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
+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
+attached, or the default is not meaningful, then @command{tar} will
+print an error message. The error message might look roughly like one
+of the following:
+
address@hidden
+tar: can't open /dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
address@hidden smallexample
+
address@hidden
+To avoid confusion, we recommend that you always specify an archive file
+name by using @address@hidden (@option{-f @var{archive-name}}) when writing
your @command{tar} commands.
+For more information on using the @address@hidden (@option{-f
@var{archive-name}}) option, see
address@hidden
+
address@hidden verbose tutorial
address@hidden The @option{--verbose} Option
+
address@hidden @option
address@hidden address@hidden, introduced}
address@hidden --verbose
address@hidden -v
+Show the files being worked on as @command{tar} is running.
address@hidden table
+
address@hidden (@option{-v}) shows details about the results of running
address@hidden This can be especially useful when the results might not be
+obvious. For example, if you want to see the progress of @command{tar} as
+it writes files into the archive, you can use the @option{--verbose}
+option. In the beginning, you may find it useful to use
address@hidden at all times; when you are more accustomed to
address@hidden, you will likely want to use it at certain times but not at
+others. We will use @option{--verbose} at times to help make something
+clear, and we will give many examples both using and not using
address@hidden to show the differences.
+
+Each instance of @option{--verbose} on the command line increases the
+verbosity level by one, so if you need more details on the output,
+specify it twice.
+
+When reading archives (@option{--list}, @option{--extract},
address@hidden), @command{tar} by default prints only the names of
+the members being extracted. Using @option{--verbose} will show a full,
address@hidden style member listing.
+
+In contrast, when writing archives (@option{--create}, @option{--append},
address@hidden), @command{tar} does not print file names by
+default. So, a single @option{--verbose} option shows the file names
+being added to the archive, while two @option{--verbose} options
+enable the full listing.
+
+For example, to create an archive in verbose mode:
+
address@hidden
+$ @kbd{tar -cvf afiles.tar apple angst aspic}
+apple
+angst
+aspic
address@hidden smallexample
+
address@hidden
+Creating the same archive with the verbosity level 2 could give:
+
address@hidden
+$ @kbd{tar -cvvf afiles.tar apple angst aspic}
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
+-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
address@hidden smallexample
+
address@hidden
+This works equally well using short or long forms of options. Using
+long forms, you would simply write out the mnemonic form of the option
+twice, like this:
+
address@hidden
+$ @kbd{tar --create --verbose --verbose @dots{}}
address@hidden smallexample
+
address@hidden
+Note that you must double the hyphens properly each time.
+
+Later in the tutorial, we will give examples using @address@hidden
+--verbose}}.
+
address@hidden member listing}
+The full output consists of six fields:
+
address@hidden @bullet
address@hidden File type and permissions in symbolic form.
+These are displayed in the same format as the first column of
address@hidden -l} output (@pxref{What information is listed,
+format=verbose, Verbose listing, fileutils, GNU file utilities}).
+
address@hidden Owner name and group separated by a slash character.
+If these data are not available (for example, when listing a @samp{v7} format
+archive), numeric ID values are printed instead.
+
address@hidden Size of the file, in bytes.
+
address@hidden File modification date in ISO 8601 format.
+
address@hidden File modification time.
+
address@hidden File name.
+If the name contains any special characters (white space, newlines,
+etc.) these are displayed in an unambiguous form using so called
address@hidden style}. For the detailed discussion of available styles
+and on how to use them, see @ref{quoting styles}.
+
+Depending on the file type, the name can be followed by some
+additional information, described in the following table:
+
address@hidden @samp
address@hidden -> @var{link-name}
+The file or archive member is a @dfn{symbolic link} and
address@hidden is the name of file it links to.
+
address@hidden link to @var{link-name}
+The file or archive member is a @dfn{hard link} and @var{link-name} is
+the name of file it links to.
+
address@hidden --Long Link--
+The archive member is an old GNU format long link. You will normally
+not encounter this.
+
address@hidden --Long Name--
+The archive member is an old GNU format long name. You will normally
+not encounter this.
+
address@hidden --Volume Header--
+The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}).
+
address@hidden --Continued at byte @var{n}--
+Encountered only at the beginning of a multy-volume archive
+(@pxref{Using Multiple Tapes}). This archive member is a continuation
+from the previous volume. The number @var{n} gives the offset where
+the original file was split.
+
address@hidden --Mangled file names--
+This archive member contains @dfn{mangled file names} declarations,
+a special member type that was used by early versions of @acronym{GNU}
@command{tar}.
+You probably will never encounter this, unless you are reading a very
+old archive.
+
address@hidden unknown file type @var{c}
+An archive member of unknown type. @var{c} is the type character from
+the archive header. If you encounter such a message, it means that
+either your archive contains proprietary member types @acronym{GNU}
@command{tar} is not
+able to handle, or the archive is corrupted.
address@hidden table
+
address@hidden itemize
+
+For example, here is an archive listing containing most of the special
+suffixes explained above:
+
address@hidden
address@hidden
+V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
+byte 32456--
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden smallexample
+
address@hidden help tutorial
address@hidden Getting Help: Using the @option{--help} Option
+
address@hidden @option
address@hidden help
address@hidden --help
+
+The @option{--help} option to @command{tar} prints out a very brief list of
+all operations and option available for the current version of
address@hidden available on your system.
address@hidden table
+
address@hidden create
address@hidden How to Create Archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Creation of the archive
address@hidden Archive, creation of
+One of the basic operations of @command{tar} is @option{--create}
(@option{-c}), which
+you use to create a @command{tar} archive. We will explain
address@hidden first because, in order to learn about the other
+operations, you will find it useful to have an archive available to
+practice on.
+
+To make this easier, in this section you will first create a directory
+containing three files. Then, we will show you how to create an
address@hidden (inside the new directory). Both the directory, and
+the archive are specifically for you to practice on. The rest of this
+chapter and the next chapter will show many examples using this
+directory and the files you will create: some of those files may be
+other directories and other archives.
+
+The three files you will archive in this example are called
address@hidden, @file{folk}, and @file{jazz}. The archive is called
address@hidden
+
+This section will proceed slowly, detailing how to use @option{--create}
+in @code{verbose} mode, and showing examples using both short and long
+forms. In the rest of the tutorial, and in the examples in the next
+chapter, we will proceed at a slightly quicker pace. This section
+moves more slowly to allow beginning users to understand how
address@hidden works.
+
address@hidden
+* prepare for examples::
+* Creating the archive::
+* create verbose::
+* short create::
+* create dir::
address@hidden menu
+
address@hidden prepare for examples
address@hidden Preparing a Practice Directory for Examples
+
+To follow along with this and future examples, create a new directory
+called @file{practice} containing files called @file{blues}, @file{folk}
+and @file{jazz}. The files can contain any information you like:
+ideally, they should contain information which relates to their names,
+and be of different lengths. Our examples assume that @file{practice}
+is a subdirectory of your home directory.
+
+Now @command{cd} to the directory named @file{practice}; @file{practice}
+is now your @dfn{working directory}. (@emph{Please note}: Although
+the full path name of this directory is
address@hidden/@var{homedir}/practice}, in our examples we will refer to
+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}.
+Because you just created the directory and the files and have changed to
+that directory, you probably don't need to do that this time.
+
+It is very important to make sure there isn't already a file in the
+working directory with the archive name you intend to use (in this case,
address@hidden), or that you don't care about its contents.
+Whenever you use @samp{create}, @command{tar} will erase the current
+contents of the file named by @address@hidden (@option{-f @var{archive-name}})
if it exists. @command{tar}
+will not tell you if you are about to overwrite an archive unless you
+specify an option which does this (@pxref{backup}, for the
+information on how to do so). To add files to an existing archive,
+you need to use a different option, such as @option{--append} (@option{-r});
see
address@hidden for information on how to do this.
+
address@hidden Creating the archive
address@hidden Creating the Archive
+
address@hidden address@hidden, introduced}
+To place the files @file{blues}, @file{folk}, and @file{jazz} into an
+archive named @file{collection.tar}, use the following command:
+
address@hidden
+$ @kbd{tar --create --file=collection.tar blues folk jazz}
address@hidden smallexample
+
+The order of the arguments is not very important, @emph{when using long
+option forms}. You could also say:
+
address@hidden
+$ @kbd{tar blues --create folk --file=collection.tar jazz}
address@hidden smallexample
+
address@hidden
+However, you can see that this order is harder to understand; this is
+why we will list the arguments in the order that makes the commands
+easiest to understand (and we encourage you to do the same when you use
address@hidden, to avoid errors).
+
+Note that the sequence
address@hidden@-collection.tar} is considered to be @emph{one} argument.
+If you substituted any other string of characters for
address@hidden, then that string would become the name of the
+archive file you create.
+
+The order of the options becomes more important when you begin to use
+short forms. With short forms, if you type commands in the wrong order
+(even if you type them correctly in all other ways), you may end up with
+results you don't expect. For this reason, it is a good idea to get
+into the habit of typing options in the order that makes inherent sense.
address@hidden create}, for more information on this.
+
+In this example, you type the command as shown above: @option{--create}
+is the operation which creates the new archive
+(@file{collection.tar}), and @option{--file} is the option which lets
+you give it the name you chose. The files, @file{blues}, @file{folk},
+and @file{jazz}, are now members of the archive, @file{collection.tar}
+(they are @dfn{file name arguments} to the @option{--create} operation.
address@hidden, for the detailed discussion on these.) Now that they are
+in the archive, they are called @emph{archive members}, not files.
+(@pxref{Definitions,members}).
+
+When you create an archive, you @emph{must} specify which files you
+want placed in the archive. If you do not specify any archive
+members, @acronym{GNU} @command{tar} will complain.
+
+If you now list the contents of the working directory (@command{ls}), you will
+find the archive file listed as well as the files you saw previously:
+
address@hidden
+blues folk jazz collection.tar
address@hidden smallexample
+
address@hidden
+Creating the archive @samp{collection.tar} did not destroy the copies of
+the files in the directory.
+
+Keep in mind that if you don't indicate an operation, @command{tar} will not
+run and will prompt you for one. If you don't name any files, @command{tar}
+will complain. You must have write access to the working directory,
+or else you will not be able to create an archive in that directory.
+
address@hidden: Do not attempt to use @option{--create} (@option{-c}) to add
files to
+an existing archive; it will delete the archive and write a new one.
+Use @option{--append} (@option{-r}) instead. @xref{append}.
+
address@hidden create verbose
address@hidden Running @option{--create} with @option{--verbose}
+
address@hidden address@hidden, using with @option{--verbose}}
address@hidden address@hidden, using with @option{--create}}
+If you include the @option{--verbose} (@option{-v}) option on the command line,
address@hidden will list the files it is acting on as it is working. In
+verbose mode, the @code{create} example above would appear as:
+
address@hidden
+$ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
+blues
+folk
+jazz
address@hidden smallexample
+
+This example is just like the example we showed which did not use
address@hidden, except that @command{tar} generated the remaining lines
+.
+
+In the rest of the examples in this chapter, we will frequently use
address@hidden mode so we can show actions or @command{tar} responses that
+you would otherwise not see, and which are important for you to
+understand.
+
address@hidden short create
address@hidden Short Forms with @samp{create}
+
+As we said before, the @option{--create} (@option{-c}) operation is one of the
most
+basic uses of @command{tar}, and you will use it countless times.
+Eventually, you will probably want to use abbreviated (or ``short'')
+forms of options. A full discussion of the three different forms that
+options can take appears in @ref{Styles}; for now, here is what the
+previous example (including the @option{--verbose} (@option{-v}) option) looks
like
+using short option forms:
+
address@hidden
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+blues
+folk
+jazz
address@hidden smallexample
+
address@hidden
+As you can see, the system responds the same no matter whether you use
+long or short option forms.
+
address@hidden
address@hidden
+ One difference between using
+short and long option forms is that, although the exact placement of
+arguments following options is no more specific when using short forms,
+it is easier to become confused and make a mistake when using short
+forms. For example, suppose you attempted the above example in the
+following way:
+
address@hidden
+$ @kbd{tar -cfv collection.tar blues folk jazz}
address@hidden smallexample
+
address@hidden
+In this case, @command{tar} will make an archive file called @file{v},
+containing the files @file{blues}, @file{folk}, and @file{jazz}, because
+the @samp{v} is the closest ``file name'' to the @option{-f} option, and
+is thus taken to be the chosen archive file name. @command{tar} will try
+to add a file called @file{collection.tar} to the @file{v} archive file;
+if the file @file{collection.tar} did not already exist, @command{tar} will
+report an error indicating that this file does not exist. If the file
address@hidden does already exist (e.g., from a previous command
+you may have run), then @command{tar} will add this file to the archive.
+Because the @option{-v} option did not get registered, @command{tar} will not
+run under @samp{verbose} mode, and will not report its progress.
+
+The end result is that you may be quite confused about what happened,
+and possibly overwrite a file. To illustrate this further, we will show
+you how an example we showed previously would look using short forms.
+
+This example,
+
address@hidden
+$ @kbd{tar blues --create folk --file=collection.tar jazz}
address@hidden smallexample
+
address@hidden
+is confusing as it is. When shown using short forms, however, it
+becomes much more so:
+
address@hidden
+$ @kbd{tar blues -c folk -f collection.tar jazz}
address@hidden smallexample
+
address@hidden
+It would be very easy to put the wrong string of characters
+immediately following the @option{-f}, but doing that could sacrifice
+valuable data.
+
+For this reason, we recommend that you pay very careful attention to
+the order of options and placement of file and archive names,
+especially when using short option forms. Not having the option name
+written out mnemonically can affect how well you remember which option
+does what, and therefore where different names have to be placed.
+
address@hidden create dir
address@hidden Archiving Directories
+
address@hidden Archiving Directories
address@hidden Directories, Archiving
+You can archive a directory by specifying its directory name as a
+file name argument to @command{tar}. The files in the directory will be
+archived relative to the working directory, and the directory will be
+re-created along with its contents when the archive is extracted.
+
+To archive a directory, first move to its superior directory. If you
+have followed the previous instructions in this tutorial, you should
+type:
+
address@hidden
+$ @kbd{cd ..}
+$
address@hidden smallexample
+
address@hidden
+This will put you into the directory which contains @file{practice},
+i.e., your home directory. Once in the superior directory, you can
+specify the subdirectory, @file{practice}, as a file name argument. To
+store @file{practice} in the new archive file @file{music.tar}, type:
+
address@hidden
+$ @kbd{tar --create --verbose --file=music.tar practice}
address@hidden smallexample
+
address@hidden
address@hidden should output:
+
address@hidden
+practice/
+practice/blues
+practice/folk
+practice/jazz
+practice/collection.tar
address@hidden smallexample
+
+Note that the archive thus created is not in the subdirectory
address@hidden, but rather in the current working directory---the
+directory from which @command{tar} was invoked. Before trying to archive a
+directory from its superior directory, you should make sure you have
+write access to the superior directory itself, not only the directory
+you are trying archive with @command{tar}. For example, you will probably
+not be able to store your home directory in an archive by invoking
address@hidden from the root directory; @xref{absolute}. (Note
+also that @file{collection.tar}, the original archive file, has itself
+been archived. @command{tar} will accept any file as a file to be
+archived, regardless of its content. When @file{music.tar} is
+extracted, the archive file @file{collection.tar} will be re-written
+into the file system).
+
+If you give @command{tar} a command such as
+
address@hidden
+$ @kbd{tar --create --file=foo.tar .}
address@hidden smallexample
+
address@hidden
address@hidden will report @samp{tar: ./foo.tar is the archive; not
+dumped}. This happens because @command{tar} creates the archive
address@hidden in the current directory before putting any files into
+it. Then, when @command{tar} attempts to add all the files in the
+directory @file{.} to the archive, it notices that the file
address@hidden/foo.tar} is the same as the archive @file{foo.tar}, and skips
+it. (It makes no sense to put an archive into itself.) @acronym{GNU}
@command{tar}
+will continue in this case, and create the archive
+normally, except for the exclusion of that one file. (@emph{Please
+note:} Other implementations of @command{tar} may not be so clever;
+they will enter an infinite loop when this happens, so you should not
+depend on this behavior unless you are certain you are running
address@hidden @command{tar}. In general, it is wise to always place the
archive outside
+of the directory being dumped.
+
address@hidden list
address@hidden How to List Archives
+
address@hidden list
+Frequently, you will find yourself wanting to determine exactly what a
+particular archive contains. You can use the @option{--list}
+(@option{-t}) operation to get the member names as they currently
+appear in the archive, as well as various attributes of the files at
+the time they were archived. For example, you can examine the archive
address@hidden that you created in the last section with the
+command,
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
address@hidden smallexample
+
address@hidden
+The output of @command{tar} would then be:
+
address@hidden
+blues
+folk
+jazz
address@hidden smallexample
+
address@hidden
+The archive @file{bfiles.tar} would list as follows:
+
address@hidden
+./birds
+baboon
+./box
address@hidden smallexample
+
address@hidden
+Be sure to use a @address@hidden (@option{-f
address@hidden) option just as with @option{--create}
+(@option{-c}) to specify the name of the archive.
+
address@hidden address@hidden, using with @option{--verbose}}
address@hidden address@hidden, using with @option{--list}}
+If you use the @option{--verbose} (@option{-v}) option with
address@hidden, then @command{tar} will print out a listing
+reminiscent of @address@hidden -l}}, showing owner, file size, and so
+forth. This output is described in detail in @ref{verbose member listing}.
+
+If you had used @option{--verbose} (@option{-v}) mode, the example
+above would look like:
+
address@hidden
+$ @kbd{tar --list --verbose --file=collection.tar folk}
+-rw-r--r-- myself user 62 1990-05-23 10:55 folk
address@hidden smallexample
+
address@hidden listing member and file names
address@hidden member and file names}
+It is important to notice that the output of @kbd{tar --list
+--verbose} does not necessarily match that produced by @kbd{tar
+--create --verbose} while creating the archive. It is because
address@hidden @command{tar}, unless told explicitly not to do so, removes some
directory
+prefixes from file names before storing them in the archive
+(@xref{absolute}, for more information). In other
+words, in verbose mode @acronym{GNU} @command{tar} shows @dfn{file names} when
creating
+an archive and @dfn{member names} when listing it. Consider this
+example:
+
address@hidden
address@hidden
+$ @kbd{tar cfv archive /etc/mail}
+tar: Removing leading `/' from member names
+/etc/mail/
+/etc/mail/sendmail.cf
+/etc/mail/aliases
+$ @kbd{tar tf archive}
+etc/mail/
+etc/mail/sendmail.cf
+etc/mail/aliases
address@hidden group
address@hidden smallexample
+
address@hidden show-stored-names
+ This default behavior can sometimes be inconvenient. You can force
address@hidden @command{tar} show member names when creating archive by
supplying
address@hidden option.
+
address@hidden @option
address@hidden --show-stored-names
+Print member (as opposed to @emph{file}) names when creating the archive.
address@hidden table
+
address@hidden File name arguments, using @option{--list} with
address@hidden address@hidden, using with file name arguments}
+You can specify one or more individual member names as arguments when
+using @samp{list}. In this case, @command{tar} will only list the
+names of members you identify. For example, @address@hidden --list
+--file=afiles.tar apple}} would only print @file{apple}.
+
+Because @command{tar} preserves paths, file names must be specified as
+they appear in the archive (i.e., relative to the directory from which
+the archive was created). Therefore, it is essential when specifying
+member names to @command{tar} that you give the exact member names.
+For example, @address@hidden --list --file=bfiles.tar birds}} would produce an
+error message something like @samp{tar: birds: Not found in archive},
+because there is no member named @file{birds}, only one named
address@hidden/birds}. While the names @file{birds} and @file{./birds} name
+the same file, @emph{member} names by default are compared verbatim.
+
+However, @address@hidden --list --file=bfiles.tar baboon}} would respond
+with @file{baboon}, because this exact member name is in the archive file
address@hidden If you are not sure of the exact file name,
+use @dfn{globbing patterns}, for example:
+
address@hidden
+$ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'}
address@hidden smallexample
+
address@hidden
+will list all members whose name contains @samp{b}. @xref{wildcards},
+for a detailed discussion of globbing patterns and related
address@hidden command line options.
+
address@hidden
+* list dir::
address@hidden menu
+
address@hidden list dir
address@hidden Listing the Contents of a Stored Directory
+
+To get information about the contents of an archived directory,
+use the directory name as a file name argument in conjunction with
address@hidden (@option{-t}). To find out file attributes, include the
address@hidden (@option{-v}) option.
+
+For example, to find out about files in the directory @file{practice}, in
+the archive file @file{music.tar}, type:
+
address@hidden
+$ @kbd{tar --list --verbose --file=music.tar practice}
address@hidden smallexample
+
address@hidden responds:
+
address@hidden
+drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
+-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
address@hidden smallexample
+
+When you use a directory name as a file name argument, @command{tar} acts on
+all the files (including sub-directories) in that directory.
+
address@hidden extract
address@hidden How to Extract Members from an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Extraction
address@hidden Retrieving files from an archive
address@hidden Resurrecting files from an archive
+
address@hidden extract
+Creating an archive is only half the job---there is no point in storing
+files in an archive if you can't retrieve them. The act of retrieving
+members from an archive so they can be used and manipulated as
+unarchived files again is called @dfn{extraction}. To extract files
+from an archive, use the @option{--extract} (@option{--get} or
address@hidden) operation. As with @option{--create}, specify the name
+of the archive with @option{--file} (@option{-f}) option. Extracting
+an archive does not modify the archive in any way; you can extract it
+multiple times if you want or need to.
+
+Using @option{--extract}, you can extract an entire archive, or specific
+files. The files can be directories containing other files, or not. As
+with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you
may use the short or the
+long form of the operation without affecting the performance.
+
address@hidden
+* extracting archives::
+* extracting files::
+* extract dir::
+* extracting untrusted archives::
+* failing commands::
address@hidden menu
+
address@hidden extracting archives
address@hidden Extracting an Entire Archive
+
+To extract an entire archive, specify the archive file name only, with
+no individual file names as arguments. For example,
+
address@hidden
+$ @kbd{tar -xvf collection.tar}
address@hidden smallexample
+
address@hidden
+produces this:
+
address@hidden
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
address@hidden smallexample
+
address@hidden extracting files
address@hidden Extracting Specific Files
+
+To extract specific archive members, give their exact member names as
+arguments, as printed by @option{--list} (@option{-t}). If you had
+mistakenly deleted one of the files you had placed in the archive
address@hidden earlier (say, @file{blues}), you can extract it
+from the archive without changing the archive's structure. Its
+contents will be identical to the original file @file{blues} that you
+deleted.
+
+First, make sure you are in the @file{practice} directory, and list the
+files in the directory. Now, delete the file, @samp{blues}, and list
+the files in the directory again.
+
+You can now extract the member @file{blues} from the archive file
address@hidden like this:
+
address@hidden
+$ @kbd{tar --extract --file=collection.tar blues}
address@hidden smallexample
+
address@hidden
+If you list the files in the directory again, you will see that the file
address@hidden has been restored, with its original permissions, data
+modification times, and address@hidden is only accidentally
+true, but not in general. Whereas modification times are always
+restored, in most cases, one has to be root for restoring the owner,
+and use a special option for restoring permissions. Here, it just
+happens that the restoring user is also the owner of the archived
+members, and that the current @code{umask} is compatible with original
+permissions.} (These parameters will be identical to those which
+the file had when you originally placed it in the archive; any changes
+you may have made before deleting the file from the file system,
+however, will @emph{not} have been made to the archive member.) The
+archive file, @samp{collection.tar}, is the same as it was before you
+extracted @samp{blues}. You can confirm this by running @command{tar} with
address@hidden (@option{-t}).
+
+Remember that as with other operations, specifying the exact member
+name is important. @address@hidden --extract --file=bfiles.tar birds}}
+will fail, because there is no member named @file{birds}. To extract
+the member named @file{./birds}, you must specify @address@hidden
+--extract --file=bfiles.tar ./birds}}. If you don't remember the
+exact member names, use @option{--list} (@option{-t}) option
+(@pxref{list}). You can also extract those members that match a
+specific @dfn{globbing pattern}. For example, to extract from
address@hidden all files that begin with @samp{b}, no matter their
+directory prefix, you could type:
+
address@hidden
+$ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'}
address@hidden smallexample
+
address@hidden
+Here, @option{--wildcards} instructs @command{tar} to treat
+command line arguments as globbing patterns and @option{--no-anchored}
+informs it that the patterns apply to member names after any @samp{/}
+delimiter. The use of globbing patterns is discussed in detail in
address@hidden
+
+You can extract a file to standard output by combining the above options
+with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard
+Output}).
+
+If you give the @option{--verbose} option, then @option{--extract}
+will print the names of the archive members as it extracts them.
+
address@hidden extract dir
address@hidden Extracting Files that are Directories
+
+Extracting directories which are members of an archive is similar to
+extracting other files. The main difference to be aware of is that if
+the extracted directory has the same name as any directory already in
+the working directory, then files in the extracted directory will be
+placed into the directory of the same name. Likewise, if there are
+files in the pre-existing directory with the same names as the members
+which you extract, the files from the extracted archive will replace
+the files already in the working directory (and possible
+subdirectories). This will happen regardless of whether or not the
+files in the working directory were more recent than those extracted
+(there exist, however, special options that alter this behavior
address@hidden).
+
+However, if a file was stored with a directory name as part of its file
+name, and that directory does not exist under the working directory when
+the file is extracted, @command{tar} will create the directory.
+
+We can demonstrate how to use @option{--extract} to extract a directory
+file with an example. Change to the @file{practice} directory if you
+weren't there, and remove the files @file{folk} and @file{jazz}. Then,
+go back to the parent directory and extract the archive
address@hidden You may either extract the entire archive, or you may
+extract only the files you just deleted. To extract the entire archive,
+don't give any file names as arguments after the archive name
address@hidden To extract only the files you deleted, use the
+following command:
+
address@hidden
+$ @kbd{tar -xvf music.tar practice/folk practice/jazz}
+practice/folk
+practice/jazz
address@hidden smallexample
+
address@hidden
+If you were to specify two @option{--verbose} (@option{-v}) options,
@command{tar}
+would have displayed more detail about the extracted files, as shown
+in the example below:
+
address@hidden
+$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
+-rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz
+-rw-r--r-- me user 20 1996-09-23 16:44 practice/folk
address@hidden smallexample
+
address@hidden
+Because you created the directory with @file{practice} as part of the
+file names of each of the files by archiving the @file{practice}
+directory as @file{practice}, you must give @file{practice} as part
+of the file names when you extract those files from the archive.
+
address@hidden extracting untrusted archives
address@hidden Extracting Archives from Untrusted Sources
+
+Extracting files from archives can overwrite files that already exist.
+If you receive an archive from an untrusted source, you should make a
+new directory and extract into that directory, so that you don't have
+to worry about the extraction overwriting one of your existing files.
+For example, if @file{untrusted.tar} came from somewhere else on the
+Internet, and you don't necessarily trust its contents, you can
+extract it as follows:
+
address@hidden
+$ @kbd{mkdir newdir}
+$ @kbd{cd newdir}
+$ @kbd{tar -xvf ../untrusted.tar}
address@hidden smallexample
+
+It is also a good practice to examine contents of the archive
+before extracting it, using @option{--list} (@option{-t}) option, possibly
combined
+with @option{--verbose} (@option{-v}).
+
address@hidden failing commands
address@hidden Commands That Will Fail
+
+Here are some sample commands you might try which will not work, and why
+they won't work.
+
+If you try to use this command,
+
address@hidden
+$ @kbd{tar -xvf music.tar folk jazz}
address@hidden smallexample
+
address@hidden
+you will get the following response:
+
address@hidden
+tar: folk: Not found in archive
+tar: jazz: Not found in archive
+$
address@hidden smallexample
+
address@hidden
+This is because these files were not originally @emph{in} the parent
+directory @file{..}, where the archive is located; they were in the
address@hidden directory, and their file names reflect this:
+
address@hidden
+$ @kbd{tar -tvf music.tar}
+practice/folk
+practice/jazz
+practice/rock
address@hidden smallexample
+
address@hidden
address@hidden
+
+
address@hidden
+Likewise, if you try to use this command,
+
address@hidden
+$ @kbd{tar -tvf music.tar folk jazz}
address@hidden smallexample
+
address@hidden
+you would get a similar response. Members with those names are not in the
+archive. You must use the correct member names, or wildcards, in order
+to extract the files from the archive.
+
+If you have forgotten the correct names of the files in the archive,
+use @address@hidden --list --verbose}} to list them correctly.
+
address@hidden
address@hidden
+
+
address@hidden going further
address@hidden Going Further Ahead in this Manual
+
address@hidden
address@hidden
+
+
address@hidden tar invocation
address@hidden Invoking @acronym{GNU} @command{tar}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+This chapter is about how one invokes the @acronym{GNU} @command{tar}
+command, from the command synopsis (@pxref{Synopsis}). There are
+numerous options, and many styles for writing them. One mandatory
+option specifies the operation @command{tar} should perform
+(@pxref{Operation Summary}), other options are meant to detail how
+this operation should be performed (@pxref{Option Summary}).
+Non-option arguments are not always interpreted the same way,
+depending on what the operation is.
+
+You will find in this chapter everything about option styles and rules for
+writing them (@pxref{Styles}). On the other hand, operations and options
+are fully described elsewhere, in other chapters. Here, you will find
+only synthetic descriptions for operations and options, together with
+pointers to other parts of the @command{tar} manual.
+
+Some options are so special they are fully described right in this
+chapter. They have the effect of inhibiting the normal operation of
address@hidden or else, they globally alter the amount of feedback the user
+receives about what is going on. These are the @option{--help} and
address@hidden (@pxref{help}), @option{--verbose} (@pxref{verbose})
+and @option{--interactive} options (@pxref{interactive}).
+
address@hidden
+* Synopsis::
+* using tar options::
+* Styles::
+* All Options::
+* help::
+* defaults::
+* verbose::
+* interactive::
address@hidden menu
+
address@hidden Synopsis
address@hidden General Synopsis of @command{tar}
+
+The @acronym{GNU} @command{tar} program is invoked as either one of:
+
address@hidden
address@hidden @address@hidden address@hidden@dots{}}
address@hidden @address@hidden address@hidden@dots{} address@hidden@dots{}
address@hidden@dots{}}
address@hidden smallexample
+
+The second form is for when old options are being used.
+
+You can use @command{tar} to store files in an archive, to extract them from
+an archive, and to do other types of archive manipulation. The primary
+argument to @command{tar}, which is called the @dfn{operation}, specifies
+which action to take. The other arguments to @command{tar} are either
address@hidden, which change the way @command{tar} performs an operation,
+or file names or archive members, which specify the files or members
address@hidden is to act on.
+
+You can actually type in arguments in any order, even if in this manual
+the options always precede the other arguments, to make examples easier
+to understand. Further, the option stating the main operation mode
+(the @command{tar} main command) is usually given first.
+
+Each @var{name} in the synopsis above is interpreted as an archive member
+name when the main command is one of @option{--compare}
+(@option{--diff}, @option{-d}), @option{--delete}, @option{--extract}
+(@option{--get}, @option{-x}), @option{--list} (@option{-t}) or
address@hidden (@option{-u}). When naming archive members, you
+must give the exact name of the member in the archive, as it is
+printed by @option{--list}. For @option{--append} (@option{-r}) and
address@hidden (@option{-c}), these @var{name} arguments specify
+the names of either files or directory hierarchies to place in the archive.
+These files or hierarchies should already exist in the file system,
+prior to the execution of the @command{tar} command.
+
address@hidden interprets relative file names as being relative to the
+working directory. @command{tar} will make all file names relative
+(by removing leading slashes when archiving or restoring files),
+unless you specify otherwise (using the @option{--absolute-names}
+option). @xref{absolute}, for more information about
address@hidden
+
+If you give the name of a directory as either a file name or a member
+name, then @command{tar} acts recursively on all the files and directories
+beneath that directory. For example, the name @file{/} identifies all
+the files in the file system to @command{tar}.
+
+The distinction between file names and archive member names is especially
+important when shell globbing is used, and sometimes a source of confusion
+for newcomers. @xref{wildcards}, for more information about globbing.
+The problem is that shells may only glob using existing files in the
+file system. Only @command{tar} itself may glob on archive members, so when
+needed, you must ensure that wildcard characters reach @command{tar} without
+being interpreted by the shell first. Using a backslash before @samp{*}
+or @samp{?}, or putting the whole argument between quotes, is usually
+sufficient for this.
+
+Even if @var{name}s are often specified on the command line, they
+can also be read from a text file in the file system, using the
address@hidden@var{file-of-names}} (@option{-T @var{file-of-names}}) option.
+
+If you don't use any file name arguments, @option{--append} (@option{-r}),
address@hidden and @option{--concatenate} (@option{--catenate},
address@hidden) will do nothing, while @option{--create} (@option{-c})
+will usually yield a diagnostic and inhibit @command{tar} execution.
+The other operations of @command{tar} (@option{--list},
address@hidden, @option{--compare}, and @option{--update})
+will act on the entire contents of the archive.
+
address@hidden exit status
address@hidden return status
+Besides successful exits, @acronym{GNU} @command{tar} may fail for
+many reasons. Some reasons correspond to bad usage, that is, when the
address@hidden command is improperly written. Errors may be
+encountered later, while encountering an error processing the archive
+or the files. Some errors are recoverable, in which case the failure
+is delayed until @command{tar} has completed all its work. Some
+errors are such that it would not meaningful, or at least risky, to
+continue processing: @command{tar} then aborts processing immediately.
+All abnormal exits, whether immediate or delayed, should always be
+clearly diagnosed on @code{stderr}, after a line stating the nature of
+the error.
+
address@hidden @command{tar} returns only a few exit statuses. I'm really
+aiming simplicity in that area, for now. If you are not using the
address@hidden @option{--diff}, @option{-d}) option, zero means
+that everything went well, besides maybe innocuous warnings. Nonzero
+means that something went wrong. Right now, as of today, ``nonzero''
+is almost always 2, except for remote operations, where it may be
+128.
+
address@hidden using tar options
address@hidden Using @command{tar} Options
+
address@hidden @command{tar} has a total of eight operating modes which
+allow you to perform a variety of tasks. You are required to choose
+one operating mode each time you employ the @command{tar} program by
+specifying one, and only one operation as an argument to the
address@hidden command (two lists of four operations each may be found
+at @ref{frequent operations} and @ref{Operations}). Depending on
+circumstances, you may also wish to customize how the chosen operating
+mode behaves. For example, you may wish to change the way the output
+looks, or the format of the files that you wish to archive may require
+you to do something special in order to make the archive look right.
+
+You can customize and control @command{tar}'s performance by running
address@hidden with one or more options (such as @option{--verbose}
+(@option{-v}), which we used in the tutorial). As we said in the
+tutorial, @dfn{options} are arguments to @command{tar} which are (as
+their name suggests) optional. Depending on the operating mode, you
+may specify one or more options. Different options will have different
+effects, but in general they all change details of the operation, such
+as archive format, archive name, or level of user interaction. Some
+options make sense with all operating modes, while others are
+meaningful only with particular modes. You will likely use some
+options frequently, while you will only use others infrequently, or
+not at all. (A full list of options is available in @pxref{All Options}.)
+
address@hidden TAR_OPTIONS, environment variable
address@hidden
+The @env{TAR_OPTIONS} environment variable specifies default options to
+be placed in front of any explicit options. For example, if
address@hidden is @samp{-v --unlink-first}, @command{tar} behaves as
+if the two options @option{-v} and @option{--unlink-first} had been
+specified before any explicit options. Option specifications are
+separated by whitespace. A backslash escapes the next character, so it
+can be used to specify an option containing whitespace or a backslash.
+
+Note that @command{tar} options are case sensitive. For example, the
+options @option{-T} and @option{-t} are different; the first requires an
+argument for stating the name of a file providing a list of @var{name}s,
+while the second does not require an argument and is another way to
+write @option{--list} (@option{-t}).
+
+In addition to the eight operations, there are many options to
address@hidden, and three different styles for writing both: long (mnemonic)
+form, short form, and old style. These styles are discussed below.
+Both the options and the operations can be written in any of these three
+styles.
+
address@hidden
address@hidden
+
+
address@hidden Styles
address@hidden The Three Option Styles
+
+There are three styles for writing operations and options to the command
+line invoking @command{tar}. The different styles were developed at
+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
+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
+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
+subtle, yet can often be very important; incorrect option placement
+can cause you to overwrite a number of important files. We urge you
+to note these differences, and only use the option style(s) which
+makes the most sense to you until you feel comfortable with the others.
+
+Some options @emph{may} take an argument. Such options may have at
+most long and short forms, they do not have old style equivalent. The
+rules for specifying an argument for such options are stricter than
+those for specifying mandatory arguments. Please, pay special
+attention to them.
+
address@hidden
+* Long Options:: Long Option Style
+* Short Options:: Short Option Style
+* Old Options:: Old Option Style
+* Mixing:: Mixing Option Styles
address@hidden menu
+
address@hidden Long Options
address@hidden Long Option Style
+
+Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with
two
+dashes in a row, e.g., @option{--list}. The long names are more clear than
+their corresponding short or old names. It sometimes happens that a
+single long option has many different different names which are
+synonymous, such as @option{--compare} and @option{--diff}. In addition,
+long option names can be given unique abbreviations. For example,
address@hidden can be used in place of @option{--create} because there is no
+other long option which begins with @samp{cre}. (One way to find
+this out is by trying it and seeing what happens; if a particular
+abbreviation could represent more than one option, @command{tar} will tell
+you that that abbreviation is ambiguous and you'll know that that
+abbreviation won't work. You may also choose to run @samp{tar --help}
+to see a list of options. Be aware that if you run @command{tar} with a
+unique abbreviation for the long name of an option you didn't want to
+use, you are stuck; @command{tar} will perform the command as ordered.)
+
+Long options are meant to be obvious and easy to remember, and their
+meanings are generally easier to discern than those of their
+corresponding short options (see below). For example:
+
address@hidden
+$ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
address@hidden smallexample
+
address@hidden
+gives a fairly good set of hints about what the command does, even
+for those not fully acquainted with @command{tar}.
+
+Long options which require arguments take those arguments
+immediately following the option name. There are two ways of
+specifying a mandatory argument. It can be separated from the
+option name either by an equal sign, or by any amount of
+white space characters. For example, the @option{--file} option (which
+tells the name of the @command{tar} archive) is given a file such as
address@hidden as argument by using any of the following notations:
address@hidden or @option{--file archive.tar}.
+
+In contrast, optional arguments must always be introduced using
+an equal sign. For example, the @option{--backup} option takes
+an optional argument specifying backup type. It must be used
+as @address@hidden
+
address@hidden Short Options
address@hidden Short Option Style
+
+Most options also have a @dfn{short option} name. Short options start with
+a single dash, and are followed by a single character, e.g., @option{-t}
+(which is equivalent to @option{--list}). The forms are absolutely
+identical in function; they are interchangeable.
+
+The short option names are faster to type than long option names.
+
+Short options which require arguments take their arguments immediately
+following the option, usually separated by white space. It is also
+possible to stick the argument right after the short option name, using
+no intervening space. For example, you might write @address@hidden
+archive.tar}} or @option{-farchive.tar} instead of using
address@hidden Both @address@hidden and
address@hidden@option{-f @var{archive-name}}} denote the option which indicates
a
+specific archive, here named @file{archive.tar}.
+
+Short options which take optional arguments take their arguments
+immediately following the option letter, @emph{without any intervening
+white space characters}.
+
+Short options' letters may be clumped together, but you are not
+required to do this (as compared to old options; see below). When
+short options are clumped as a set, use one (single) dash for them
+all, e.g., @address@hidden@command{tar} -cvf}}. Only the last option in
+such a set is allowed to have an address@hidden many
+options, the last of which has an argument, is a rather opaque way to
+write options. Some wonder if @acronym{GNU} @code{getopt} should not
+even be made helpful enough for considering such usages as invalid.}.
+
+When the options are separated, the argument for each option which requires
+an argument directly follows that option, as is usual for Unix programs.
+For example:
+
address@hidden
+$ @kbd{tar -c -v -b 20 -f /dev/rmt0}
address@hidden smallexample
+
+If you reorder short options' locations, be sure to move any arguments
+that belong to them. If you do not move the arguments properly, you may
+end up overwriting files.
+
address@hidden Old Options
address@hidden Old Option Style
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Like short options, @dfn{old options} are single letters. However, old options
+must be written together as a single clumped set, without spaces separating
+them or dashes preceding address@hidden that if you precede options
+with a dash, you are announcing the short option style instead of the
+old option style; short options are decoded differently.}. This set
+of letters must be the first to appear on the command line, after the
address@hidden program name and some white space; old options cannot appear
+anywhere else. The letter of an old option is exactly the same letter as
+the corresponding short option. For example, the old option @samp{t} is
+the same as the short option @option{-t}, and consequently, the same as the
+long option @option{--list}. So for example, the command @address@hidden
+cv}} specifies the option @option{-v} in addition to the operation @option{-c}.
+
+When options that need arguments are given together with the command,
+all the associated arguments follow, in the same order as the options.
+Thus, the example given previously could also be written in the old
+style as follows:
+
address@hidden
+$ @kbd{tar cvbf 20 /dev/rmt0}
address@hidden smallexample
+
address@hidden
+Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
+the argument of @option{-f}.
+
+On the other hand, this old style syntax makes it difficult to match
+option letters with their corresponding arguments, and is often
+confusing. In the command @address@hidden cvbf 20 /dev/rmt0}}, for example,
address@hidden is the argument for @option{-b}, @samp{/dev/rmt0} is the
+argument for @option{-f}, and @option{-v} does not have a corresponding
+argument. Even using short options like in @address@hidden -c -v -b 20 -f
+/dev/rmt0}} is clearer, putting all arguments next to the option they
+pertain to.
+
+If you want to reorder the letters in the old option argument, be
+sure to reorder any corresponding argument appropriately.
+
+This old way of writing @command{tar} options can surprise even experienced
+users. For example, the two commands:
+
address@hidden
address@hidden cfz archive.tar.gz file}
address@hidden -cfz archive.tar.gz file}
address@hidden smallexample
+
address@hidden
+are quite different. The first example uses @file{archive.tar.gz} as
+the value for option @samp{f} and recognizes the option @samp{z}. The
+second example, however, uses @file{z} as the value for option
address@hidden --- probably not what was intended.
+
+Old options are kept for compatibility with old versions of @command{tar}.
+
+This second example could be corrected in many ways, among which the
+following are equivalent:
+
address@hidden
address@hidden -czf archive.tar.gz file}
address@hidden -cf archive.tar.gz -z file}
address@hidden cf archive.tar.gz -z file}
address@hidden smallexample
+
address@hidden option syntax, traditional
+As far as we know, all @command{tar} programs, @acronym{GNU} and
address@hidden, support old options. @acronym{GNU} @command{tar}
+supports them not only for historical reasons, but also because many
+people are used to them. For compatibility with Unix @command{tar},
+the first argument is always treated as containing command and option
+letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
+equivalent to @address@hidden -c}:} both of them specify the
address@hidden (@option{-c}) command to create an archive.
+
address@hidden Mixing
address@hidden Mixing Option Styles
+
+All three styles may be intermixed in a single @command{tar} command,
+so long as the rules for each style are fully
address@hidden @acronym{GNU} @command{tar} version 1.11.6,
+a bug prevented intermixing old style options with long options in
+some cases.}. Old style options and either of the modern styles of
+options may be mixed within a single @command{tar} command. However,
+old style options must be introduced as the first arguments only,
+following the rule for old options (old options must appear directly
+after the @command{tar} command and some white space). Modern options
+may be given only after all arguments to the old options have been
+collected. If this rule is not respected, a modern option might be
+falsely interpreted as the value of the argument to one of the old
+style options.
+
+For example, all the following commands are wholly equivalent, and
+illustrate the many combinations and orderings of option styles.
+
address@hidden
address@hidden --create --file=archive.tar}
address@hidden --create -f archive.tar}
address@hidden --create -farchive.tar}
address@hidden --file=archive.tar --create}
address@hidden --file=archive.tar -c}
address@hidden -c --file=archive.tar}
address@hidden -c -f archive.tar}
address@hidden -c -farchive.tar}
address@hidden -cf archive.tar}
address@hidden -cfarchive.tar}
address@hidden -f archive.tar --create}
address@hidden -f archive.tar -c}
address@hidden -farchive.tar --create}
address@hidden -farchive.tar -c}
address@hidden c --file=archive.tar}
address@hidden c -f archive.tar}
address@hidden c -farchive.tar}
address@hidden cf archive.tar}
address@hidden f archive.tar --create}
address@hidden f archive.tar -c}
address@hidden fc archive.tar}
address@hidden smallexample
+
+On the other hand, the following commands are @emph{not} equivalent to
+the previous set:
+
address@hidden
address@hidden -f -c archive.tar}
address@hidden -fc archive.tar}
address@hidden -fcarchive.tar}
address@hidden -farchive.tarc}
address@hidden cfarchive.tar}
address@hidden smallexample
+
address@hidden
+These last examples mean something completely different from what the
+user intended (judging based on the example in the previous set which
+uses long options, whose intent is therefore very clear). The first
+four specify that the @command{tar} archive would be a file named
address@hidden, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc},
+respectively. The first two examples also specify a single non-option,
address@hidden argument having the value @samp{archive.tar}. The last
+example contains only old style option letters (repeating option
address@hidden twice), not all of which are meaningful (eg., @samp{.},
address@hidden, or @samp{i}), with no argument value. @allow-recursion
address@hidden
+
+
address@hidden All Options
address@hidden All @command{tar} Options
+
+The coming manual sections contain an alphabetical listing of all
address@hidden 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.
+
address@hidden
+* Operation Summary::
+* Option Summary::
+* Short Option Summary::
address@hidden menu
+
address@hidden Operation Summary
address@hidden Operations
+
address@hidden @option
+
address@hidden ANCHOR--append 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --append
address@hidden -r
+
+Appends files to the end of the archive. @xref{append}.
+
address@hidden ANCHOR--catenate 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --catenate
address@hidden -A
+
+Same as @option{--concatenate}. @xref{concatenate}.
+
address@hidden ANCHOR--compare 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --compare
address@hidden -d
+
+Compares archive members with their counterparts in the file
+system, and reports differences in file size, mode, owner,
+modification date and contents. @xref{compare}.
+
address@hidden ANCHOR--concatenate 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --concatenate
address@hidden -A
+
+Appends other @command{tar} archives to the end of the archive.
address@hidden
+
address@hidden ANCHOR--create 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --create
address@hidden -c
+
+Creates a new @command{tar} archive. @xref{create}.
+
address@hidden ANCHOR--delete 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --delete
+
+Deletes members from the archive. Don't try this on a archive on a
+tape! @xref{delete}.
+
address@hidden ANCHOR--diff 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --diff
address@hidden -d
+
+Same @option{--compare}. @xref{compare}.
+
address@hidden ANCHOR--extract 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --extract
address@hidden -x
+
+Extracts members from the archive into the file system. @xref{extract}.
+
address@hidden ANCHOR--get 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --get
address@hidden -x
+
+Same as @option{--extract}. @xref{extract}.
+
address@hidden ANCHOR--list 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --list
address@hidden -t
+
+Lists the members in an archive. @xref{list}.
+
address@hidden ANCHOR--update 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --update
address@hidden -u
+
+Adds files to the end of the archive, but only if they are newer than
+their counterparts already in the archive, or if they do not already
+exist in the archive. @xref{update}.
+
address@hidden table
+
address@hidden Option Summary
address@hidden @command{tar} Options
+
address@hidden @option
+
address@hidden ANCHOR--absolute-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --absolute-names
address@hidden -P
+
+Normally when creating an archive, @command{tar} strips an initial
address@hidden/} from member names. This option disables that behavior.
address@hidden
+
address@hidden ANCHOR--after-date 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --after-date
+
+(See @option{--newer}, @pxref{after})
+
address@hidden ANCHOR--anchored 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --anchored
+A pattern must match an initial subsequence of the name's components.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--atime-preserve 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --atime-preserve
address@hidden --atime-preserve=replace
address@hidden --atime-preserve=system
+
+Attempt to preserve the access time of files when reading them. This
+option currently is effective only on files that you own, unless you
+have superuser privileges.
+
address@hidden remembers the access time of a file
+before reading it, and then restores the access time afterwards. This
+may cause problems if other programs are reading the file at the same
+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
+to detect this situation, but cannot do so reliably due to race
+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.
+
address@hidden avoids changing time stamps on files,
+without interfering with time stamp updates
+caused by other programs, so it works better with incremental backups.
+However, it requires a special @code{O_NOATIME} option from the
+underlying operating and file system implementation, and it also requires
+that searching directories does not update their access times. As of
+this writing (November 2005) this works only with Linux, and only with
+Linux kernels 2.6.8 and later. Worse, there is currently no reliable
+way to know whether this feature actually works. Sometimes
address@hidden knows that it does not work, and if you use
address@hidden then @command{tar} complains and
+exits right away. But other times @command{tar} might think that the
+option works when it actually does not.
+
+Currently @option{--atime-preserve} with no operand defaults to
address@hidden, but this may change in the future
+as support for @option{--atime-preserve=system} improves.
+
+If your operating system does not support
address@hidden@-system}, you might be able to preserve access
+times reliably by 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
+superuser privileges and can be a pain to manage.
+
address@hidden ANCHOR--backup 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Rather than deleting files from the file system, @command{tar} will
+back them up using simple or numbered backups, depending upon
address@hidden @xref{backup}.
+
address@hidden ANCHOR--block-number 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --block-number
address@hidden -R
+
+With this option present, @command{tar} prints error messages for read errors
+with the block number in the archive file. @xref{block-number}.
+
address@hidden ANCHOR--blocking-factor 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -b @var{blocking}
+
+Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per
+record. @xref{Blocking Factor}.
+
address@hidden ANCHOR--bzip2 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --bzip2
address@hidden -j
+
+This option tells @command{tar} to read or write archives through
address@hidden @xref{gzip}.
+
address@hidden ANCHOR--checkpoint 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+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}.
+
address@hidden ANCHOR--check-links 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --check-links
address@hidden -l
+If this option was given, @command{tar} will 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, a warning message will be
+output @footnote{Earlier versions of @acronym{GNU} @command{tar} understood
@option{-l} as a
+synonym for @option{--one-file-system}. The current semantics, which
+complies to UNIX98, was introduced with version
+1.15.91. @xref{Changes}, for more information.}.
+
address@hidden ANCHOR--compress 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--uncompress 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --compress
address@hidden --uncompress
address@hidden -Z
+
address@hidden will use the @command{compress} program when reading or
+writing the archive. This allows you to directly act on archives
+while saving space. @xref{gzip}.
+
address@hidden ANCHOR--confirmation 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --confirmation
+
+(See @option{--interactive}.) @xref{interactive}.
+
address@hidden ANCHOR--delay-directory-restore 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --delay-directory-restore
+
+Delay setting modification times and permissions of extracted
+directories until the end of extraction. @xref{Directory Modification Times
and Permissions}.
+
address@hidden ANCHOR--dereference 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --dereference
address@hidden -h
+
+When creating a @command{tar} archive, @command{tar} will archive the
+file that a symbolic link points to, rather than archiving the
+symlink. @xref{dereference}.
+
address@hidden ANCHOR--directory 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -C @var{dir}
+
+When this option is specified, @command{tar} will change its current directory
+to @var{dir} before performing any operations. When this option is used
+during archive creation, it is order sensitive. @xref{directory}.
+
address@hidden ANCHOR--exclude 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When performing operations, @command{tar} will skip files that match
address@hidden @xref{exclude}.
+
address@hidden ANCHOR--exclude-from 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -X @var{file}
+
+Similar to @option{--exclude}, except @command{tar} will use the list of
+patterns in the file @var{file}. @xref{exclude}.
+
address@hidden ANCHOR--exclude-caches 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --exclude-caches
+
+Automatically excludes all directories
+containing a cache directory tag. @xref{exclude}.
+
address@hidden ANCHOR--file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -f @var{archive}
+
address@hidden will use the file @var{archive} as the @command{tar} archive it
+performs operations on, rather than @command{tar}'s compilation dependent
+default. @xref{file tutorial}.
+
address@hidden ANCHOR--files-from 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -T @var{file}
+
address@hidden will use the contents of @var{file} as a list of archive members
+or files to operate on, in addition to those specified on the
+command-line. @xref{files}.
+
address@hidden ANCHOR--force-local 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --force-local
+
+Forces @command{tar} to interpret the filename given to @option{--file}
+as a local file, even if it looks like a remote tape drive name.
address@hidden and remote archives}.
+
address@hidden ANCHOR--format 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -H @var{format}
+
+Selects output archive format. @var{Format} may be one of the
+following:
+
address@hidden @samp
address@hidden v7
+Creates an archive that is compatible with Unix V7 @command{tar}.
+
address@hidden oldgnu
+Creates an archive that is compatible with GNU @command{tar} version
+1.12 or earlier.
+
address@hidden gnu
+Creates archive in GNU tar 1.13 format. Basically it is the same as
address@hidden with the only difference in the way it handles long
+numeric fields.
+
address@hidden ustar
+Creates a @acronym{POSIX.1-1988} compatible archive.
+
address@hidden posix
+Creates a @acronym{POSIX.1-2001 archive}.
+
address@hidden table
+
address@hidden, for a detailed discussion of these formats.
+
address@hidden ANCHOR--group 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Files added to the @command{tar} archive will have a group id of @var{group},
+rather than the group from the source file. @var{group} is first decoded
+as a group symbolic name, but if this interpretation fails, it has to be
+a decimal numeric group ID. @xref{override}.
+
+Also see the comments for the @address@hidden option.
+
address@hidden ANCHOR--gzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--gunzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--ungzip 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --gzip
address@hidden --gunzip
address@hidden --ungzip
address@hidden -z
+
+This option tells @command{tar} to read or write archives through
address@hidden, allowing @command{tar} to directly operate on several
+kinds of compressed archives transparently. @xref{gzip}.
+
address@hidden ANCHOR--help 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --help
address@hidden -?
+
address@hidden will print out a short message summarizing the operations and
+options to @command{tar} and exit. @xref{help}.
+
address@hidden ANCHOR--ignore-case 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-case
+Ignore case when matching member or file names with
+patterns. @xref{controlling pattern-matching}.
+
address@hidden ANCHOR--ignore-command-error 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-command-error
+Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--ignore-failed-read 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-failed-read
+
+Do not exit unsuccessfully merely because an unreadable file was encountered.
address@hidden
+
address@hidden ANCHOR--ignore-zeros 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --ignore-zeros
address@hidden -i
+
+With this option, @command{tar} will ignore zeroed blocks in the
+archive, which normally signals EOF. @xref{Reading}.
+
address@hidden ANCHOR--incremental 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --incremental
address@hidden -G
+
+Used to inform @command{tar} that it is working with an old
address@hidden incremental backup archive. It is intended
+primarily for backwards compatibility only. @xref{Incremental Dumps},
+for a detailed discussion of incremental archives.
+
address@hidden ANCHOR--index-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Send verbose output to @var{file} instead of to standard output.
+
address@hidden ANCHOR--info-script 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--new-volume-script 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden address@hidden
address@hidden -F @var{script-file}
+
+When @command{tar} is performing multi-tape backups, @var{script-file} is run
+at the end of each tape. If @var{script-file} exits with nonzero status,
address@hidden fails immediately. @xref{info-script}, for a detailed
+discussion of @var{script-file}.
+
address@hidden ANCHOR--interactive 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --interactive
address@hidden --confirmation
address@hidden -w
+
+Specifies that @command{tar} should ask the user for confirmation before
+performing potentially destructive options, such as overwriting files.
address@hidden
+
address@hidden ANCHOR--keep-newer-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --keep-newer-files
+
+Do not replace existing files that are newer than their archive copies
+when extracting files from an archive.
+
address@hidden ANCHOR--keep-old-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --keep-old-files
address@hidden -k
+
+Do not overwrite existing files when extracting files from an archive.
address@hidden Old Files}.
+
address@hidden ANCHOR--label 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -V @var{name}
+
+When creating an archive, instructs @command{tar} to write @var{name}
+as a name record in the archive. When extracting or listing archives,
address@hidden will only operate on archives that have a label matching
+the pattern specified in @var{name}. @xref{Tape Files}.
+
address@hidden ANCHOR--listed-incremental 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -g @var{snapshot-file}
+
+During a @option{--create} operation, specifies that the archive that
address@hidden creates is a new @acronym{GNU}-format incremental
+backup, using @var{snapshot-file} to determine which files to backup.
+With other operations, informs @command{tar} that the archive is in
+incremental format. @xref{Incremental Dumps}.
+
address@hidden ANCHOR--mode 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use
address@hidden for the archive members, rather than the permissions
+from the files. @var{permissions} can be specified either as an octal
+number or as symbolic permissions, like with
address@hidden @xref{override}.
+
address@hidden ANCHOR--mtime 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use @var{date} as
+the modification time of members when creating archives, instead of
+their actual modification times. The value of @var{date} can be
+either a textual date representation (@pxref{Date input formats}) or a
+name of the existing file, starting with @samp{/} or @samp{.}. In the
+latter case, the modification time of that file is used. @xref{override}.
+
address@hidden ANCHOR--multi-volume 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --multi-volume
address@hidden -M
+
+Informs @command{tar} that it should create or otherwise operate on a
+multi-volume @command{tar} archive. @xref{Using Multiple Tapes}.
+
address@hidden address@hidden, summary}
address@hidden --new-volume-script
+
+(see --info-script)
+
address@hidden ANCHOR--seek 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --seek
address@hidden -n
+
+Assume that the archive media supports seeks to arbitrary
+locations. Usually @command{tar} determines automatically whether
+the archive can be seeked or not. This option is intended for use
+in cases when such recognition fails.
+
address@hidden ANCHOR--newer 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden address@hidden
address@hidden -N
+
+When creating an archive, @command{tar} will only add files that have changed
+since @var{date}. If @var{date} begins with @samp{/} or @samp{.}, it
+is taken to be the name of a file whose data modification time specifies
+the date. @xref{after}.
+
address@hidden ANCHOR--newer-mtime 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Like @option{--newer}, but add only files whose
+contents have changed (as opposed to just @option{--newer}, which will
+also back up files for which any status information has
+changed). @xref{after}.
+
address@hidden ANCHOR--no-anchored 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-anchored
+An exclude pattern can match any subsequence of the name's components.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-delay-directory-restore 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-delay-directory-restore
+
+Setting modification times and permissions of extracted
+directories when all files from this directory has been
+extracted. This is the default. @xref{Directory Modification Times and
Permissions}.
+
address@hidden ANCHOR--no-ignore-case 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-ignore-case
+Use case-sensitive matching.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-ignore-command-error 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-ignore-command-error
+Print warnings about subprocesses terminated with a non-zero exit
+code. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--no-overwrite-dir 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-overwrite-dir
+
+Preserve metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--no-quote-chars 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option
+(@pxref{quoting styles}).
+
address@hidden ANCHOR--no-recursion 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-recursion
+
+With this option, @command{tar} will not recurse into directories.
address@hidden
+
address@hidden ANCHOR--no-same-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-same-owner
address@hidden -o
+
+When extracting an archive, do not attempt to preserve the owner
+specified in the @command{tar} archive. This the default behavior
+for ordinary users.
+
address@hidden ANCHOR--no-same-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-same-permissions
+
+When extracting an archive, subtract the user's umask from files from
+the permissions specified in the archive. This is the default behavior
+for ordinary users.
+
address@hidden ANCHOR--no-unquote 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-unquote
+Treat all input file or member names literally, do not interpret
+escape sequences. @xref{input name quoting}.
+
address@hidden ANCHOR--no-wildcards 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-wildcards
+Do not use wildcards.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--no-wildcards-match-slash 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --no-wildcards-match-slash
+Wildcards do not match @samp{/}.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--null 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --null
+
+When @command{tar} is using the @option{--files-from} option, this option
+instructs @command{tar} to expect filenames terminated with @option{NUL}, so
address@hidden can correctly work with file names that contain newlines.
address@hidden
+
address@hidden ANCHOR--numeric-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --numeric-owner
+
+This option will notify @command{tar} that it should use numeric user
+and group IDs when creating a @command{tar} file, rather than names.
address@hidden
+
address@hidden -o
+The function of this option depends on the action @command{tar} is
+performing. When extracting files, @option{-o} is a synonym for
address@hidden, i.e. it prevents @command{tar} from
+restoring ownership of files being extracted.
+
+When creating an archive, it is a synonym for
address@hidden This behavior is for compatibility
+with previous versions of @acronym{GNU} @command{tar}, and will be
+removed in the future releases.
+
address@hidden, for more information.
+
address@hidden ANCHOR--occurrence 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+This option can be used in conjunction with one of the subcommands
address@hidden, @option{--diff}, @option{--extract} or
address@hidden when a list of files is given either on the command
+line or via @option{-T} option.
+
+This option instructs @command{tar} to process only the @var{number}th
+occurrence of each named file. @var{Number} defaults to 1, so
+
address@hidden
+tar -x -f archive.tar --occurrence filename
address@hidden smallexample
+
address@hidden
+will extract the first occurrence of the member @file{filename} from
@file{archive.tar}
+and will terminate without scanning to the end of the archive.
+
address@hidden ANCHOR--old-archive 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --old-archive
+Synonym for @option{--format=v7}.
+
address@hidden ANCHOR--one-file-system 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --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 @acronym{GNU} @command{tar} understood
@option{-l} as a
+synonym for @option{--one-file-system}. This has changed in version
+1.15.91. @xref{Changes}, for more information.}.
+
address@hidden ANCHOR--overwrite 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --overwrite
+
+Overwrite existing files and directory metadata when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--overwrite-dir 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --overwrite-dir
+
+Overwrite the metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden ANCHOR--owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file. @var{user} is first decoded as a user symbolic name, but if
+this interpretation fails, it has to be a decimal numeric user ID.
address@hidden
+
+This option does not affect extraction from archives.
+
address@hidden ANCHOR--transform 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Transform file or member names using @command{sed} replacement expression
address@hidden For example,
+
address@hidden
+$ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .}
address@hidden smallexample
+
address@hidden
+will add to @file{archive} files from the current working directory,
+replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
+discussion, @xref{transform}.
+
+To see transformed member names in verbose listings, use
address@hidden option
+(@pxref{show-transformed-names}).
+
address@hidden ANCHOR--quote-chars 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them (@pxref{quoting styles}).
+
address@hidden ANCHOR--quoting-style 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Set quoting style to use when printing member and file names
+(@pxref{quoting styles}). Valid @var{style} values are:
address@hidden, @code{shell}, @code{shell-always}, @code{c},
address@hidden, @code{locale}, and @code{clocale}. Default quoting
+style is @code{escape}, unless overridden while configuring the
+package.
+
address@hidden ANCHOR--pax-option 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+This option is meaningful only with @acronym{POSIX.1-2001} archives
+(@pxref{posix}). It modifies the way @command{tar} handles the
+extended header keywords. @var{Keyword-list} is a comma-separated
+list of keyword options. @xref{PAX keywords}, for a detailed
+discussion.
+
address@hidden ANCHOR--portability 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --portability
address@hidden --old-archive
+Synonym for @option{--format=v7}.
+
address@hidden ANCHOR--posix 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --posix
+Same as @option{--format=posix}.
+
address@hidden ANCHOR--preserve 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve
+
+Synonymous with specifying both @option{--preserve-permissions} and
address@hidden @xref{Setting Access Permissions}.
+
address@hidden ANCHOR--preserve-order 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve-order
+
+(See @option{--same-order}; @pxref{Reading}.)
+
address@hidden ANCHOR--preserve-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--same-permissions 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --preserve-permissions
address@hidden --same-permissions
address@hidden -p
+
+When @command{tar} is extracting an archive, it normally subtracts the
+users' umask from the permissions specified in the archive and uses
+that number as the permissions to create the destination file.
+Specifying this option instructs @command{tar} that it should use the
+permissions directly from the archive. @xref{Setting Access Permissions}.
+
address@hidden ANCHOR--read-full-records 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --read-full-records
address@hidden -B
+
+Specifies that @command{tar} should reblock its input, for reading
+from pipes on systems with buggy implementations. @xref{Reading}.
+
address@hidden ANCHOR--record-size 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Instructs @command{tar} to use @var{size} bytes per record when accessing the
+archive. @xref{Blocking Factor}.
+
address@hidden ANCHOR--recursion 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --recursion
+
+With this option, @command{tar} recurses into directories.
address@hidden
+
address@hidden ANCHOR--recursive-unlink 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --recursive-unlink
+
+Remove existing
+directory hierarchies before extracting directories of the same name
+from the archive. @xref{Recursive Unlink}.
+
address@hidden ANCHOR--remove-files 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --remove-files
+
+Directs @command{tar} to remove the source file from the file system after
+appending it to an archive. @xref{remove files}.
+
address@hidden ANCHOR--restrict 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --restrict
+
+Disable use of some potentially harmful @command{tar} options.
+Currently this option disables shell invocaton from multi-volume menu
+(@pxref{Using Multiple Tapes}).
+
address@hidden ANCHOR--rmt-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Notifies @command{tar} that it should use @var{cmd} instead of
+the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}).
+
address@hidden ANCHOR--rsh-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Notifies @command{tar} that is should use @var{cmd} to communicate with remote
+devices. @xref{Device}.
+
address@hidden ANCHOR--same-order 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --same-order
address@hidden --preserve-order
address@hidden -s
+
+This option is an optimization for @command{tar} when running on machines with
+small amounts of memory. It informs @command{tar} that the list of file
+arguments has already been sorted to match the order of files in the
+archive. @xref{Reading}.
+
address@hidden ANCHOR--same-owner 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --same-owner
+
+When extracting an archive, @command{tar} will attempt to preserve the owner
+specified in the @command{tar} archive with this option present.
+This is the default behavior for the superuser; this option has an
+effect only for ordinary users. @xref{Attributes}.
+
address@hidden address@hidden, summary}
address@hidden --same-permissions
+
+(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
+
address@hidden ANCHOR--show-defaults 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-defaults
+
+Displays the default options used by @command{tar} and exits
+successfully. This option is intended for use in shell scripts.
+Here is an example of what you can see using this option:
+
address@hidden
+$ tar --show-defaults
+--format=gnu -f- -b20 --quoting-style=escape \
+--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
address@hidden smallexample
+
address@hidden ANCHOR--show-omitted-dirs 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-omitted-dirs
+
+Instructs @command{tar} to mention directories its skipping over when
+operating on a @command{tar} archive. @xref{show-omitted-dirs}.
+
address@hidden ANCHOR--show-transformed-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden ANCHOR--show-stored-names 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --show-transformed-names
address@hidden --show-stored-names
+
+Display file or member names after applying any transformations
+(@pxref{transform}). In particular, when used in conjunction with one of
+archive creation operations it instructs tar to list the member names
+stored in the archive, as opposed to the actual file
+names. @xref{listing member and file names}.
+
address@hidden ANCHOR--sparse 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --sparse
address@hidden -S
+
+Invokes a @acronym{GNU} extension when adding files to an archive that handles
+sparse files efficiently. @xref{sparse}.
+
address@hidden ANCHOR--sparse-version 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Specified the @dfn{format version} to use when archiving sparse
+files. Implies @option{--sparse}. @xref{sparse}. For the description
+of the supported sparse formats, @xref{Sparse Formats}.
+
address@hidden ANCHOR--starting-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -K @var{name}
+
+This option affects extraction only; @command{tar} will skip extracting
+files in the archive until it finds one that matches @var{name}.
address@hidden
+
address@hidden ANCHOR--strip-components 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+Strip given @var{number} of leading components from file names before
address@hidden option was called @option{--strip-path} in
+version 1.14.} For example, if archive @file{archive.tar} contained
address@hidden/some/file/name}, then running
+
address@hidden
+tar --extract --file archive.tar --strip-components=2
address@hidden smallexample
+
address@hidden
+would extract this file to file @file{name}.
+
address@hidden ANCHOR--suffix 1
address@hidden
address@hidden address@hidden, summary}, summary
address@hidden address@hidden
+
+Alters the suffix @command{tar} uses when backing up files from the default
address@hidden @xref{backup}.
+
address@hidden ANCHOR--tape-length 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
address@hidden -L @var{num}
+
+Specifies the length of tapes that @command{tar} is writing as being
address@hidden@var{num} x 1024} bytes long. @xref{Using Multiple Tapes}.
+
address@hidden ANCHOR--test-label 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --test-label
+
+Reads the volume label. If an argument is specified, test whether it
+matches the volume label. @xref{--test-label option}.
+
address@hidden ANCHOR--to-command 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+During extraction @command{tar} will pipe extracted files to the
+standard input of @var{command}. @xref{Writing to an External Program}.
+
address@hidden ANCHOR--to-stdout 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --to-stdout
address@hidden -O
+
+During extraction, @command{tar} will extract files to stdout rather
+than to the file system. @xref{Writing to Standard Output}.
+
address@hidden ANCHOR--totals 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Displays the total number of bytes transferred when processing an
+archive. If an argument is given, these data are displayed on
+request, when signal @var{signo} is delivered to @command{tar}.
address@hidden
+
address@hidden ANCHOR--touch 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --touch
address@hidden -m
+
+Sets the data modification time of extracted files to the extraction time,
+rather than the data modification time stored in the archive.
address@hidden Modification Times}.
+
address@hidden address@hidden, summary}
address@hidden --uncompress
+
+(See @option{--compress}. @pxref{gzip})
+
address@hidden address@hidden, summary}
address@hidden --ungzip
+
+(See @option{--gzip}. @pxref{gzip})
+
address@hidden ANCHOR--unlink-first 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --unlink-first
address@hidden -U
+
+Directs @command{tar} to remove the corresponding file from the file
+system before extracting it from the archive. @xref{Unlink First}.
+
address@hidden ANCHOR--unquote 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --unquote
+Enable unquoting input file or member names (default). @xref{input
+name quoting}.
+
address@hidden ANCHOR--use-compress-program 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Instructs @command{tar} to access the archive through @var{prog}, which is
+presumed to be a compression program of some sort. @xref{gzip}.
+
address@hidden ANCHOR--utc 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --utc
+
+Display file modification dates in @acronym{UTC}. This option implies
address@hidden
+
address@hidden ANCHOR--verbose 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --verbose
address@hidden -v
+
+Specifies that @command{tar} should be more verbose about the operations its
+performing. This option can be specified multiple times for some
+operations to increase the amount of information displayed.
address@hidden
+
address@hidden ANCHOR--verify 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --verify
address@hidden -W
+
+Verifies that the archive was correctly written when creating an
+archive. @xref{verify}.
+
address@hidden ANCHOR--version 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --version
+
+Print information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden
+
address@hidden ANCHOR--volno-file 1
address@hidden
address@hidden address@hidden, summary}
address@hidden address@hidden
+
+Used in conjunction with @option{--multi-volume}. @command{tar} will
+keep track of which volume of a multi-volume archive its working in
address@hidden @xref{volno-file}.
+
address@hidden ANCHOR--wildcards 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --wildcards
+Use wildcards when matching member names with patterns.
address@hidden pattern-matching}.
+
address@hidden ANCHOR--wildcards-match-slash 1
address@hidden
address@hidden address@hidden, summary}
address@hidden --wildcards-match-slash
+Wildcards match @samp{/}.
address@hidden pattern-matching}.
address@hidden table
+
address@hidden Short Option Summary
address@hidden Short Options Cross Reference
+
+Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
+
address@hidden @columnfractions 0.20 0.80
address@hidden Short Option @tab Reference
+
address@hidden -A @tab @ref{--concatenate}.
+
address@hidden -B @tab @ref{--read-full-records}.
+
address@hidden -C @tab @ref{--directory}.
+
address@hidden -F @tab @ref{--info-script}.
+
address@hidden -G @tab @ref{--incremental}.
+
address@hidden -K @tab @ref{--starting-file}.
+
address@hidden -L @tab @ref{--tape-length}.
+
address@hidden -M @tab @ref{--multi-volume}.
+
address@hidden -N @tab @ref{--newer}.
+
address@hidden -O @tab @ref{--to-stdout}.
+
address@hidden -P @tab @ref{--absolute-names}.
+
address@hidden -R @tab @ref{--block-number}.
+
address@hidden -S @tab @ref{--sparse}.
+
address@hidden -T @tab @ref{--files-from}.
+
address@hidden -U @tab @ref{--unlink-first}.
+
address@hidden -V @tab @ref{--label}.
+
address@hidden -W @tab @ref{--verify}.
+
address@hidden -X @tab @ref{--exclude-from}.
+
address@hidden -Z @tab @ref{--compress}.
+
address@hidden -b @tab @ref{--blocking-factor}.
+
address@hidden -c @tab @ref{--create}.
+
address@hidden -d @tab @ref{--compare}.
+
address@hidden -f @tab @ref{--file}.
+
address@hidden -g @tab @ref{--listed-incremental}.
+
address@hidden -h @tab @ref{--dereference}.
+
address@hidden -i @tab @ref{--ignore-zeros}.
+
address@hidden -j @tab @ref{--bzip2}.
+
address@hidden -k @tab @ref{--keep-old-files}.
+
address@hidden -l @tab @ref{--check-links}.
+
address@hidden -m @tab @ref{--touch}.
+
address@hidden -o @tab When creating, @ref{--no-same-owner}, when extracting ---
address@hidden
+
+The later usage is deprecated. It is retained for compatibility with
+the earlier versions of @acronym{GNU} @command{tar}. In the future releases
address@hidden will be equivalent to @option{--no-same-owner} only.
+
address@hidden -p @tab @ref{--preserve-permissions}.
+
address@hidden -r @tab @ref{--append}.
+
address@hidden -s @tab @ref{--same-order}.
+
address@hidden -t @tab @ref{--list}.
+
address@hidden -u @tab @ref{--update}.
+
address@hidden -v @tab @ref{--verbose}.
+
address@hidden -w @tab @ref{--interactive}.
+
address@hidden -x @tab @ref{--extract}.
+
address@hidden -z @tab @ref{--gzip}.
+
address@hidden multitable
+
address@hidden help
address@hidden @acronym{GNU} @command{tar} documentation
+
address@hidden Getting program version number
address@hidden version
address@hidden Version of the @command{tar} program
+Being careful, the first thing is really checking that you are using
address@hidden @command{tar}, indeed. The @option{--version} option
+causes @command{tar} to print information about its name, version,
+origin and legal status, all on standard output, and then exit
+successfully. For example, @address@hidden --version}} might print:
+
address@hidden
+tar (GNU tar) 1.15.92
+Copyright (C) 2006 Free Software Foundation, Inc.
+This is free software. You may redistribute copies of it under the terms
+of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by John Gilmore and Jay Fenlason.
address@hidden smallexample
+
address@hidden
+The first occurrence of @samp{tar} in the result above is the program
+name in the package (for example, @command{rmt} is another program),
+while the second occurrence of @samp{tar} is the name of the package
+itself, containing possibly many programs. The package is currently
+named @samp{tar}, after the name of the main program it
address@hidden are plans to merge the @command{cpio} and
address@hidden packages into a single one which would be called
address@hidden So, who knows if, one of this days, the
address@hidden would not output @address@hidden (@acronym{GNU}
+paxutils) 3.2}}}.
+
address@hidden Obtaining help
address@hidden Listing all @command{tar} options
address@hidden address@hidden, introduction}
+Another thing you might want to do is checking the spelling or meaning
+of some particular @command{tar} option, without resorting to this
+manual, for once you have carefully read it. @acronym{GNU} @command{tar}
+has a short help feature, triggerable through the
address@hidden option. By using this option, @command{tar} will
+print a usage message listing all available options on standard
+output, then exit successfully, without doing anything else and
+ignoring all other options. Even if this is only a brief summary, it
+may be several screens long. So, if you are not using some kind of
+scrollable window, you might prefer to use something like:
+
address@hidden
+$ @kbd{tar --help | less}
address@hidden smallexample
+
address@hidden
+presuming, here, that you like using @command{less} for a pager. Other
+popular pagers are @command{more} and @command{pg}. If you know about some
address@hidden which interests you and do not want to read all the
address@hidden output, another common idiom is doing:
+
address@hidden
+tar --help | grep @var{keyword}
address@hidden smallexample
+
address@hidden
+for getting only the pertinent lines. Notice, however, that some
address@hidden options have long description lines and the above
+command will list only the first of them.
+
+The exact look of the option summary displayed by @kbd{tar --help} is
+configurable. @xref{Configuring Help Summary}, for a detailed description.
+
address@hidden 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
address@hidden option 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
+this paragraph, you already have the @command{tar} manual in some
+form. This manual is available in a variety of forms from
address@hidden://www.gnu.org/software/tar/manual}. It may be printed out of
the @acronym{GNU} @command{tar}
+distribution, provided you have @TeX{} already installed somewhere,
+and a laser printer around. Just configure the distribution, execute
+the command @address@hidden dvi}}, then print @file{doc/tar.dvi} the
+usual way (contact your local guru to know how). If @acronym{GNU}
@command{tar}
+has been conveniently installed at your place, this
+manual is also available in interactive, hypertextual form as an Info
+file. Just call @address@hidden tar}} or, if you do not have the
address@hidden program handy, use the Info reader provided within
address@hidden Emacs, calling @samp{tar} from the main Info menu.
+
+There is currently no @code{man} page for @acronym{GNU} @command{tar}.
+If you observe such a @code{man} page on the system you are running,
+either it does not belong to @acronym{GNU} @command{tar}, or it has not
+been produced by @acronym{GNU}. Some package maintainers convert
address@hidden --help} output to a man page, using @command{help2man}. In
+any case, please bear in mind that the authoritative source of
+information about @acronym{GNU} @command{tar} is this Texinfo documentation.
+
address@hidden defaults
address@hidden Obtaining @acronym{GNU} @command{tar} default values
+
address@hidden show-defaults
address@hidden @command{tar} has some predefined defaults that are used when
you do not
+explicitely specify another values. To obtain a list of such
+defaults, use @option{--show-defaults} option. This will output the
+values in the form of @command{tar} command line options:
+
address@hidden
address@hidden
address@hidden --show-defaults}
+--format=gnu -f- -b20 --quoting-style=escape
+--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that this option outputs only one line. The example output above
+has been split to fit page boundaries.
+
address@hidden
+The above output shows that this version of @acronym{GNU} @command{tar}
defaults to
+using @samp{gnu} archive format (@pxref{Formats}), it uses standard
+output as the archive, if no @option{--file} option has been given
+(@pxref{file tutorial}), the default blocking factor is 20
+(@pxref{Blocking Factor}). It also shows the default locations where
address@hidden will look for @command{rmt} and @command{rsh} binaries.
+
address@hidden verbose
address@hidden Checking @command{tar} progress
+
+Typically, @command{tar} performs most operations without reporting any
+information to the user except error messages. When using @command{tar}
+with many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
address@hidden provides several options that make observing @command{tar}
+easier. These options cause @command{tar} to print information as it
+progresses in its job, and you might want to use them just for being
+more careful about what is going on, or merely for entertaining
+yourself. If you have encountered a problem when operating on an
+archive, however, you may need more information than just an error
+message in order to solve the problem. The following options can be
+helpful diagnostic tools.
+
address@hidden Verbose operation
address@hidden verbose
+Normally, the @option{--list} (@option{-t}) command to list an archive
+prints just the file names (one per line) and the other commands are
+silent. When used with most operations, the @option{--verbose}
+(@option{-v}) option causes @command{tar} to print the name of each
+file or archive member as it is processed. This and the other options
+which make @command{tar} print status information can be useful in
+monitoring @command{tar}.
+
+With @option{--create} or @option{--extract}, @option{--verbose} used
+once just prints the names of the files or members as they are processed.
+Using it twice causes @command{tar} to print a longer listing
+(@xref{verbose member listing}, for the description) for each member.
+Since @option{--list} already prints the names of the members,
address@hidden used once with @option{--list} causes @command{tar}
+to print an @samp{ls -l} type listing of the files in the archive.
+The following examples both extract members with long list output:
+
address@hidden
+$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
+$ @kbd{tar xvvf archive.tar}
address@hidden smallexample
+
+Verbose output appears on the standard output except when an archive is
+being written to the standard output, as with @samp{tar --create
+--file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
+installer let standard output be the default archive). In that case
address@hidden writes verbose output to the standard error stream.
+
+If @address@hidden is specified, @command{tar} sends
+verbose output to @var{file} rather than to standard output or standard
+error.
+
address@hidden
address@hidden Obtaining total status information
address@hidden totals
+The @option{--totals} option causes @command{tar} to print on the
+standard error the total amount of bytes transferred when processing
+an archive. When creating or appending to an archive, this option
+prints the number of bytes written to the archive and the average
+speed at which they have been written, e.g.:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --totals /home}
+Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
address@hidden group
address@hidden smallexample
+
+When reading an archive, this option displays the number of bytes
+read:
+
address@hidden
address@hidden
+$ @kbd{tar -x -f archive.tar --totals}
+Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
address@hidden group
address@hidden smallexample
+
+Finally, when deleting from an archive, the @option{--totals} option
+displays both numbers plus number of bytes removed from the archive:
+
address@hidden
address@hidden
+$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'}
+Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+Total bytes deleted: 1474048
address@hidden group
address@hidden smallexample
+
+You can also obtain this information on request. When
address@hidden is used with an argument, this argument is
+interpreted as a symbolic name of a signal, upon delivery of which the
+statistics is to be printed:
+
address@hidden @option
address@hidden address@hidden
+Print statistics upon delivery of signal @var{signo}. Valid arguments
+are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and
address@hidden Shortened names without @samp{SIG} prefix are also
+accepted.
address@hidden table
+
+Both forms of @option{--totals} option can be used simultaneously.
+Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to
+extract all members from its default archive and print statistics
+after finishing the extraction, as well as when receiving signal
address@hidden
+
address@hidden information}
address@hidden Progress information
address@hidden 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
address@hidden (@option{-R}), but do want visual confirmation
+that @command{tar} is actually making forward progress. By default it
+prints a message each 10 records read or written. This can be changed
+by giving it a numeric argument after an equal sign:
+
address@hidden
+$ @kbd{tar -c --checkpoint=1000} /var
+tar: Write checkpoint 1000
+tar: Write checkpoint 2000
+tar: Write checkpoint 3000
address@hidden smallexample
+
+This example shows the default checkpoint message used by
address@hidden If you place a dot immediately after the equal
+sign, it will print a @samp{.} at each checkpoint. For example:
+
address@hidden
+$ @kbd{tar -c --checkpoint=.1000} /var
+...
address@hidden smallexample
+
address@hidden show-omitted-dirs
address@hidden
+The @option{--show-omitted-dirs} option, when reading an archive---with
address@hidden or @option{--extract}, for example---causes a message
+to be printed for each directory in the archive which is skipped.
+This happens regardless of the reason for skipping: the directory might
+not have been named on the command line (implicitly or explicitly),
+it might be excluded by the use of the
address@hidden@var{pattern}} option, or some other reason.
+
address@hidden block-number
address@hidden Block number where error occurred
address@hidden
+If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along
with
+every message it would normally produce, the block number within the
+archive where the message was triggered. Also, supplementary messages
+are triggered when reading blocks full of NULs, or when hitting end of
+file on the archive. As of now, if the archive if properly terminated
+with a NUL block, the reading of the file may stop before end of file
+is met, so the position of end of file will not usually show when
address@hidden (@option{-R}) is used. Note that @acronym{GNU} @command{tar}
+drains the archive before exiting when reading the
+archive from a pipe.
+
address@hidden Error message, block number of
+This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
address@hidden (@option{-t}) when listing a file-system backup tape, allowing
you to
+choose among several backup tapes when retrieving a file later, in
+favor of the tape where the file appears earliest (closest to the
+front of the tape). @xref{backup}.
+
address@hidden interactive
address@hidden Asking for Confirmation During Operations
address@hidden Interactive operation
+
+Typically, @command{tar} carries out a command without stopping for
+further instructions. In some situations however, you may want to
+exclude some files and archive members from the operation (for instance
+if disk or storage space is tight). You can do this by excluding
+certain files automatically (@pxref{Choosing}), or by performing
+an operation interactively, using the @option{--interactive} (@option{-w})
option.
address@hidden also accepts @option{--confirmation} for this option.
+
address@hidden interactive
+When the @option{--interactive} (@option{-w}) option is specified, before
+reading, writing, or deleting files, @command{tar} first prints a message
+for each such file, telling what operation it intends to take, then asks
+for confirmation on the terminal. The actions which require
+confirmation include adding a file to the archive, extracting a file
+from the archive, deleting a file from the archive, and deleting a file
+from disk. To confirm the action, you must type a line of input
+beginning with @samp{y}. If your input line begins with anything other
+than @samp{y}, @command{tar} skips that file.
+
+If @command{tar} is reading the archive from the standard input,
address@hidden opens the file @file{/dev/tty} to support the interactive
+communications.
+
+Verbose output is normally sent to standard output, separate from
+other error messages. However, if the archive is produced directly
+on standard output, then verbose output is mixed with errors on
address@hidden Producing the archive on standard output may be used
+as a way to avoid using disk space, when the archive is soon to be
+consumed by another process reading it, say. Some people felt the need
+of producing an archive on stdout, still willing to segregate between
+verbose output and error output. A possible approach would be using a
+named pipe to receive the archive, and having the consumer process to
+read from that named pipe. This has the advantage of letting standard
+output free to receive verbose output, all separate from errors.
+
address@hidden operations
address@hidden @acronym{GNU} @command{tar} Operations
+
address@hidden
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
address@hidden menu
+
address@hidden Basic tar
address@hidden Basic @acronym{GNU} @command{tar} Operations
+
+The basic @command{tar} operations, @option{--create} (@option{-c}),
address@hidden (@option{-t}) and @option{--extract} (@option{--get},
address@hidden), are currently presented and described in the tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+
address@hidden @option
address@hidden address@hidden, complementary notes}
address@hidden --create
address@hidden -c
+
+Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use @option{--append}
+(@option{-r}) for adding all members. Some applications would not
+welcome making an exception in the way of adding the first archive
+member. On the other hand, many people reported that it is
+dangerously too easy for @command{tar} to destroy a magnetic tape with
+an empty address@hidden is well described in @cite{Unix-haters
+Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG
+Books, ISBN 1-56884-203-1.}. The two most common errors are:
+
address@hidden
address@hidden
+Mistakingly using @code{create} instead of @code{extract}, when the
+intent was to extract the full contents of an archive. This error
+is likely: keys @kbd{c} and @kbd{x} are right next to each other on
+the QWERTY keyboard. Instead of being unpacked, the archive then
+gets wholly destroyed. When users speak about @dfn{exploding} an
+archive, they usually mean something else :-).
+
address@hidden
+Forgetting the argument to @code{file}, when the intent was to create
+an archive with a single file in it. This error is likely because a
+tired user can easily add the @kbd{f} key to the cluster of option
+letters, by the mere force of habit, without realizing the full
+consequence of doing so. The usual consequence is that the single
+file, which was meant to be saved, is rather destroyed.
address@hidden enumerate
+
+So, recognizing the likelihood and the catastrophical nature of these
+errors, @acronym{GNU} @command{tar} now takes some distance from elegance, and
+cowardly refuses to create an archive when @option{--create} option is
+given, there are no arguments besides options, and
address@hidden (@option{-T}) option is @emph{not} used. To get
+around the cautiousness of @acronym{GNU} @command{tar} and nevertheless create
an
+archive with nothing in it, one may still use, as the value for the
address@hidden option, a file with no names in it, as shown in
+the following commands:
+
address@hidden
address@hidden --create --file=empty-archive.tar --files-from=/dev/null}
address@hidden cfT empty-archive.tar /dev/null}
address@hidden smallexample
+
address@hidden address@hidden, complementary notes}
address@hidden --extract
address@hidden --get
address@hidden -x
+
+A socket is stored, within a @acronym{GNU} @command{tar} archive, as a pipe.
+
address@hidden @option{--list} (@option{-t})
+
address@hidden @command{tar} now shows dates as @samp{1996-08-30},
+while it used to show them as @samp{Aug 30 1996}. Preferably,
+people should get used to ISO 8601 dates. Local American dates should
+be made available again with full date localization support, once
+ready. In the meantime, programs not being localizable for dates
+should prefer international dates, that's really the way to go.
+
+Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you
+are curious, it contains a detailed explanation of the ISO 8601 standard.
+
address@hidden table
+
address@hidden Advanced tar
address@hidden Advanced @acronym{GNU} @command{tar} Operations
+
+Now that you have learned the basics of using @acronym{GNU} @command{tar}, you
may want
+to learn about further ways in which @command{tar} can help you.
+
+This chapter presents five, more advanced operations which you probably
+won't use on a daily basis, but which serve more specialized functions.
+We also explain the different styles of options and why you might want
+to use one or another, or a combination of them in your @command{tar}
+commands. Additionally, this chapter includes options which allow you to
+define the output from @command{tar} more carefully, and provide help and
+error correction in special circumstances.
+
address@hidden
address@hidden
+
+
address@hidden
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
address@hidden menu
+
address@hidden Operations
address@hidden The Five Advanced @command{tar} Operations
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+In the last chapter, you learned about the first three operations to
address@hidden This chapter presents the remaining five operations to
address@hidden: @option{--append}, @option{--update}, @option{--concatenate},
address@hidden, and @option{--compare}.
+
+You are not likely to use these operations as frequently as those
+covered in the last chapter; however, since they perform specialized
+functions, they are quite useful when you do need to use them. We
+will give examples using the same directory and files that you created
+in the last chapter. As you may recall, the directory is called
address@hidden, the files are @samp{jazz}, @samp{blues}, @samp{folk},
address@hidden, and the two archive files you created are
address@hidden and @samp{music.tar}.
+
+We will also use the archive files @samp{afiles.tar} and
address@hidden The archive @samp{afiles.tar} contains the members @samp{apple},
address@hidden, and @samp{aspic}; @samp{bfiles.tar} contains the members
address@hidden/birds}, @samp{baboon}, and @samp{./box}.
+
+Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the @file{practice} directory that
+you created in the previous chapter; see @ref{prepare for examples}.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+
+The five operations that we will cover in this chapter are:
+
address@hidden @option
address@hidden --append
address@hidden -r
+Add new entries to an archive that already exists.
address@hidden --update
address@hidden -r
+Add more recent copies of archive members to the end of an archive, if
+they exist.
address@hidden --concatenate
address@hidden --catenate
address@hidden -A
+Add one or more pre-existing archives to the end of another archive.
address@hidden --delete
+Delete items from an archive (does not work on tapes).
address@hidden --compare
address@hidden --diff
address@hidden -d
+Compare archive members to their counterparts in the file system.
address@hidden table
+
address@hidden append
address@hidden How to Add Files to Existing Archives: @option{--append}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden append
+If you want to add files to an existing archive, you don't need to
+create a new archive; you can use @option{--append} (@option{-r}).
+The archive must already exist in order to use @option{--append}. (A
+related operation is the @option{--update} operation; you can use this
+to add newer versions of archive members to an existing archive. To learn how
to
+do this with @option{--update}, @pxref{update}.)
+
+If you use @option{--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 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 @option{--list} (@option{-t}), you will see all
+of those members listed, with their data modification times, owners, etc.
+
+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
+other members would end up in the working directory. This is because
address@hidden 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 address@hidden you give it
address@hidden option, or the disk copy is newer than the
+the one in the archive and you invoke @command{tar} with
address@hidden 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
address@hidden contained three copies of file @file{myfile}, then
+the command
+
address@hidden
+tar --extract --file archive.tar --occurrence=2 myfile
address@hidden smallexample
+
address@hidden
+would extract only the second copy. @xref{Option
+Summary,---occurrence}, for the description of @option{--occurrence}
+option.
+
address@hidden
address@hidden
+
+
address@hidden Members, replacing with other members
address@hidden Replacing members with other members
+If you want to replace an archive member, use @option{--delete} to
+delete the member you want to remove from the archive, , and then use
address@hidden to add the member you want to be in the archive. Note
+that you can not change the order of the archive; the most recently
+added member will still appear last. In this sense, you cannot truly
+``replace'' one member with another. (Replacing one member with another
+will not work on certain types of media, such as tapes; see @ref{delete}
+and @ref{Media}, for more information.)
+
address@hidden
+* appending files:: Appending Files to an Archive
+* multiple::
address@hidden menu
+
address@hidden appending files
address@hidden Appending Files to an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Adding files to an Archive
address@hidden Appending files to an Archive
address@hidden Archives, Appending files to
+
+The simplest way to add a file to an already existing archive is the
address@hidden (@option{-r}) operation, which writes specified
+files into the archive whether or not they are already among the
+archived files.
+
+When you use @option{--append}, you @emph{must} specify file name
+arguments, as there is no default. If you specify a file that already
+exists in the archive, another copy of the file will be added to the
+end of the archive. As with other operations, the member names of the
+newly added files will be exactly the same as their names given on the
+command line. The @option{--verbose} (@option{-v}) option will print
+out the names of the files as they are written into the archive.
+
address@hidden cannot be performed on some tape drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid @command{tar} archive, or else the results of using this
+operation will be unpredictable. @xref{Media}.
+
+To demonstrate using @option{--append} to add a file to an archive,
+create a file called @file{rock} in the @file{practice} directory.
+Make sure you are in the @file{practice} directory. Then, run the
+following @command{tar} command to add @file{rock} to
address@hidden:
+
address@hidden
+$ @kbd{tar --append --file=collection.tar rock}
address@hidden smallexample
+
address@hidden
+If you now use the @option{--list} (@option{-t}) operation, you will see that
address@hidden has been added to the archive:
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
address@hidden smallexample
+
address@hidden multiple
address@hidden Multiple Members with the Same Name
+
+You can use @option{--append} (@option{-r}) to add copies of files
+which have been updated since the archive was created. (However, we
+do not recommend doing this since there is another @command{tar}
+option called @option{--update}; @xref{update}, for more information.
+We describe this use of @option{--append} here for the sake of
+completeness.) When you extract the archive, the older version will
+be effectively lost. This works because files are extracted from an
+archive in the order in which they were archived. Thus, when the
+archive is extracted, a file archived later in time will replace a
+file of the same name which was archived earlier, even though the
+older version of the file will remain in the archive unless you delete
+all versions of the file.
+
+Supposing you change the file @file{blues} and then append the changed
+version to @file{collection.tar}. As you saw above, the original
address@hidden is in the archive @file{collection.tar}. If you change the
+file and append the new version of the file to the archive, there will
+be two copies in the archive. When you extract the archive, the older
+version of the file will be extracted first, and then replaced by the
+newer version when it is extracted.
+
+You can append the new, changed copy of the file @file{blues} to the
+archive in this way:
+
address@hidden
+$ @kbd{tar --append --verbose --file=collection.tar blues}
+blues
address@hidden smallexample
+
address@hidden
+Because you specified the @option{--verbose} option, @command{tar} has
+printed the name of the file being appended as it was acted on. Now
+list the contents of the archive:
+
address@hidden
+$ @kbd{tar --list --verbose --file=collection.tar}
+-rw-r--r-- me user 28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+-rw-r--r-- me user 20 1996-09-23 16:44 rock
+-rw-r--r-- me user 58 1996-10-24 18:30 blues
address@hidden smallexample
+
address@hidden
+The newest version of @file{blues} is now at the end of the archive
+(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.
+
+If you wish to extract the first occurrence of the file @file{blues}
+from the archive, use @option{--occurrence} option, as shown in
+the following example:
+
address@hidden
+$ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
address@hidden smallexample
+
address@hidden, for more information on @option{--extract} and
address@hidden Summary, --occurrence}, for the description of
address@hidden option.
+
address@hidden update
address@hidden Updating an Archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Updating an archive
+
address@hidden update
+In the previous section, you learned how to use @option{--append} to
+add a file to an existing archive. A related operation is
address@hidden (@option{-u}). The @option{--update} operation
+updates a @command{tar} archive by comparing the date of the specified
+archive members against the date of the file with the same name. If
+the file has been modified more recently than the archive member, then
+the newer version of the file is added to the archive (as with
address@hidden).
+
+Unfortunately, you cannot use @option{--update} with magnetic tape drives.
+The operation will fail.
+
address@hidden
address@hidden
+
+
+Both @option{--update} and @option{--append} work by adding to the end
+of the archive. When you extract a file from the archive, only the
+version stored last will wind up in the file system, unless you use
+the @option{--backup} option. @xref{multiple}, for a detailed discussion.
+
address@hidden
+* how to update::
address@hidden menu
+
address@hidden how to update
address@hidden How to Update an Archive Using @option{--update}
+
+You must use file name arguments with the @option{--update}
+(@option{-u}) operation. If you don't specify any files,
address@hidden won't act on any files and won't tell you that it didn't
+do anything (which may end up confusing you).
+
address@hidden note: the above parenthetical added because in fact, this
address@hidden behavior just confused the author. :-)
+
+To see the @option{--update} option at work, create a new file,
address@hidden, in your practice directory, and some extra text to the
+file @file{blues}, using any text editor. Then invoke @command{tar} with
+the @samp{update} operation and the @option{--verbose} (@option{-v})
+option specified, using the names of all the files in the practice
+directory as file name arguments:
+
address@hidden
+$ @kbd{tar --update -v -f collection.tar blues folk rock classical}
+blues
+classical
+$
address@hidden smallexample
+
address@hidden
+Because we have specified verbose mode, @command{tar} prints out the names
+of the files it is working on, which in this case are the names of the
+files that needed to be updated. If you run @samp{tar --list} and look
+at the archive, you will see @file{blues} and @file{classical} at its
+end. There will be a total of two versions of the member @samp{blues};
+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
+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.
+
address@hidden (@option{-u}) is not suitable for performing backups for two
+reasons: it does not change directory content entries, and it
+lengthens the archive every time it is used. The @acronym{GNU} @command{tar}
+options intended specifically for backups are more
+efficient. If you need to run backups, please consult @ref{Backups}.
+
address@hidden concatenate
address@hidden Combining Archives with @option{--concatenate}
+
address@hidden Adding archives to an archive
address@hidden Concatenating Archives
address@hidden concatenate
address@hidden catenate
address@hidden @cindex @option{-A} described
+Sometimes it may be convenient to add a second archive onto the end of
+an archive rather than adding individual files to the archive. To add
+one or more archives to the end of another archive, you should use the
address@hidden (@option{--catenate}, @option{-A}) operation.
+
+To use @option{--concatenate}, give the first archive with
address@hidden 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.
address@hidden 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
address@hidden, @command{tar} will use the value of the environment
+variable @env{TAPE}, or, if this has not been set, the default archive name.
+
address@hidden
address@hidden
+
+
+To demonstrate how @option{--concatenate} works, create two small archives
+called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
+files from @file{practice}:
+
address@hidden
+$ @kbd{tar -cvf bluesrock.tar blues rock}
+blues
+rock
+$ @kbd{tar -cvf folkjazz.tar folk jazz}
+folk
+jazz
address@hidden smallexample
+
address@hidden
+If you like, You can run @samp{tar --list} to make sure the archives
+contain what they are supposed to:
+
address@hidden
+$ @kbd{tar -tvf bluesrock.tar}
+-rw-r--r-- melissa user 105 1997-01-21 19:42 blues
+-rw-r--r-- melissa user 33 1997-01-20 15:34 rock
+$ @kbd{tar -tvf jazzfolk.tar}
+-rw-r--r-- melissa user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
address@hidden smallexample
+
+We can concatenate these two archives with @command{tar}:
+
address@hidden
+$ @kbd{cd ..}
+$ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
address@hidden smallexample
+
+If you now list the contents of the @file{bluesrock.tar}, you will see
+that now it also contains the archive members of @file{jazzfolk.tar}:
+
address@hidden
+$ @kbd{tar --list --file=bluesrock.tar}
+blues
+rock
+folk
+jazz
address@hidden smallexample
+
+When you use @option{--concatenate}, the source and target archives must
+already exist and must have been created using compatible format
+parameters. Notice, that @command{tar} does not check whether the
+archives it concatenates have compatible formats, it does not
+even check if the files are really tar archives.
+
+Like @option{--append} (@option{-r}), this operation cannot be performed on
some
+tape drives, due to deficiencies in the formats those tape drives use.
+
address@hidden @code{concatenate} vs @command{cat}
address@hidden @command{cat} vs @code{concatenate}
+It may seem more intuitive to you to want or try to use @command{cat} to
+concatenate two archives instead of using the @option{--concatenate}
+operation; after all, @command{cat} is the utility for combining files.
+
+However, @command{tar} archives incorporate an end-of-file marker which
+must be removed if the concatenated archives are to be read properly as
+one archive. @option{--concatenate} removes the end-of-archive marker
+from the target archive before each new archive is appended. If you use
address@hidden to combine the archives, the result will not be a valid
address@hidden format archive. If you need to retrieve files from an
+archive that was added to using the @command{cat} utility, use the
address@hidden (@option{-i}) option. @xref{Ignore Zeros}, for further
+information on dealing with archives improperly combined using the
address@hidden shell utility.
+
address@hidden delete
address@hidden Removing Archive Members Using @option{--delete}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Deleting files from an archive
address@hidden Removing files from an archive
+
address@hidden delete
+You can remove members from an archive by using the @option{--delete}
+option. Specify the name of the archive with @option{--file}
+(@option{-f}) and then specify the names of the members to be deleted;
+if you list no member names, nothing will be deleted. The
address@hidden option will cause @command{tar} to print the names
+of the members as they are deleted. As with @option{--extract}, you
+must give the exact member names when using @samp{tar --delete}.
address@hidden will remove all versions of the named file from the
+archive. The @option{--delete} operation can run very slowly.
+
+Unlike other operations, @option{--delete} has no short form.
+
address@hidden Tapes, using @option{--delete} and
address@hidden Deleting from tape archives
+This operation will rewrite the archive. You can only use
address@hidden on an archive if the archive device allows you to
+write to any point on the media, such as a disk; because of this, it
+does not work on magnetic tapes. Do not try to delete an archive member
+from a magnetic tape; the action will not succeed, and you will be
+likely to scramble the archive and damage your tape. There is no safe
+way (except by completely re-writing the archive) to delete files from
+most kinds of magnetic tape. @xref{Media}.
+
+To delete all versions of the file @file{blues} from the archive
address@hidden in the @file{practice} directory, make sure you
+are in that directory, and then,
+
address@hidden
+$ @kbd{tar --list --file=collection.tar}
+blues
+folk
+jazz
+rock
+$ @kbd{tar --delete --file=collection.tar blues}
+$ @kbd{tar --list --file=collection.tar}
+folk
+jazz
+rock
+$
address@hidden smallexample
+
address@hidden
address@hidden
+
+
+The @option{--delete} option has been reported to work properly when
address@hidden acts as a filter from @code{stdin} to @code{stdout}.
+
address@hidden compare
address@hidden Comparing Archive Members with the File System
address@hidden Verifying the currency of an archive
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden compare
+The @option{--compare} (@option{-d}), or @option{--diff} operation compares
+specified archive members against files with the same names, and then
+reports differences in file size, mode, owner, modification date and
+contents. You should @emph{only} specify archive member names, not file
+names. If you do not name any members, then @command{tar} will compare the
+entire archive. If a file is represented in the archive but does not
+exist in the file system, @command{tar} reports a difference.
+
+You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+
address@hidden ignores files in the file system that do not have
+corresponding members in the archive.
+
+The following example compares the archive members @file{rock},
address@hidden and @file{funk} in the archive @file{bluesrock.tar} with
+files of the same name in the file system. (Note that there is no file,
address@hidden; @command{tar} will report an error message.)
+
address@hidden
+$ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
+rock
+blues
+tar: funk not found in archive
address@hidden smallexample
+
+The spirit behind the @option{--compare} (@option{--diff},
address@hidden) 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}.
+
address@hidden create options
address@hidden Options Used by @option{--create}
+
address@hidden address@hidden, additional options}
+The previous chapter described the basics of how to use
address@hidden (@option{-c}) to create an archive from a set of files.
address@hidden This section described advanced options to be used with
address@hidden
+
address@hidden
+* override:: Overriding File Metadata.
+* Ignore Failed Read::
address@hidden menu
+
address@hidden override
address@hidden Overriding File Metadata
+
+As described above, a @command{tar} archive keeps, for each member it contains,
+its @dfn{metadata}, such as modification time, mode and ownership of
+the file. @acronym{GNU} @command{tar} allows to replace these data with other
values
+when adding files to the archive. The options described in this
+section affect creation of archives of any type. For POSIX archives,
+see also @ref{PAX keywords}, for additional ways of controlling
+metadata, stored in the archive.
+
address@hidden @option
address@hidden mode
address@hidden address@hidden
+
+When adding files to an archive, @command{tar} will use
address@hidden for the archive members, rather than the permissions
+from the files. @var{permissions} can be specified either as an octal
+number or as symbolic permissions, like with
address@hidden (@xref{File permissions, Permissions, File
+permissions, fileutils, @acronym{GNU} file utilities}. This reference
+also has useful information for those not being overly familiar with
+the UNIX permission system). Using latter syntax allows for
+more flexibility. For example, the value @samp{a+rw} adds read and write
+permissions for everybody, while retaining executable bits on directories
+or on any other file already marked as executable:
+
address@hidden
+$ @kbd{tar -c -f archive.tar --mode='a+rw' .}
address@hidden smallexample
+
address@hidden address@hidden
address@hidden mtime
+
+When adding files to an archive, @command{tar} will use @var{date} as
+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
+with @samp{/} or @samp{.}. In the latter case, the modification time
+of that file will be used.
+
+The following example will set the modification date to 00:00:00 UTC,
+January 1, 1970:
+
address@hidden
+$ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .}
address@hidden smallexample
+
address@hidden
+When used with @option{--verbose} (@pxref{verbose tutorial}) @acronym{GNU}
@command{tar}
+will try to convert the specified date back to its textual
+representation and compare it with the one given with
address@hidden options. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date.
+
+For example:
+
address@hidden
+$ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
+tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+13:06:29.152478
address@hidden
address@hidden smallexample
+
address@hidden address@hidden
address@hidden owner
+
+Specifies that @command{tar} should use @var{user} as the owner of members
+when creating archives, instead of the user associated with the source
+file. The argument @var{user} can be either an existing user symbolic
+name, or a decimal numeric user ID.
+
+There is no value indicating a missing number, and @samp{0} usually means
address@hidden Some people like to force @samp{0} as the value to offer in
+their distributions for the owner of files, because the @code{root} user is
+anonymous anyway, so that might as well be the owner of anonymous
+archives. For example:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --owner=0 .}
+# @r{Or:}
+$ @kbd{tar -c -f archive.tar --owner=root .}
address@hidden group
address@hidden smallexample
+
address@hidden address@hidden
address@hidden group
+
+Files added to the @command{tar} archive will have a group id of @var{group},
+rather than the group from the source file. The argument @var{group}
+can be either an existing group symbolic name, or a decimal numeric group ID.
address@hidden table
+
address@hidden Ignore Failed Read
address@hidden Ignore Fail Read
+
address@hidden @option
address@hidden --ignore-failed-read
address@hidden ignore-failed-read
+Do not exit with nonzero on unreadable files or directories.
address@hidden table
+
address@hidden extract options
address@hidden Options Used by @option{--extract}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden address@hidden, additional options}
+The previous chapter showed how to use @option{--extract} to extract
+an archive into the file system. Various options cause @command{tar} to
+extract more information than just file contents, such as the owner,
+the permissions, the modification date, and so forth. This section
+presents options to be used with @option{--extract} when certain special
+considerations arise. You may review the information presented in
address@hidden for more basic information about the
address@hidden operation.
+
address@hidden
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
address@hidden menu
+
address@hidden Reading
address@hidden Options to Help Read Archives
address@hidden Options when reading archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Reading incomplete records
address@hidden Records, incomplete
address@hidden read-full-records
+Normally, @command{tar} will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
address@hidden will report an error. However, some devices do not always
+return full records, or do not require the last record of an archive to
+be padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the @option{--read-full-records}
(@option{-B}) option
+in conjunction with the @option{--extract} or @option{--list} operations.
address@hidden
+
+The @option{--read-full-records} (@option{-B}) option is turned on by default
when
address@hidden reads an archive from standard input, or from a remote
+machine. This is because on BSD Unix systems, attempting to read a
+pipe returns however much happens to be in the pipe, even if it is
+less than was requested. If this option were not enabled, @command{tar}
+would fail as soon as it read an incomplete record from the pipe.
+
+If you're not sure of the blocking factor of an archive, you can
+read the archive by specifying @option{--read-full-records} (@option{-B}) and
address@hidden@var{512-size}} (@option{-b
address@hidden), using a blocking factor larger than what the archive
+uses. This lets you avoid having to determine the blocking factor
+of an archive. @xref{Blocking Factor}.
+
address@hidden
+* read full records::
+* Ignore Zeros::
address@hidden menu
+
address@hidden read full records
address@hidden Reading Full Records
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden read-full-records
address@hidden --read-full-records
address@hidden -B
+Use in conjunction with @option{--extract} (@option{--get},
address@hidden) to read an archive which contains incomplete records, or
+one which has a blocking factor less than the one specified.
address@hidden table
+
address@hidden Ignore Zeros
address@hidden Ignoring Blocks of Zeros
+
address@hidden End-of-archive blocks, ignoring
address@hidden Ignoring end-of-archive blocks
address@hidden ignore-zeros
+Normally, @command{tar} stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
address@hidden (@option{-i}) allows @command{tar} to
+completely read an archive which contains a block of zeros before the
+end (i.e., a damaged archive, or one that was created by concatenating
+several archives together).
+
+The @option{--ignore-zeros} (@option{-i}) option is turned off by default
because many
+versions of @command{tar} write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read. @acronym{GNU}
@command{tar}
+does not write after the end of an archive, but seeks to
+maintain compatiblity among archiving utilities.
+
address@hidden @option
address@hidden --ignore-zeros
address@hidden -i
+To ignore blocks of zeros (i.e., end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
address@hidden or @option{--list}.
address@hidden table
+
address@hidden Writing
address@hidden Changing How @command{tar} Writes Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden
+* Dealing with Old Files::
+* Overwrite Old Files::
+* Keep Old Files::
+* Keep Newer Files::
+* Unlink First::
+* Recursive Unlink::
+* Data Modification Times::
+* Setting Access Permissions::
+* Directory Modification Times and Permissions::
+* Writing to Standard Output::
+* Writing to an External Program::
+* remove files::
address@hidden menu
+
address@hidden Dealing with Old Files
address@hidden Options Controlling the Overwriting of Existing Files
+
address@hidden address@hidden, introduced}
+When extracting files, if @command{tar} discovers that the extracted
+file already exists, it normally replaces the file by removing it before
+extracting it, to prevent confusion in the presence of hard or symbolic
+links. (If the existing file is a symbolic link, it is removed, not
+followed.) However, if a directory cannot be removed because it is
+nonempty, @command{tar} normally overwrites its metadata (ownership,
+permission, etc.). The @option{--overwrite-dir} option enables this
+default behavior. To be more cautious and preserve the metadata of
+such a directory, use the @option{--no-overwrite-dir} option.
+
address@hidden Overwriting old files, prevention
address@hidden address@hidden, introduced}
+To be even more cautious and prevent existing files from being replaced, use
+the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar}
to refuse
+to replace or update a file that already exists, i.e., a file with the
+same name as an archive member prevents extraction of that archive
+member. Instead, it reports an error.
+
address@hidden address@hidden, introduced}
+To be more aggressive about altering existing files, use the
address@hidden option. It causes @command{tar} to overwrite
+existing files and to follow existing symbolic links when extracting.
+
address@hidden Protecting old files
+Some people argue that @acronym{GNU} @command{tar} should not hesitate
+to overwrite files with other files when extracting. When extracting
+a @command{tar} archive, they expect to see a faithful copy of the
+state of the file system when the archive was created. It is debatable
+that this would always be a proper behavior. For example, suppose one
+has an archive in which @file{usr/local} is a link to
address@hidden/local2}. Since then, maybe the site removed the link and
+renamed the whole hierarchy from @file{/usr/local2} to
address@hidden/usr/local}. Such things happen all the time. I guess it would
+not be welcome at all that @acronym{GNU} @command{tar} removes the
+whole hierarchy just to make room for the link to be reinstated
+(unless it @emph{also} simultaneously restores the full
address@hidden/usr/local2}, of course!) @acronym{GNU} @command{tar} is indeed
+able to remove a whole hierarchy to reestablish a symbolic link, for
+example, but @emph{only if} @option{--recursive-unlink} is specified
+to allow this behavior. In any case, single files are silently
+removed.
+
address@hidden address@hidden, introduced}
+Finally, the @option{--unlink-first} (@option{-U}) option can improve
performance in
+some cases by causing @command{tar} to remove files unconditionally
+before extracting them.
+
address@hidden Overwrite Old Files
address@hidden Overwrite Old Files
+
address@hidden @option
address@hidden overwrite
address@hidden --overwrite
+Overwrite existing files and directory metadata when extracting files
+from an archive.
+
+This causes @command{tar} to write extracted files into the file system without
+regard to the files already on the system; i.e., files with the same
+names as archive members are overwritten when the archive is extracted.
+It also causes @command{tar} to extract the ownership, permissions,
+and time stamps onto any preexisting files or directories.
+If the name of a corresponding file name is a symbolic link, the file
+pointed to by the symbolic link will be overwritten instead of the
+symbolic link itself (if this is possible). Moreover, special devices,
+empty directories and even symbolic links are automatically removed if
+they are in the way of extraction.
+
+Be careful when using the @option{--overwrite} option, particularly when
+combined with the @option{--absolute-names} (@option{-P}) option, as this
combination
+can change the contents, ownership or permissions of any file on your
+system. Also, many systems do not take kindly to overwriting files that
+are currently being executed.
+
address@hidden overwrite-dir
address@hidden --overwrite-dir
+Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
address@hidden table
+
address@hidden Keep Old Files
address@hidden Keep Old Files
+
address@hidden @option
address@hidden keep-old-files
address@hidden --keep-old-files
address@hidden -k
+Do not replace existing files from archive. The
address@hidden (@option{-k}) option prevents @command{tar}
+from replacing existing files with files with the same name from the
+archive. The @option{--keep-old-files} option is meaningless with
address@hidden (@option{-t}). Prevents @command{tar} from replacing
+files in the file system during extraction.
address@hidden table
+
address@hidden Keep Newer Files
address@hidden Keep Newer Files
+
address@hidden @option
address@hidden keep-newer-files
address@hidden --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @option{--list} (@option{-t}).
address@hidden table
+
address@hidden Unlink First
address@hidden Unlink First
+
address@hidden @option
address@hidden unlink-first
address@hidden --unlink-first
address@hidden -U
+Remove files before extracting over them.
+This can make @command{tar} run a bit faster if you know in advance
+that the extracted files all need to be removed. Normally this option
+slows @command{tar} down slightly, so it is disabled by default.
address@hidden table
+
address@hidden Recursive Unlink
address@hidden Recursive Unlink
+
address@hidden @option
address@hidden recursive-unlink
address@hidden --recursive-unlink
+When this option is specified, try removing files and directory hierarchies
+before extracting over them. @emph{This is a dangerous option!}
address@hidden table
+
+If you specify the @option{--recursive-unlink} option,
address@hidden removes @emph{anything} that keeps you from extracting a file
+as far as current permissions will allow it. This could include removal
+of the contents of a full directory hierarchy.
+
address@hidden Data Modification Times
address@hidden Setting Data Modification Times
+
address@hidden Data modification times of extracted files
address@hidden Modification times of extracted files
+Normally, @command{tar} sets the data modification times of extracted
+files to the corresponding times recorded for the files in the archive, but
+limits the permissions of extracted files by the current @code{umask}
+setting.
+
+To set the data modification times of extracted files to the time when
+the files were extracted, use the @option{--touch} (@option{-m}) option in
+conjunction with @option{--extract} (@option{--get}, @option{-x}).
+
address@hidden @option
address@hidden touch
address@hidden --touch
address@hidden -m
+Sets the data modification time of extracted archive members to the time
+they were extracted, not the time recorded for them in the archive.
+Use in conjunction with @option{--extract} (@option{--get}, @option{-x}).
address@hidden table
+
address@hidden Setting Access Permissions
address@hidden Setting Access Permissions
+
address@hidden Permissions of extracted files
address@hidden Modes of extracted files
+To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use @option{--same-permissions}
+in conjunction with the @option{--extract} (@option{--get},
address@hidden) operation.
+
address@hidden @option
address@hidden preserve-permissions
address@hidden same-permissions
address@hidden --preserve-permissions
address@hidden --same-permissions
address@hidden @itemx --ignore-umask
address@hidden -p
+Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
address@hidden (@option{--get}, @option{-x}).
address@hidden table
+
address@hidden Directory Modification Times and Permissions
address@hidden Directory Modification Times and Permissions
+
+After sucessfully extracting a file member, @acronym{GNU} @command{tar}
normally
+restores its permissions and modification times, as described in the
+previous sections. This cannot be done for directories, because
+after extracting a directory @command{tar} will almost certainly
+extract files into that directory and this will cause the directory
+modification time to be updated. Moreover, restoring that directory
+permissions may not permit file creation within it. Thus, restoring
+directory permissions and modification times must be delayed at least
+until all files have been extracted into that directory. @acronym{GNU}
@command{tar}
+restores directories using the following approach.
+
+The extracted directories are created with the mode specified in the
+archive, as modified by the umask of the user, which gives sufficient
+permissions to allow file creation. The meta-information about the
+directory is recorded in the temporary list of directories. When
+preparing to extract next archive member, @acronym{GNU} @command{tar} checks
if the
+directory prefix of this file contains the remembered directory. If
+it does not, the program assumes that all files have been extracted
+into that directory, restores its modification time and permissions
+and removes its entry from the internal list. This approach allows
+to correctly restore directory meta-information in the majority of
+cases, while keeping memory requirements sufficiently small. It is
+based on the fact, that most @command{tar} archives use the predefined
+order of members: first the directory, then all the files and
+subdirectories in that directory.
+
+However, this is not always true. The most important exception are
+incremental archives (@pxref{Incremental Dumps}). The member order in
+an incremental archive is reversed: first all directory members are
+stored, followed by other (non-directory) members. So, when extracting
+from incremental archives, @acronym{GNU} @command{tar} alters the above
procedure. It
+remebers all restored directories, and restores their meta-data
+only after the entire archive has been processed. Notice, that you do
+not need to specity any special options for that, as @acronym{GNU}
@command{tar}
+automatically detects archives in incremental format.
+
+There may be cases, when such processing is required for normal archives
+too. Consider the following example:
+
address@hidden
address@hidden
+$ @kbd{tar --no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2}
+foo/
+foo/file1
+bar/
+bar/file
+foo/file2
address@hidden group
address@hidden smallexample
+
+During the normal operation, after encountering @file{bar}
address@hidden @command{tar} will assume that all files from the directory
@file{foo}
+were already extracted and will therefore restore its timestamp and
+permission bits. However, after extracting @file{foo/file2} the
+directory timestamp will be offset again.
+
+To correctly restore directory meta-information in such cases, use
address@hidden command line option:
+
address@hidden @option
address@hidden delay-directory-restore
address@hidden --delay-directory-restore
+Delays restoring of the modification times and permissions of extracted
+directories until the end of extraction. This way, correct
+meta-information is restored even if the archive has unusual member
+ordering.
+
address@hidden no-delay-directory-restore
address@hidden --no-delay-directory-restore
+Cancel the effect of the previous @option{--delay-directory-restore}.
+Use this option if you have used @option{--delay-directory-restore} in
address@hidden variable (@pxref{TAR_OPTIONS}) and wish to
+temporarily disable it.
address@hidden table
+
address@hidden Writing to Standard Output
address@hidden Writing to Standard Output
+
address@hidden Writing extracted files to standard output
address@hidden Standard output, writing extracted files to
+To write the extracted files to the standard output, instead of
+creating the files on the file system, use @option{--to-stdout} (@option{-O})
in
+conjunction with @option{--extract} (@option{--get}, @option{-x}). This
option is useful if you are
+extracting files to send them through a pipe, and do not need to
+preserve them in the file system. If you extract multiple members,
+they appear on standard output concatenated, in the order they are
+found in the archive.
+
address@hidden @option
address@hidden to-stdout
address@hidden --to-stdout
address@hidden -O
+Writes files to the standard output. Use only in conjunction with
address@hidden (@option{--get}, @option{-x}). When this option is
+used, instead of creating the files specified, @command{tar} writes
+the contents of the files extracted to its standard output. This may
+be useful if you are only extracting the files in order to send them
+through a pipe. This option is meaningless with @option{--list}
+(@option{-t}).
address@hidden table
+
+This can be useful, for example, if you have a tar archive containing
+a big file and don't want to store the file on disk before processing
+it. You can use a command like this:
+
address@hidden
+tar -xOzf foo.tgz bigfile | process
address@hidden smallexample
+
+or even like this if you want to process the concatenation of the files:
+
address@hidden
+tar -xOzf foo.tgz bigfile1 bigfile2 | process
address@hidden smallexample
+
+Hovewer, @option{--to-command} may be more convenient for use with
+multiple files. See the next section.
+
address@hidden Writing to an External Program
address@hidden Writing to an External Program
+
+You can instruct @command{tar} to send the contents of each extracted
+file to the standard input of an external program:
+
address@hidden @option
address@hidden to-command
address@hidden address@hidden
+Extract files and pipe their contents to the standard input of
address@hidden When this option is used, instead of creating the
+files specified, @command{tar} invokes @var{command} and pipes the
+contents of the files to its standard output. @var{Command} may
+contain command line arguments. The program is executed via
address@hidden -c}. Notice, that @var{command} is executed once for each
regular file
+extracted. Non-regular files (directories, etc.) are ignored when this
+option is used.
address@hidden table
+
+The command can obtain the information about the file it processes
+from the following environment variables:
+
address@hidden @var
address@hidden TAR_FILETYPE, to-command environment
address@hidden TAR_FILETYPE
+Type of the file. It is a single letter with the following meaning:
+
address@hidden @columnfractions 0.10 0.90
address@hidden f @tab Regular file
address@hidden d @tab Directory
address@hidden l @tab Symbolic link
address@hidden h @tab Hard link
address@hidden b @tab Block device
address@hidden c @tab Character device
address@hidden multitable
+
+Currently only regular files are supported.
+
address@hidden TAR_MODE, to-command environment
address@hidden TAR_MODE
+File mode, an octal number.
+
address@hidden TAR_FILENAME, to-command environment
address@hidden TAR_FILENAME
+The name of the file.
+
address@hidden TAR_REALNAME, to-command environment
address@hidden TAR_REALNAME
+Name of the file as stored in the archive.
+
address@hidden TAR_UNAME, to-command environment
address@hidden TAR_UNAME
+Name of the file owner.
+
address@hidden TAR_GNAME, to-command environment
address@hidden TAR_GNAME
+Name of the file owner group.
+
address@hidden TAR_ATIME, to-command environment
address@hidden TAR_ATIME
+Time of last access. It is a decimal number, representing seconds
+since the epoch. If the archive provides times with nanosecond
+precision, the nanoseconds are appended to the timestamp after a
+decimal point.
+
address@hidden TAR_MTIME, to-command environment
address@hidden TAR_MTIME
+Time of last modification.
+
address@hidden TAR_CTIME, to-command environment
address@hidden TAR_CTIME
+Time of last status change.
+
address@hidden TAR_SIZE, to-command environment
address@hidden TAR_SIZE
+Size of the file.
+
address@hidden TAR_UID, to-command environment
address@hidden TAR_UID
+UID of the file owner.
+
address@hidden TAR_GID, to-command environment
address@hidden TAR_GID
+GID of the file owner.
address@hidden table
+
+In addition to these variables, @env{TAR_VERSION} contains the
address@hidden @command{tar} version number.
+
+If @var{command} exits with a non-0 status, @command{tar} will print
+an error message similar to the following:
+
address@hidden
+tar: 2345: Child returned status 1
address@hidden smallexample
+
+Here, @samp{2345} is the PID of the finished process.
+
+If this behavior is not wanted, use @option{--ignore-command-error}:
+
address@hidden @option
address@hidden ignore-command-error
address@hidden --ignore-command-error
+Ignore exit codes of subprocesses. Notice that if the program
+exits on signal or otherwise terminates abnormally, the error message
+will be printed even if this option is used.
+
address@hidden no-ignore-command-error
address@hidden --no-ignore-command-error
+Cancel the effect of any previous @option{--ignore-command-error}
+option. This option is useful if you have set
address@hidden in @env{TAR_OPTIONS}
+(@pxref{TAR_OPTIONS}) and wish to temporarily cancel it.
address@hidden table
+
address@hidden remove files
address@hidden Removing Files
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden remove-files
address@hidden --remove-files
+Remove files after adding them to the archive.
address@hidden table
+
address@hidden Scarce
address@hidden Coping with Scarce Resources
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Small memory
address@hidden Running out of space
+
address@hidden
+* Starting File::
+* Same Order::
address@hidden menu
+
address@hidden Starting File
address@hidden Starting File
+
address@hidden @option
address@hidden starting-file
address@hidden address@hidden
address@hidden -K @var{name}
+Starts an operation in the middle of an archive. Use in conjunction
+with @option{--extract} (@option{--get}, @option{-x}) or @option{--list}
(@option{-t}).
address@hidden table
+
address@hidden Middle of the archive, starting in the
+If a previous attempt to extract files failed due to lack of disk
+space, you can use @address@hidden (@option{-K
address@hidden) to start extracting only after member @var{name} of the
+archive. This assumes, of course, that there is now free space, or
+that you are now extracting into a different file system. (You could
+also choose to suspend @command{tar}, remove unnecessary files from
+the file system, and then restart the same @command{tar} operation.
+In this case, @option{--starting-file} is not necessary.
address@hidden Dumps}, @xref{interactive}, and @ref{exclude}.)
+
address@hidden Same Order
address@hidden Same Order
+
address@hidden @option
address@hidden Large lists of file names on small machines
address@hidden same-order
address@hidden preserve-order
address@hidden --same-order
address@hidden --preserve-order
address@hidden -s
+To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with @option{--compare} (@option{--diff},
address@hidden), @option{--list} (@option{-t}) or @option{--extract}
+(@option{--get}, @option{-x}).
address@hidden table
+
+The @option{--same-order} (@option{--preserve-order}, @option{-s}) option
tells @command{tar} that the list of file
+names to be listed or extracted is sorted in the same order as the
+files in the archive. This allows a large list of names to be used,
+even on a small machine that would not otherwise be able to hold all
+the names in memory at the same time. Such a sorted list can easily be
+created by running @samp{tar -t} on the archive and editing its output.
+
+This option is probably never needed on modern computer systems.
+
address@hidden backup
address@hidden Backup options
+
address@hidden backup options
+
address@hidden @command{tar} offers options for making backups of files
+before writing new versions. These options control the details of
+these backups. They may apply to the archive itself before it is
+created or rewritten, as well as individual extracted members. Other
address@hidden programs (@command{cp}, @command{install}, @command{ln},
+and @command{mv}, for example) offer similar options.
+
+Backup options may prove unexpectedly useful when extracting archives
+containing many members having identical name, or when extracting archives
+on systems having file name limitations, making different members appear
+has having similar names through the side-effect of name truncation.
+(This is true only if we have a good scheme for truncated backup names,
+which I'm not sure at all: I suspect work is needed in this area.)
+When any existing file is backed up before being overwritten by extraction,
+then clashing files are automatically be renamed to be unique, and the
+true name is kept for only the last file of a series of clashing files.
+By using verbose mode, users may track exactly what happens.
+
+At the detail level, some decisions are still experimental, and may
+change in the future, we are waiting comments from our users. So, please
+do not learn to depend blindly on the details of the backup features.
+For example, currently, directories themselves are never renamed through
+using these options, so, extracting a file over a directory still has
+good chances to fail. Also, backup options apply to created archives,
+not only to extracted members. For created archives, backups will not
+be attempted when the archive is a block or character device, or when it
+refers to a remote file.
+
+For the sake of simplicity and efficiency, backups are made by renaming old
+files prior to creation or extraction, and not by copying. The original
+name is restored if the file creation fails. If a failure occurs after a
+partial extraction of a file, both the backup and the partially extracted
+file are kept.
+
address@hidden @samp
address@hidden address@hidden
address@hidden backup
address@hidden VERSION_CONTROL
address@hidden backups
+Back up files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+
+Use @var{method} to determine the type of backups made.
+If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
+environment variable. And if @env{VERSION_CONTROL} is not set,
+use the @samp{existing} method.
+
address@hidden version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the same values for @var{method} are accepted as in Emacs. This option
+also allows more descriptive names. The valid @var{method}s are:
+
address@hidden @samp
address@hidden t
address@hidden numbered
address@hidden numbered @r{backup method}
+Always make numbered backups.
+
address@hidden nil
address@hidden existing
address@hidden existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
address@hidden never
address@hidden simple
address@hidden simple @r{backup method}
+Always make simple backups.
+
address@hidden table
+
address@hidden address@hidden
address@hidden suffix
address@hidden backup suffix
address@hidden SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{--backup}. If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
address@hidden table
+
address@hidden Applications
address@hidden Notable @command{tar} Usages
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
address@hidden uuencode
+You can easily use archive files to transport a group of files from
+one system to another: put all relevant files into an archive on one
+computer system, transfer the archive to another system, and extract
+the contents there. The basic transfer medium might be magnetic tape,
+Internet FTP, or even electronic mail (though you must encode the
+archive with @command{uuencode} in order to transport it properly by
+mail). Both machines do not have to use the same operating system, as
+long as they both support the @command{tar} program.
+
+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:
+
address@hidden
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
address@hidden smallexample
+
address@hidden
+You can avoid subshells by using @option{-C} option:
+
address@hidden
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
address@hidden smallexample
+
address@hidden
+The command also works using short option forms:
+
address@hidden
+$ @kbd{(cd sourcedir; tar --create --file=- . ) \
+ | (cd targetdir; tar --extract --file=-)}
+# Or:
+$ @kbd{tar --directory sourcedir --create --file=- . ) \
+ | tar --directory targetdir --extract --file=-}
address@hidden smallexample
+
address@hidden
+This is one of the easiest methods to transfer a @command{tar} archive.
+
address@hidden looking ahead
address@hidden Looking Ahead: The Rest of this Manual
+
+You have now seen how to use all eight of the operations available to
address@hidden, and a number of the possible options. The next chapter
+explains how to choose and change file and archive names, how to use
+files to store names of other files which you can then call as
+arguments to @command{tar} (this can help you save time if you expect to
+archive the same list of files a number of times), and so forth.
address@hidden
address@hidden
+
+
+If there are too many files to conveniently list on the command line,
+you can list the names in a file, and @command{tar} will read that file.
address@hidden
+
+There are various ways of causing @command{tar} to skip over some files,
+and not archive them. @xref{Choosing}.
+
address@hidden Backups
address@hidden Performing Backups and Restoring Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @command{tar} is distributed along with the scripts
+which the Free Software Foundation uses for performing backups. There
+is no corresponding scripts available yet for doing restoration of
+files. Even if there is a good chance those scripts may be satisfying
+to you, they are not the only scripts or methods available for doing
+backups and restore. You may well create your own, or use more
+sophisticated packages dedicated to that purpose.
+
+Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
+This is free software, and it is available at these places:
+
address@hidden
+http://www.cs.umd.edu/projects/amanda/amanda.html
+ftp://ftp.cs.umd.edu/pub/amanda
address@hidden smallexample
+
address@hidden
address@hidden
+
+
+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
+all the files in that file system. Those archives can then be used to
+restore any or all of those files (for instance if a disk crashes or a
+file is accidentally deleted). File system @dfn{backups} are also
+called @dfn{dumps}.
+
address@hidden
+* Full Dumps:: Using @command{tar} to Perform Full Dumps
+* Incremental Dumps:: Using @command{tar} to Perform Incremental
Dumps
+* Backup Levels:: Levels of Backups
+* Backup Parameters:: Setting Parameters for Backups and Restoration
+* Scripted Backups:: Using the Backup Scripts
+* Scripted Restoration:: Using the Restore Script
address@hidden menu
+
address@hidden Full Dumps
address@hidden Using @command{tar} to Perform Full Dumps
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden full dumps
address@hidden dumps, full
+
address@hidden corrupted archives
+Full dumps should only be made when no other people or programs
+are modifying files in the file system. If files are modified while
address@hidden is making the backup, they may not be stored properly in
+the archive, in which case you won't be able to restore them if you
+have to. (Files not being modified are written with no trouble, and do
+not corrupt the entire archive.)
+
+You will want to use the @address@hidden
+(@option{-V @var{archive-label}}) option to give the archive a
+volume label, so you can tell what this archive is even if the label
+falls off the tape, or anything like that.
+
+Unless the file system you are dumping is guaranteed to fit on
+one volume, you will need to use the @option{--multi-volume} (@option{-M})
option.
+Make sure you have enough tapes on hand to complete the backup.
+
+If you want to dump each file system separately you will need to use
+the @option{--one-file-system} option to prevent
address@hidden from crossing file system boundaries when storing
+(sub)directories.
+
+The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
+option is not needed, since this is a complete copy of everything in
+the file system, and a full restore from this backup would only be
+done onto a completely
+empty disk.
+
+Unless you are in a hurry, and trust the @command{tar} program (and your
+tapes), it is a good idea to use the @option{--verify} (@option{-W})
+option, to make sure your files really made it onto the dump properly.
+This will also detect cases where the file was modified while (or just
+after) it was being archived. Not all media (notably cartridge tapes)
+are capable of being verified, unfortunately.
+
address@hidden Incremental Dumps
address@hidden Using @command{tar} to Perform Incremental Dumps
+
address@hidden backup} is a special form of @acronym{GNU} @command{tar} archive
that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+
address@hidden @command{tar} currently offers two options for handling
incremental
+backups: @address@hidden (@option{-g
address@hidden) and @option{--incremental} (@option{-G}).
+
address@hidden listed-incremental
+The option @option{--listed-incremental} instructs tar to operate on
+an incremental archive with additional metadata stored in a standalone
+file, called a @dfn{snapshot file}. The purpose of this file is to help
+determine which files have been changed, added or deleted since the
+last backup, so that the next incremental backup will contain only
+modified files. The name of the snapshot file is given as an argument
+to the option:
+
address@hidden @option
address@hidden address@hidden
address@hidden -g @var{file}
+ Handle incremental backups with snapshot data in @var{file}.
address@hidden table
+
+To create an incremental backup, you would use
address@hidden together with @option{--create}
+(@pxref{create}). For example:
+
address@hidden
+$ @kbd{tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
address@hidden smallexample
+
+This will create in @file{archive.1.tar} an incremental backup of
+the @file{/usr} file system, storing additional metadata in the file
address@hidden/var/log/usr.snar}. If this file does not exist, it will be
+created. The created archive will then be a @dfn{level 0 backup};
+please see the next section for more on backup levels.
+
+Otherwise, if the file @file{/var/log/usr.snar} exists, it
+determines which files are modified. In this case only these files will be
+stored in the archive. Suppose, for example, that after running the
+above command, you delete file @file{/usr/doc/old} and create
+directory @file{/usr/local/db} with the following contents:
+
address@hidden
+$ @kbd{ls /usr/local/db}
+/usr/local/db/data
+/usr/local/db/index
address@hidden smallexample
+
+Some time later you create another incremental backup. You will
+then see:
+
address@hidden
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr}
+tar: usr/local/db: Directory is new
+usr/local/db/
+usr/local/db/data
+usr/local/db/index
address@hidden smallexample
+
address@hidden
+The created archive @file{archive.2.tar} will contain only these
+three members. This archive is called a @dfn{level 1 backup}. Notice
+that @file{/var/log/usr.snar} will be updated with the new data, so if
+you plan to create more @samp{level 1} backups, it is necessary to
+create a working copy of the snapshot file before running
address@hidden The above example will then be modified as follows:
+
address@hidden
+$ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+$ @kbd{tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr}
address@hidden smallexample
+
+Incremental dumps depend crucially on time stamps, so the results are
+unreliable if you modify a file's time stamps during dumping (e.g.,
+with the @option{--atime-preserve=replace} option), or if you set the clock
+backwards.
+
+Metadata stored in snapshot files include device numbers, which,
+obviously is supposed to be a non-volatile value. However, it turns
+out that NFS devices have undependable values when an automounter
+gets in the picture. This can lead to a great deal of spurious
+redumping in incremental dumps, so it is somewhat useless to compare
+two NFS devices numbers over time. The solution implemented currently
+is to considers all NFS devices as being equal when it comes to
+comparing directories; this is fairly gross, but there does not seem
+to be a better way to go.
+
+Note that incremental archives use @command{tar} extensions and may
+not be readable by address@hidden versions of the @command{tar} program.
+
address@hidden address@hidden, using with @option{--extract}}
address@hidden address@hidden, using with @option{--listed-incremental}}
+To extract from the incremental dumps, use
address@hidden together with @option{--extract}
+option (@pxref{extracting files}). In this case, @command{tar} does
+not need to access snapshot file, since all the data necessary for
+extraction are stored in the archive itself. So, when extracting, you
+can give whatever argument to @option{--listed-incremental}, the usual
+practice is to use @option{--listed-incremental=/dev/null}.
+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
+option, @pxref{incremental-op}).
+
+When extracting from the incremental backup @acronym{GNU} @command{tar}
attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will @emph{delete} those files in the file
+system that did not exist in their directories when the archive was
+created. If you have created several levels of incremental files,
+then in order to restore the exact contents the file system had when
+the last level was created, you will need to restore from all backups
+in turn. Continuing our example, to restore the state of @file{/usr}
+file system, one would address@hidden, that since both archives
+were created withouth @option{-P} option (@pxref{absolute}), these
+commands should be run from the root file system.}:
+
address@hidden
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar}
+$ @kbd{tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar}
address@hidden smallexample
+
+To list the contents of an incremental archive, use @option{--list}
+(@pxref{list}), as usual. To obtain more information about the
+archive, use @option{--listed-incremental} or @option{--incremental}
+combined with two @option{--verbose} address@hidden
address@hidden options were selected to avoid breaking usual
+verbose listing output (@option{--list --verbose}) when using in
+scripts.
+
address@hidden address@hidden, using with @option{--list}}
address@hidden address@hidden, using with @option{--list}}
address@hidden address@hidden, using with @option{--incremental}}
address@hidden address@hidden, using with @option{--listed-incremental}}
+Versions of @acronym{GNU} @command{tar} up to 1.15.1 used to dump verbatim
binary
+contents of the DUMPDIR header (with terminating nulls) when
address@hidden or @option{--listed-incremental} option was
+given, no matter what the verbosity level. This behavior, and,
+especially, the binary output it produced were considered incovenient
+and were changed in version 1.16}:
+
address@hidden
address@hidden --list --incremental --verbose --verbose archive.tar}
address@hidden smallexample
+
+This command will print, for each directory in the archive, the list
+of files in that directory at the time the archive was created. This
+information is put out in a format which is both human-readable and
+unambiguous for a program: each file name is printed as
+
address@hidden
address@hidden @var{file}
address@hidden smallexample
+
address@hidden
+where @var{x} is a letter describing the status of the file: @samp{Y}
+if the file is present in the archive, @samp{N} if the file is not
+included in the archive, or a @samp{D} if the file is a directory (and
+is included in the archive). @xref{Dumpdir}, for the detailed
+description of dumpdirs and status codes. Each such
+line is terminated by a newline character. The last line is followed
+by an additional newline to indicate the end of the data.
+
address@hidden option @option{--incremental} (@option{-G})
+gives the same behavior as @option{--listed-incremental} when used
+with @option{--list} and @option{--extract} options. When used with
address@hidden option, it creates an incremental archive without
+creating snapshot file. Thus, it is impossible to create several
+levels of incremental backups with @option{--incremental} option.
+
address@hidden Backup Levels
address@hidden Levels of Backups
+
+An archive containing all the files in the file system is called a
address@hidden backup} or @dfn{full dump}. You could insure your data by
+creating a full dump every day. This strategy, however, would waste a
+substantial amount of archive media and user time, as unchanged files
+are daily re-archived.
+
+It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can use @dfn{incremental dumps}. A @dfn{level
+one} dump archives all the files that have changed since the last full
+dump.
+
+A typical dump strategy would be to perform a full dump once a week,
+and a level one dump once a day. This means some versions of files
+will in fact be archived more than once, but this dump strategy makes
+it possible to restore a file system to within one day of accuracy by
+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).
+
address@hidden @command{tar} comes with scripts you can use to do full
+and level-one (actually, even level-two and so on) dumps. Using
+scripts (shell programs) to perform backups and restoration is a
+convenient and reliable alternative to typing out file name lists
+and @command{tar} commands by hand.
+
+Before you use these scripts, you need to edit the file
address@hidden, which specifies parameters used by the backup
+scripts and by the restore script. This file is usually located
+in @file{/etc/backup} directory. @xref{Backup Parameters}, for its
+detailed description. Once the backup parameters are set, you can
+perform backups or restoration by running the appropriate script.
+
+The name of the backup script is @code{backup}. The name of the
+restore script is @code{restore}. The following sections describe
+their use in detail.
+
address@hidden Note:} The backup and restoration scripts are
+designed to be used together. While it is possible to restore files by
+hand from an archive which was created using a backup script, and to create
+an archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. @xref{Incremental Dumps}, before
+making such an attempt.
+
address@hidden Backup Parameters
address@hidden Setting Parameters for Backups and Restoration
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @command{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+Syntactically, @file{backup-specs} is a shell script, containing
+mainly variable assignments. However, any valid shell construct
+is allowed in this file. Particularly, you may wish to define
+functions within that script (e.g., see @code{RESTORE_BEGIN} below).
+For more information about shell script syntax, please refer to
address@hidden://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02, the definition of the Shell Command Language}. See also
address@hidden,,Bash Features,bashref,Bash Reference Manual}.
+
+The shell variables controlling behavior of @code{backup} and
address@hidden are described in the following subsections.
+
address@hidden
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
address@hidden menu
+
address@hidden General-Purpose Variables
address@hidden General-Purpose Variables
+
address@hidden {Backup variable} ADMINISTRATOR
+The user name of the backup administrator. @code{Backup} scripts
+sends a backup report to this address.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the time specification in form @var{hours}:@var{minutes},
+or the string @samp{now}.
+
+This variable is used by @code{backup}. Its value may be overridden
+using @option{--time} option (@pxref{Scripted Backups}).
address@hidden defvr
+
address@hidden {Backup variable} TAPE_FILE
+
+The device @command{tar} writes the archive to. If @var{TAPE_FILE}
+is a remote archive (@pxref{remote-dev}), backup script will suppose
+that your @command{mt} is able to access remote devices. If @var{RSH}
+(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
+invocations of @command{mt}.
address@hidden defvr
+
address@hidden {Backup variable} BLOCKING
+
+The blocking factor @command{tar} will use when writing the dump archive.
address@hidden Factor}.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_DIRS
+
+A list of file systems to be dumped (for @code{backup}), or restored
+(for @code{restore}). You can include any directory
+name in the list --- subdirectories on that file system will be
+included, regardless of how they may look to other networked machines.
+Subdirectories on other file systems will be ignored.
+
+The host name specifies which host to run @command{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have @acronym{GNU} @command{tar} installed, and
+must be able to access the directory containing the backup scripts and
+their support files using the same file name that is used on the
+machine where the scripts are run (i.e. what @command{pwd} will print
+when in that directory on that machine). If the host that contains
+the file system does not have this capability, you can specify another
+host as long as it can access the file system through NFS.
+
+If the list of file systems is very long you may wish to put it
+in a separate file. This file is usually named
address@hidden/etc/backup/dirs}, but this name may be overridden in
address@hidden using @code{DIRLIST} variable.
address@hidden defvr
+
address@hidden {Backup variable} DIRLIST
+
+A path to the file containing the list of the file systems to backup
+or restore. By default it is @file{/etc/backup/dirs}.
address@hidden defvr
+
address@hidden {Backup variable} BACKUP_FILES
+
+A list of individual files to be dumped (for @code{backup}), or restored
+(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
+in a separate file. This file is usually named
address@hidden/etc/backup/files}, but this name may be overridden in
address@hidden using @code{FILELIST} variable.
address@hidden defvr
+
address@hidden {Backup variable} FILELIST
+
+A path to the file containing the list of the individual files to backup
+or restore. By default it is @file{/etc/backup/files}.
address@hidden defvr
+
address@hidden {Backup variable} MT
+
+Full file name of @command{mt} binary.
address@hidden defvr
+
address@hidden {Backup variable} RSH
address@hidden
+Full file name of @command{rsh} binary or its equivalent. You may wish to
+set it to @code{ssh}, to improve security. In this case you will have
+to use public key authentication.
address@hidden defvr
+
address@hidden {Backup variable} RSH_COMMAND
+
+Full file name of @command{rsh} binary on remote mashines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @acronym{GNU} @command{tar}.
address@hidden defvr
+
address@hidden {Backup variable} VOLNO_FILE
+
+Name of temporary file to hold volume numbers. This needs to be accessible
+by all the machines which have file systems to be dumped.
address@hidden defvr
+
address@hidden {Backup variable} XLIST
+
+Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
+located on the remote machine and containing the list of files to
+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).
+
+This variable affects only @code{backup}.
address@hidden defvr
+
address@hidden {Backup variable} SLEEP_TIME
+
+Time to sleep between dumps of any two successive file systems
+
+This variable affects only @code{backup}.
address@hidden defvr
+
address@hidden {Backup variable} DUMP_REMIND_SCRIPT
+
+Script to be run when it's time to insert a new tape in for the next
+volume. Administrators may want to tailor this script for their site.
+If this variable isn't set, @acronym{GNU} @command{tar} will display its
built-in
+prompt, and will expect confirmation from the console. For the
+description of the default prompt, see @ref{change volume prompt}.
+
address@hidden defvr
+
address@hidden {Backup variable} SLEEP_MESSAGE
+
+Message to display on the terminal while waiting for dump time. Usually
+this will just be some literal text.
address@hidden defvr
+
address@hidden {Backup variable} TAR
+
+Full file name of the @acronym{GNU} @command{tar} executable. If this is not
set, backup
+scripts will search @command{tar} in the current shell path.
address@hidden defvr
+
address@hidden Magnetic Tape Control
address@hidden Magnetic Tape Control
+
+Backup scripts access tape device using special @dfn{hook functions}.
+These functions take a single argument -- the name of the tape
+device. Their names are kept in the following variables:
+
address@hidden {Backup variable} MT_BEGIN
+The name of @dfn{begin} function. This function is called before
+accessing the drive. By default it retensions the tape:
+
address@hidden
+MT_BEGIN=mt_begin
+
+mt_begin() @{
+ mt -f "$1" retension
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden {Backup variable} MT_REWIND
+The name of @dfn{rewind} function. The default definition is as
+follows:
+
address@hidden
+MT_REWIND=mt_rewind
+
+mt_rewind() @{
+ mt -f "$1" rewind
address@hidden
address@hidden smallexample
+
address@hidden defvr
+
address@hidden {Backup variable} MT_OFFLINE
+The name of the function switching the tape off line. By default
+it is defined as follows:
+
address@hidden
+MT_OFFLINE=mt_offline
+
+mt_offline() @{
+ mt -f "$1" offl
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden {Backup variable} MT_STATUS
+The name of the function used to obtain the status of the archive device,
+including error count. Default definition:
+
address@hidden
+MT_STATUS=mt_status
+
+mt_status() @{
+ mt -f "$1" status
address@hidden
address@hidden smallexample
address@hidden defvr
+
address@hidden User Hooks
address@hidden User Hooks
+
address@hidden hooks} are shell functions executed before and after
+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:
+
address@hidden {User Hook Function} hook @var{level} @var{host} @var{fs}
@var{fsname}
+Its arguments are:
+
address@hidden @var
address@hidden level
+Current backup or restore level.
+
address@hidden host
+Name or IP address of the host machine being dumped or restored.
+
address@hidden fs
+Full path name to the file system being dumped or restored.
+
address@hidden fsname
+File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
address@hidden table
address@hidden deffn
+
+Following variables keep the names of user hook functions
+
address@hidden {Backup variable} DUMP_BEGIN
+Dump begin function. It is executed before dumping the file system.
address@hidden defvr
+
address@hidden {Backup variable} DUMP_END
+Executed after dumping the file system.
address@hidden defvr
+
address@hidden {Backup variable} RESTORE_BEGIN
+Executed before restoring the file system.
address@hidden defvr
+
address@hidden {Backup variable} RESTORE_END
+Executed after restoring the file system.
address@hidden defvr
+
address@hidden backup-specs example
address@hidden An Example Text of @file{Backup-specs}
+
+The following is an example of @file{backup-specs}:
+
address@hidden
+# site-specific parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+
+# Use @code{ssh} instead of the less secure @code{rsh}
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
+
+# Override MT_STATUS function:
+my_status() @{
+ mts -t $TAPE_FILE
address@hidden
+MT_STATUS=my_status
+
+# Disable MT_OFFLINE function
+MT_OFFLINE=:
+
+BLOCKING=124
+BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
+
+BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+
address@hidden smallexample
+
address@hidden Scripted Backups
address@hidden Using the Backup Scripts
+
+The syntax for running a backup script is:
+
address@hidden
+backup address@hidden address@hidden
address@hidden smallexample
+
+The @option{level} option requests the dump level. Thus, to produce
+a full dump, specify @code{--level=0} (this is the default, so
address@hidden may be omitted if its value is @code{0}).
address@hidden backward compatibility, the @code{backup} will also
+try to deduce the requested dump level from the name of the
+script itself. If the name consists of a string @samp{level-}
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from @code{backup}
+to @code{level-1} and then run @code{level-1} whenever you need to
+create a level one dump.}
+
+The @option{--time} option determines when should the backup be
+run. @var{Time} may take three forms:
+
address@hidden @asis
address@hidden @var{hh}:@var{mm}
+
+The dump must be run at @var{hh} hours @var{mm} minutes.
+
address@hidden @var{hh}
+
+The dump must be run at @var{hh} hours
+
address@hidden now
+
+The dump must be run immediately.
address@hidden table
+
+You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it
+needs them. Media volumes don't have to correspond to archive
+files --- a multi-volume archive can be started in the middle of a
+tape that already contains the end of another multi-volume archive.
+The @code{restore} script prompts for media by its archive volume,
+so to avoid an error message you should keep track of which tape
+(or disk) contains which volume of the archive (@pxref{Scripted
+Restoration}).
+
+The backup scripts write two files on the file system. The first is a
+record file in @file{/etc/tar-backup/}, which is used by the scripts
+to store and retrieve information about which files were dumped. This
+file is not meant to be read by humans, and should not be deleted by
+them. @xref{Snapshot Files}, for a more detailed explanation of this
+file.
+
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+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
address@hidden@address@hidden, 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.
+
+Following is the full list of options accepted by @code{backup}
+script:
+
address@hidden @option
address@hidden -l @var{level}
address@hidden address@hidden
+Do backup level @var{level} (default 0).
+
address@hidden -f
address@hidden --force
+Force backup even if today's log file already exists.
+
address@hidden address@hidden
address@hidden address@hidden
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
address@hidden -t @var{start-time}
address@hidden address@hidden
+Wait till @var{time}, then do backup.
+
address@hidden -h
address@hidden --help
+Display short help message and exit.
+
address@hidden -V
address@hidden --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden table
+
+
address@hidden Scripted Restoration
address@hidden Using the Restore Script
+
+To restore files that were archived using a scripted backup, use the
address@hidden script. Its usage is quite straightforward. In the
+simplest form, invoke @code{restore --all}, it will
+then restore all the file systems and files specified in
address@hidden (@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
+line. For example, running
+
address@hidden
+restore 'albert:*'
address@hidden smallexample
+
address@hidden
+will restore all file systems on the machine @samp{albert}. A more
+complicated example:
+
address@hidden
+restore 'albert:*' '*:/var'
address@hidden smallexample
+
address@hidden
+This command will restore all file systems on the machine @samp{albert}
+as well as @file{/var} file system on all machines.
+
+By default @code{restore} will start restoring files from the lowest
+available dump level (usually zero) and will continue through
+all available dump levels. There may be situations where such a
+thorough restore is not necessary. For example, you may wish to
+restore only files from the recent level one backup. To do so,
+use @option{--level} option, as shown in the example below:
+
address@hidden
+restore --level=1
address@hidden smallexample
+
+The full list of options accepted by @code{restore} follows:
+
address@hidden @option
address@hidden -a
address@hidden --all
+Restore all file systems and files specified in @file{backup-specs}
+
address@hidden -l @var{level}
address@hidden address@hidden
+Start restoring from the given backup level, instead of the default 0.
+
address@hidden address@hidden
address@hidden address@hidden
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
address@hidden -h
address@hidden --help
+Display short help message and exit.
+
address@hidden -V
address@hidden --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
address@hidden table
+
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @xref{Tape Positioning}, for a discussion of tape
+positioning.
+
address@hidden
address@hidden:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
address@hidden quotation
+
address@hidden Dumps}, for an explanation of how the script makes
+that determination.
+
address@hidden Choosing
address@hidden Choosing Files and Names for @command{tar}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Certain options to @command{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.
+
+This chapter discusses these options in detail.
+
address@hidden
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
address@hidden menu
+
address@hidden file
address@hidden Choosing and Naming Archive Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Naming an archive
address@hidden Archive Name
address@hidden Choosing an archive file
address@hidden Where is the archive?
+By default, @command{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @command{tar}
+on the system may not have set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
address@hidden where to find (or create) the archive. The
address@hidden@var{archive-name}} (@option{-f @var{archive-name}})
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+
address@hidden @option
address@hidden address@hidden, short description}
address@hidden address@hidden
address@hidden -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
address@hidden table
+
+For example, in this @command{tar} command,
+
address@hidden
+$ @kbd{tar -cvf collection.tar blues folk jazz}
address@hidden smallexample
+
address@hidden
address@hidden is the name of the archive. It must directly
+follow the @option{-f} option, since whatever directly follows @option{-f}
address@hidden end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @command{tar} will use this file's name
+for the archive name.
+
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
+
address@hidden Writing new archives
address@hidden Archive creation
+If you do not name the archive, @command{tar} uses the value of the
+environment variable @env{TAPE} as the file name for the archive. If
+that is not available, @command{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (i.e. @file{/dev/tu00}).
+
address@hidden Standard input and output
address@hidden tar to standard input and output
+If you use @file{-} as an @var{archive-name}, @command{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
address@hidden as an @var{archive-name} when modifying an archive,
address@hidden reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+
+The following example is a convenient way of copying directory
+hierarchy from @file{sourcedir} to @file{targetdir}.
+
address@hidden
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
address@hidden smallexample
+
+The @option{-C} option allows to avoid using subshells:
+
address@hidden
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
address@hidden smallexample
+
+In both examples above, the leftmost @command{tar} invocation archives
+the contents of @file{sourcedir} to the standard output, while the
+rightmost one reads this archive from its standard input and
+extracts it. The @option{-p} option tells it to restore permissions
+of the extracted files.
+
address@hidden Remote devices
address@hidden tar to a remote device
address@hidden
+To specify an archive file on a device attached to a remote machine,
+use the following:
+
address@hidden
address@hidden@var{hostname}:/@var{dev}/@var{file-name}}
address@hidden smallexample
+
address@hidden
address@hidden will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
address@hidden@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
+
address@hidden Local and remote archives
address@hidden and remote archives}
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
address@hidden@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @command{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @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
+the @acronym{GNU} @command{tar} distribution and by default is installed under
address@hidden@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 @option{--force-local} option.
+
+When the archive is being created to @file{/dev/null}, @acronym{GNU}
@command{tar}
+tries to minimize input and output operations. The Amanda backup
+system, when used with @acronym{GNU} @command{tar}, has an initial sizing pass
which
+uses this feature.
+
address@hidden Selecting Archive Members
address@hidden Selecting Archive Members
address@hidden Specifying files to act on
address@hidden Specifying archive members
+
address@hidden Name arguments} specify which files in the file system
address@hidden operates on, when creating or adding to an archive, or which
+archive members @command{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
+
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
address@hidden
address@hidden @var{operation} address@hidden @var{option2} @dots{}]
address@hidden name-1} @var{file name-2} @dots{}]
address@hidden smallexample
+
+If a file name begins with dash (@samp{-}), precede it with
address@hidden option to prevent it from being treated as an
+option.
+
address@hidden name quoting}
+By default @acronym{GNU} @command{tar} attempts to @dfn{unquote} each file or
member
+name, replacing @dfn{escape sequences} according to the following
+table:
+
address@hidden @columnfractions 0.20 0.60
address@hidden Escape @tab Replaced with
address@hidden \a @tab Audible bell (ASCII 7)
address@hidden \b @tab Backspace (ASCII 8)
address@hidden \f @tab Form feed (ASCII 12)
address@hidden \n @tab New line (ASCII 10)
address@hidden \r @tab Carriage return (ASCII 13)
address@hidden \t @tab Horizontal tabulation (ASCII 9)
address@hidden \v @tab Vertical tabulation (ASCII 11)
address@hidden \? @tab ASCII 127
address@hidden address@hidden @tab ASCII @var{n} (@var{n} should be an octal
number
+ of up to 3 digits)
address@hidden multitable
+
+A backslash followed by any other symbol is retained.
+
+This default behavior is controlled by the following command line
+option:
+
address@hidden @option
address@hidden unquote
address@hidden --unquote
+Enable unquoting input file or member names (default).
+
address@hidden no-unquote
address@hidden --no-unquote
+Disable unquoting input file or member names.
address@hidden table
+
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @command{tar}.
+
+If you do not specify files, @command{tar} behavior differs depending
+on the operation mode as described below:
+
+When @command{tar} is invoked with @option{--create} (@option{-c}),
address@hidden will stop immediately, reporting the following:
+
address@hidden
address@hidden
+$ @kbd{tar cf a.tar}
+tar: Cowardly refusing to create an empty archive
+Try `tar --help' or `tar --usage' for more information.
address@hidden group
address@hidden smallexample
+
+If you specify either @option{--list} (@option{-t}) or
address@hidden (@option{--get}, @option{-x}), @command{tar}
+operates on all the archive members in the archive.
+
+If run with @option{--diff} option, tar will compare the archive with
+the contents of the current working directory.
+
+If you specify any other operation, @command{tar} does nothing.
+
+By default, @command{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @command{tar} selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
+
address@hidden files
address@hidden Reading Names from a File
+
address@hidden Reading file names from a file
address@hidden Lists of file names
address@hidden File Name arguments, alternatives
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
address@hidden@var{file-of-names}} (@option{-T
address@hidden) option to @command{tar}. Give the name of the
+file which contains the list of files to include as the argument to
address@hidden In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @command{find} utility.
+
address@hidden @option
address@hidden files-from
address@hidden address@hidden
address@hidden -T @var{file-name}
+Get names to extract or create from file @var{file-name}.
address@hidden table
+
+If you give a single dash as a file name for @option{--files-from}, (i.e.,
+you specify either @code{--files-from=-} or @code{-T -}), then the file
+names are read from standard input.
+
+Unless you are running @command{tar} with @option{--create}, you can not use
+both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
+command.
+
+Any number of @option{-T} options can be given in the command line.
+
+The following example shows how to use @command{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @option{-T} option to
address@hidden to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @option{-z} option to
address@hidden compresses the archive with @command{gzip}; @pxref{gzip} for
+more information.)
+
address@hidden
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
address@hidden smallexample
+
address@hidden
+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 address@hidden of @acronym{GNU} @command{tar} up to 1.15.1
+recognized only @option{-C} option in file lists, and only if the
+option and its argument occupied two consecutive lines.} For example,
+the common use of this feature is to change to another directory by
+specifying @option{-C} option:
+
address@hidden
address@hidden
+$ @kbd{cat list}
+-C/etc
+passwd
+hosts
+-C/lib
+libc.a
+$ @kbd{tar -c -f foo.tar --files-from list}
address@hidden group
address@hidden smallexample
+
address@hidden
+In this example, @command{tar} will first switch to @file{/etc}
+directory and add files @file{passwd} and @file{hosts} to the
+archive. Then it will change to @file{/lib} directory and will archive
+the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will
+contain:
+
address@hidden
address@hidden
+$ @kbd{tar tf foo.tar}
+passwd
+hosts
+libc.a
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden address@hidden, using in @option{--files-from} argument}
+Notice that the option parsing algorithm used with @option{-T} is
+stricter than the one used by shell. Namely, when specifying option
+arguments, you should observe the following rules:
+
address@hidden @bullet
address@hidden
+When using short (single-letter) option form, its argument must
+immediately follow the option letter, without any intervening
+whitespace. For example: @code{-Cdir}.
+
address@hidden
+When using long option form, the option argument must be separated
+from the option by a single equal sign. No whitespace is allowed on
+any side of the equal sign. For example: @code{--directory=dir}.
+
address@hidden
+For both short and long option forms, the option argument can be given
+on the next line after the option name, e.g.:
+
address@hidden
address@hidden
+--directory
+dir
address@hidden group
address@hidden smallexample
+
address@hidden
+and
+
address@hidden
address@hidden
+-C
+dir
address@hidden group
address@hidden smallexample
address@hidden itemize
+
address@hidden add-file
+If you happen to have a file whose name starts with @samp{-},
+precede it with @option{--add-file} option to prevent it from
+being recognized as an option. For example: @code{--add-file=--my-file}.
+
address@hidden
+* nul::
address@hidden menu
+
address@hidden nul
address@hidden @code{NUL} Terminated File Names
+
address@hidden File names, terminated by @code{NUL}
address@hidden @code{NUL} terminated file names
+The @option{--null} option causes
address@hidden@var{file-of-names}} (@option{-T @var{file-of-names}})
+to read file names terminated by a @code{NUL} instead of a newline, so
+files whose names contain newlines can be archived using
address@hidden
+
address@hidden @option
address@hidden null
address@hidden --null
+Only consider @code{NUL} terminated file names, instead of files that
+terminate in a newline.
address@hidden table
+
+The @option{--null} option is just like the one in @acronym{GNU}
address@hidden and @command{cpio}, and is useful with the
address@hidden predicate of @acronym{GNU} @command{find}. In
address@hidden, @option{--null} also disables special handling for
+file names that begin with dash.
+
+This example shows how to use @command{find} to generate a list of files
+larger than 800K in length and put that list into a file called
address@hidden 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
address@hidden and @option{-T} options to specify that @command{tar} get the
+files from that file, @file{long-files}, to create the archive
address@hidden The @option{--null} option to @command{tar} will cause
address@hidden to recognize the @code{NUL} separator between files.
+
address@hidden
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
address@hidden smallexample
+
address@hidden
address@hidden
+
+
address@hidden exclude
address@hidden Excluding Some Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden File names, excluding files by
address@hidden Excluding files by name and pattern
address@hidden Excluding files by file system
+To avoid operating on files whose names match a particular pattern,
+use the @option{--exclude} or @option{--exclude-from} options.
+
address@hidden @option
address@hidden exclude
address@hidden address@hidden
+Causes @command{tar} to ignore files that match the @var{pattern}.
address@hidden table
+
address@hidden exclude
+The @address@hidden option prevents any file or
+member whose name matches the shell wildcard (@var{pattern}) from
+being operated on.
+For example, to create an archive with all the contents of the directory
address@hidden except for files whose names end in @file{.o}, use the
+command @samp{tar -cf src.tar --exclude='*.o' src}.
+
+You may give multiple @option{--exclude} options.
+
address@hidden @option
address@hidden exclude-from
address@hidden address@hidden
address@hidden -X @var{file}
+Causes @command{tar} to ignore files that match the patterns listed in
address@hidden
address@hidden table
+
address@hidden exclude-from
+Use the @option{--exclude-from} option to read a
+list of patterns, one per line, from @var{file}; @command{tar} will
+ignore files matching those patterns. Thus if @command{tar} is
+called as @address@hidden -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
+
address@hidden @option
address@hidden exclude-caches
address@hidden --exclude-caches
+Causes @command{tar} to ignore directories containing a cache directory tag.
address@hidden table
+
address@hidden exclude-caches
+When creating an archive, the @option{--exclude-caches} option causes
address@hidden to exclude all directories that contain a @dfn{cache
+directory tag}. A cache directory tag is a short file with the
+well-known name @file{CACHEDIR.TAG} and having a standard header
+specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
+Various applications write cache directory tags into directories they
+use to hold regenerable, non-precious data, so that such data can be
+more easily excluded from backups.
+
address@hidden
+* problems with exclude::
address@hidden menu
+
address@hidden problems with exclude
address@hidden Problems with Using the @code{exclude} Options
+
address@hidden address@hidden, potential problems with}
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
+
address@hidden @bullet
address@hidden
+The main operating mode of @command{tar} does not act on a path name
+explicitly listed on the command line if one of its file name
+components is excluded. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{dir.o/foo} after all the options have been
+listed, @samp{dir.o/foo} will be excluded from the archive.
+
address@hidden
+You can sometimes confuse the meanings of @option{--exclude} and
address@hidden Be careful: use @option{--exclude} when files
+to be excluded are given as a pattern on the command line. Use
address@hidden to introduce the name of a file which contains
+a list of patterns, one per line; each of these patterns can exclude
+zero, one, or many files.
+
address@hidden
+When you use @address@hidden, be sure to quote the
address@hidden parameter, so @acronym{GNU} @command{tar} sees wildcard
characters
+like @samp{*}. If you do not do this, the shell might expand the
address@hidden itself using files at hand, so @command{tar} might receive a
+list of files instead of one pattern, or none at all, making the
+command somewhat illegal. This might not correspond to what you want.
+
+For example, write:
+
address@hidden
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
address@hidden smallexample
+
address@hidden
+rather than:
+
address@hidden
+# @emph{Wrong!}
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
address@hidden smallexample
+
address@hidden
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @command{tar}. If you try to use
address@hidden syntax to describe files to be excluded, your command
+might fail.
+
address@hidden
address@hidden
address@hidden
+
+In earlier versions of @command{tar}, what is now the
address@hidden option was called @option{--exclude} instead.
+Now, @option{--exclude} applies to patterns listed on the command
+line and @option{--exclude-from} applies to patterns listed in a
+file.
+
address@hidden itemize
+
address@hidden wildcards
address@hidden Wildcards Patterns and Matching
+
address@hidden is the operation by which @dfn{wildcard} characters,
address@hidden or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. @acronym{GNU} @command{tar} can
use wildcard
+patterns for matching (or globbing) archive members when extracting
+from or listing an archive. Wildcard patterns are also used for
+verifying volume labels of @command{tar} archives. This section has the
+purpose of explaining wildcard syntax for @command{tar}.
+
address@hidden
address@hidden
+
+
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
address@hidden in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
address@hidden would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
address@hidden would match any of the characters, @samp{-}, @samp{\},
address@hidden, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
address@hidden in a character class.)
+
address@hidden Excluding characters from a character class
address@hidden Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
+
+Other characters of the class stand for themselves. The special
+construction @address@hidden@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
address@hidden, inclusive.
+
address@hidden
address@hidden
+
+
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: thus, excluding a directory also excludes all the files beneath it.
+
address@hidden
+* controlling pattern-matching::
address@hidden menu
+
address@hidden controlling pattern-matching
address@hidden Controlling Pattern-Matching
+
+For the purposes of this section, we call @dfn{exclusion members} all
+member names obtained while processing @option{--exclude} and
address@hidden options, and @dfn{inclusion members} those
+member names that were given in the command line or read from the file
+specified with @option{--files-from} option.
+
+These two pairs of member lists are used in the following operations:
address@hidden, @option{--extract}, @option{--list},
address@hidden
+
+There are no inclusion members in create mode (@option{--create} and
address@hidden), since in this mode the names obtained from the
+command line refer to @emph{files}, not archive members.
+
+By default, inclusion members are compared with archive members
+literally @footnote{Notice that earlier @acronym{GNU} @command{tar} versions
used
+globbing for inclusion members, which contradicted to UNIX98
+specification and was not documented. @xref{Changes}, for more
+information on this and other changes.} and exclusion members are
+treated as globbing patterns. For example:
+
address@hidden
address@hidden
+$ @kbd{tar tf foo.tar}
+a.c
+b.c
+a.txt
+[remarks]
+# @i{Member names are used verbatim:}
+$ @kbd{tar -xf foo.tar -v '[remarks]'}
+[remarks]
+# @i{Exclude member names are globbed:}
+$ @kbd{tar -xf foo.tar -v --exclude '*.c'}
+a.txt
+[remarks]
address@hidden group
address@hidden smallexample
+
+This behavior can be altered by using the following options:
+
address@hidden @option
address@hidden wildcards
address@hidden --wildcards
+Treat all member names as wildcards.
+
address@hidden no-wildcards
address@hidden --no-wildcards
+Treat all member names as literal strings.
address@hidden table
+
+Thus, to extract files whose names end in @samp{.c}, you can use:
+
address@hidden
+$ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
+a.c
+b.c
address@hidden smallexample
+
address@hidden
+Notice quoting of the pattern to prevent the shell from interpreting
+it.
+
+The effect of @option{--wildcards} option is cancelled by
address@hidden This can be used to pass part of
+the command line arguments verbatim and other part as globbing
+patterns. For example, the following invocation:
+
address@hidden
+$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
address@hidden smallexample
+
address@hidden
+instructs @command{tar} to extract from @file{foo.tar} all files whose
+names end in @samp{.txt} and the file named @file{[remarks]}.
+
+Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where @samp{*}, @samp{?}, and
address@hidden are the usual shell wildcards, @samp{\} escapes wildcards,
+and wildcards can match @samp{/}.
+
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and names are used as-is. For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
+
+However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+
address@hidden
+--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
address@hidden smallexample
+
address@hidden
+ignores case when excluding @samp{makefile}, but not when excluding
address@hidden
+
address@hidden @option
address@hidden anchored
address@hidden no-anchored
address@hidden --anchored
address@hidden --no-anchored
+If anchored, a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any
+subsequence. Default is @option{--no-anchored} for exclusion members
+and @option{--anchored} inclusion members.
+
address@hidden ignore-case
address@hidden no-ignore-case
address@hidden --ignore-case
address@hidden --no-ignore-case
+When ignoring case, upper-case patterns match lower-case names and vice versa.
+When not ignoring case (the default), matching is case-sensitive.
+
address@hidden wildcards-match-slash
address@hidden no-wildcards-match-slash
address@hidden --wildcards-match-slash
address@hidden --no-wildcards-match-slash
+When wildcards match slash (the default for exclusion members), a
+wildcard like @samp{*} in the pattern can match a @samp{/} in the
+name. Otherwise, @samp{/} is matched only by @samp{/}.
+
address@hidden table
+
+The @option{--recursion} and @option{--no-recursion} options
+(@pxref{recurse}) also affect how member patterns are interpreted. If
+recursion is in effect, a pattern matches a name if it matches any of
+the name's parent directories.
+
+The following table summarizes pattern-matching default values:
+
address@hidden @columnfractions .3 .7
address@hidden Members @tab Default settings
address@hidden Inclusion @tab @option{--no-wildcards --anchored
--no-wildcards-match-slash}
address@hidden Exclusion @tab @option{--wildcards --no-anchored
--wildcards-match-slash}
address@hidden multitable
+
address@hidden quoting styles
address@hidden Quoting Member Names
+
+When displaying member names, @command{tar} takes care to avoid
+ambiguities caused by certain characters. This is called @dfn{name
+quoting}. The characters in question are:
+
address@hidden @bullet
address@hidden Non-printable control characters:
+
address@hidden @columnfractions 0.20 0.10 0.60
address@hidden Character @tab ASCII @tab Character name
address@hidden \a @tab 7 @tab Audible bell
address@hidden \b @tab 8 @tab Backspace
address@hidden \f @tab 12 @tab Form feed
address@hidden \n @tab 10 @tab New line
address@hidden \r @tab 13 @tab Carriage return
address@hidden \t @tab 9 @tab Horizontal tabulation
address@hidden \v @tab 11 @tab Vertical tabulation
address@hidden multitable
+
address@hidden Space (ASCII 32)
+
address@hidden Single and double quotes (@samp{'} and @samp{"})
+
address@hidden Backslash (@samp{\})
address@hidden itemize
+
+The exact way @command{tar} uses to quote these characters depends on
+the @dfn{quoting style}. The default quoting style, called
address@hidden (see below), uses backslash notation to represent control
+characters, space and backslash. Using this quoting style, control
+characters are represented as listed in column @samp{Character} in the
+above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
+
address@hidden @command{tar} offers seven distinct quoting styles, which can be
selected
+using @option{--quoting-style} option:
+
address@hidden @option
address@hidden address@hidden
address@hidden quoting-style
+
+Sets quoting style. Valid values for @var{style} argument are:
+literal, shell, shell-always, c, escape, locale, clocale.
address@hidden table
+
+These styles are described in detail below. To illustrate their
+effect, we will use an imaginary tar archive @file{arch.tar}
+containing the following members:
+
address@hidden
address@hidden
+# 1. Contains horizontal tabulation character.
+a tab
+# 2. Contains newline character
+a
+newline
+# 3. Contains a space
+a space
+# 4. Contains double quotes
+a"double"quote
+# 5. Contains single quotes
+a'single'quote
+# 6. Contains a backslash character:
+a\backslash
address@hidden group
address@hidden smallexample
+
+Here is how usual @command{ls} command would have listed them, if they
+had existed in the current working directory:
+
address@hidden
address@hidden
+$ @kbd{ls}
+a\ttab
+a\nnewline
+a\ space
+a"double"quote
+a'single'quote
+a\\backslash
address@hidden group
address@hidden smallexample
+
+Quoting styles:
+
address@hidden @samp
address@hidden literal
+No quoting, display each character as is:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=literal}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\backslash
+./a tab
+./a
+newline
address@hidden group
address@hidden smallexample
+
address@hidden shell
+Display characters the same way Bourne shell does:
+control characters, except @samp{\t} and @samp{\n}, are printed using
+backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
+single quote is printed as @samp{\'}. If a name contains any quoted
+characters, it is enclosed in single quotes. In particular, if a name
+contains single quotes, it is printed as several single-quoted strings:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=shell}
+./
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
address@hidden group
address@hidden smallexample
+
address@hidden shell-always
+Same as @samp{shell}, but the names are always enclosed in single
+quotes:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=shell-always}
+'./'
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
address@hidden group
address@hidden smallexample
+
address@hidden c
+Use the notation of the C programming language. All names are
+enclosed in double quotes. Control characters are quoted using
+backslash notations, double quotes are represented as @samp{\"},
+backslash characters are represented as @samp{\\}. Single quotes and
+spaces are not quoted:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=c}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
address@hidden group
address@hidden smallexample
+
address@hidden escape
+Control characters are printed using backslash notation, a space is
+printed as @samp{\ } and a backslash as @samp{\\}. This is the
+default quoting style, unless it was changed when configured the
+package.
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=escape}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
address@hidden group
address@hidden smallexample
+
address@hidden locale
+Control characters, single quote and backslash are printed using
+backslash notation. All names are quoted using left and right
+quotation marks, appropriate to the current locale. If it does not
+define quotation marks, use @samp{`} as left and @samp{'} as right
+quotation marks. Any occurrences of the right quotation mark in a
+name are escaped with @samp{\}, for example:
+
+For example:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=locale}
+`./'
+`./a space'
+`./a\'single\'quote'
+`./a"double"quote'
+`./a\\backslash'
+`./a\ttab'
+`./a\nnewline'
address@hidden group
address@hidden smallexample
+
address@hidden clocale
+Same as @samp{locale}, but @samp{"} is used for both left and right
+quotation marks, if not provided by the currently selected locale:
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=clocale}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
address@hidden group
address@hidden smallexample
address@hidden table
+
+You can specify which characters should be quoted in addition to those
+implied by the current quoting style:
+
address@hidden @option
address@hidden address@hidden
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them.
address@hidden table
+
+For example, using @samp{escape} quoting (compare with the usual
+escape listing above):
+
address@hidden
address@hidden
+$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
+./
+./a\ space
+./a'single'quote
+./a\"double\"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
address@hidden group
address@hidden smallexample
+
+To disable quoting of such additional characters, use the following
+option:
+
address@hidden @option
address@hidden address@hidden
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option.
address@hidden table
+
+This option is particularly useful if you have added
address@hidden to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
+and wish to disable it for the current invocation.
+
+Note, that @option{--no-quote-chars} does @emph{not} disable those
+characters that are quoted by default in the selected quoting style.
+
address@hidden transform
address@hidden Modifying File and Member Names
+
address@hidden archives contain detailed information about files stored
+in them and full file names are part of that information. When
+storing file to an archive, its file name is recorded in the archive
+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
+of a file archiver. However, there are some cases when it is not.
+
+First of all, it is often unsafe to extract archive members with
+absolute file names or those that begin with a @file{../}. @acronym{GNU}
@command{tar}
+takes special precautions when extracting such names and provides a
+special option for handling them, which is described in
address@hidden
+
+Secondly, you may wish to extract file names without some leading
+directory components, or with otherwise modified names. In other
+cases it is desirable to store files under differing names in the
+archive.
+
address@hidden @command{tar} provides two options for these needs.
+
address@hidden @option
address@hidden strip-components
address@hidden address@hidden
+Strip given @var{number} of leading components from file names before
+extraction.
address@hidden table
+
+For example, suppose you have archived whole @file{/usr} hierarchy to
+a tar archive named @file{usr.tar}. Among other files, this archive
+contains @file{usr/include/stdlib.h}, which you wish to extract to
+the current working directory. To do so, you type:
+
address@hidden
+$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h}
address@hidden smallexample
+
+The option @option{--strip=2} instructs @command{tar} to strip the
+two leading components (@file{usr/} and @file{include/}) off the file
+name.
+
+If you add to the above invocation @option{--verbose} (@option{-v})
+option, you will note that the verbose listing still contains the
+full file name, with the two removed components still in place. This
+can be inconvenient, so @command{tar} provides a special option for
+altering this behavior:
+
address@hidden
address@hidden @option
address@hidden show-transformed-names
address@hidden --show-transformed-names
+Display file or member names with all requested transformations
+applied.
address@hidden table
+
address@hidden
+For example:
+
address@hidden
address@hidden
+$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h}
+usr/include/stdlib.h
+$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h}
+stdlib.h
address@hidden group
address@hidden smallexample
+
+Notice that in both cases the file is @file{stdlib.h} extracted to the
+current working directory, @option{--show-transformed-names} affects
+only the way its name is displayed.
+
+This option is especially useful for verifying whether the invocation
+will have the desired effect. Thus, before running
+
address@hidden
+$ @kbd{tar -x address@hidden
address@hidden smallexample
+
address@hidden
+it is often advisable to run
+
address@hidden
+$ @kbd{tar -t -v --show-transformed address@hidden
address@hidden smallexample
+
address@hidden
+to make sure the command will produce the intended results.
+
+In case you need to apply more complex modifications to the file name,
address@hidden @command{tar} provides a general-purpose transformation option:
+
address@hidden @option
address@hidden transform
address@hidden address@hidden
+Modify file names using supplied @var{expression}.
address@hidden table
+
address@hidden
+The @var{expression} is a @command{sed}-like replace expression of the
+form:
+
address@hidden
+s/@var{regexp}/@var{replace}/address@hidden
address@hidden smallexample
+
address@hidden
+where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
+replacement for each file name part that matches @var{regexp}. Both
address@hidden and @var{replace} are described in detail in
address@hidden "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
+
+Supported @var{flags} are:
+
address@hidden @samp
address@hidden g
+Apply the replacement to @emph{all} matches to the @var{regexp}, not
+just the first.
+
address@hidden i
+Use case-insensitive matching
+
address@hidden x
address@hidden is an @dfn{extended regular expression} (@pxref{Extended
+regexps, Extended regular expressions, Extended regular expressions,
+sed, GNU sed}).
+
address@hidden @var{number}
+Only replace the @var{number}th match of the @var{regexp}.
+
+Note: the @var{posix} standard does not specify what should happen
+when you mix the @samp{g} and @var{number} modifiers. @acronym{GNU}
@command{tar}
+follows the GNU @command{sed} implementation in this regard, so
+the the interaction is defined to be: ignore matches before the
address@hidden, and then match and replace all matches from the
address@hidden on.
+
address@hidden table
+
+Any delimiter can be used in lieue of @samp{/}, the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+
address@hidden
address@hidden
+s/one/two/
+s,one,two,
address@hidden group
address@hidden smallexample
+
+Changing delimiters is often useful when the @var{regex} contains
+slashes. For example, it is more convenient to write @code{s,/,-,} than
address@hidden/\//-/}.
+
+Here are several examples of @option{--transform} usage:
+
address@hidden
address@hidden Extract @file{usr/} hierarchy into @file{usr/local/}:
+
address@hidden
+$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Strip two leading directory components (equivalent to
address@hidden):
+
address@hidden
+$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Prepend @file{/prefix/} to each file name:
+
address@hidden
+$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
address@hidden smallexample
+
address@hidden Convert each file name to lower case:
+
address@hidden
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
address@hidden smallexample
+
address@hidden enumerate
+
+Unlike @option{--strip-components}, @option{--transform} can be used
+in any @acronym{GNU} @command{tar} operation mode. For example, the following
command
+adds files to the archive while replacing the leading @file{usr/}
+component with @file{var/}:
+
address@hidden
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /}
address@hidden smallexample
+
+To test @option{--transform} effect we suggest using
address@hidden option:
+
address@hidden
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
+ --verbose --show-transformed-names /}
address@hidden smallexample
+
+If both @option{--strip-components} and @option{--transform} are used
+together, then @option{--transform} is applied first, and the required
+number of components is then stripped from its result.
+
address@hidden after
address@hidden Operating Only on New Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden Excluding file by age
address@hidden Data Modification time, excluding files by
address@hidden Modification time, excluding files by
address@hidden Age, excluding files by
+The @address@hidden (@address@hidden,
address@hidden @var{date}}) option causes @command{tar} to only work on
+files whose data modification or status change times are newer than
+the @var{date} given. If @var{date} starts with @samp{/} or @samp{.},
+it is taken to be a file name; the data modification time of that file
+is used as the date. If you use this option when creating or appending
+to an archive, the archive will only include new files. If you use
address@hidden when extracting an archive, @command{tar} will
+only extract files newer than the @var{date} you specify.
+
+If you only want @command{tar} to make the date comparison based on
+modification of the file's data (rather than status
+changes), then use the @address@hidden option.
+
+You may use these options with any operation. Note that these options
+differ from the @option{--update} (@option{-u}) operation in that they
+allow you to specify a particular date against which @command{tar} can
+compare when deciding whether or not to archive the files.
+
address@hidden @option
address@hidden after-date
address@hidden newer
address@hidden address@hidden
address@hidden address@hidden
address@hidden -N @var{date}
+Only store files newer than @var{date}.
+
+Acts on files only if their data modification or status change times are
+later than @var{date}. Use in conjunction with any operation.
+
+If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
+name; the data modification time of that file is used as the date.
+
address@hidden newer-mtime
address@hidden address@hidden
+Acts like @option{--after-date}, but only looks at data modification times.
address@hidden table
+
+These options limit @command{tar} to operate only on files which have
+been modified after the date specified. A file's status is considered to have
+changed if its contents have been modified, or if its owner,
+permissions, and so forth, have been changed. (For more information on
+how to specify a date, see @ref{Date input formats}; remember that the
+entire date argument must be quoted if it contains any spaces.)
+
+Gurus would say that @option{--after-date} tests both the data
+modification time (@code{mtime}, the time the contents of the file
+were last modified) and the status change time (@code{ctime}, the time
+the file's status was last changed: owner, permissions, etc.@:)
+fields, while @option{--newer-mtime} tests only the @code{mtime}
+field.
+
+To be precise, @option{--after-date} checks @emph{both} @code{mtime} and
address@hidden and processes the file if either one is more recent than
address@hidden, while @option{--newer-mtime} only checks @code{mtime} and
+disregards @code{ctime}. Neither does it use @code{atime} (the last time the
+contents of the file were looked at).
+
+Date specifiers can have embedded spaces. Because of this, you may need
+to quote date arguments to keep the shell from parsing them as separate
+arguments. For example, the following command will add to the archive
+all the files modified less than two days ago:
+
address@hidden
+$ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
address@hidden smallexample
+
+When any of these options is used with the option @option{--verbose}
+(@pxref{verbose tutorial}) @acronym{GNU} @command{tar} will try to convert the
specified
+date back to its textual representation and compare that with the
+one given with the option. If the two dates differ, @command{tar} will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date. For example:
+
address@hidden
address@hidden
+$ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
+tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
+13:19:37.232434
address@hidden group
address@hidden smallexample
+
address@hidden
address@hidden Note:} @option{--after-date} and @option{--newer-mtime}
+should not be used for incremental backups. @xref{Incremental Dumps},
+for proper way of creating incremental backups.
address@hidden quotation
+
address@hidden recurse
address@hidden Descending into Directories
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
address@hidden Avoiding recursion in directories
address@hidden Descending directories, avoiding
address@hidden Directories, avoiding recursion
address@hidden Recursion in directories, avoiding
+
address@hidden
address@hidden
+
+
+Usually, @command{tar} will recursively explore all directories (either
+those given on the command line or through the @option{--files-from}
+option) for the various files they contain. However, you may not always
+want @command{tar} to act this way.
+
address@hidden no-recursion
+The @option{--no-recursion} option inhibits @command{tar}'s recursive descent
+into specified directories. If you specify @option{--no-recursion}, you can
+use the @command{find} utility for hunting through levels of directories to
+construct a list of file names which you could then pass to @command{tar}.
address@hidden allows you to be more selective when choosing which files to
+archive; see @ref{files}, for more information on using @command{find} with
address@hidden, or look.
+
address@hidden @option
address@hidden --no-recursion
+Prevents @command{tar} from recursively descending directories.
+
address@hidden recursion
address@hidden --recursion
+Requires @command{tar} to recursively descend directories.
+This is the default.
address@hidden table
+
+When you use @option{--no-recursion}, @acronym{GNU} @command{tar} grabs
+directory entries themselves, but does not descend on them
+recursively. Many people use @command{find} for locating files they
+want to back up, and since @command{tar} @emph{usually} recursively
+descends on directories, they have to use the @address@hidden -type d}}
+test in their @command{find} invocation (@pxref{Type, Type, Type test,
+find, Finding Files}), as they usually do not want all the files in a
+directory. They then use the @option{--files-from} option to archive
+the files located via @command{find}.
+
+The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
address@hidden (@option{--preserve-permissions},
address@hidden) option does not affect them---while users might really
+like it to. Specifying @option{--no-recursion} is a way to tell
address@hidden to grab only the directory entries given to it, adding
+no new files on its own. To summarize, if you use @command{find} to
+create a list of files to be stored in an archive, use it as follows:
+
address@hidden
address@hidden
+$ @kbd{find @var{dir} @var{tests} | \
+ tar -cf @var{archive} -T - --no-recursion}
address@hidden group
address@hidden smallexample
+
+The @option{--no-recursion} option also applies when extracting: it
+causes @command{tar} to extract only the matched directory entries, not
+the files under those directories.
+
+The @option{--no-recursion} option also affects how globbing patterns
+are interpreted (@pxref{controlling pattern-matching}).
+
+The @option{--no-recursion} and @option{--recursion} options apply to
+later options and operands, and can be overridden by later occurrences
+of @option{--no-recursion} and @option{--recursion}. For example:
+
address@hidden
+$ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord}
address@hidden smallexample
+
address@hidden
+creates an archive with one entry for @file{grape}, and the recursive
+contents of @file{grape/concord}, but no entries under @file{grape}
+other than @file{grape/concord}.
+
address@hidden one
address@hidden Crossing File System Boundaries
address@hidden File system boundaries, not crossing
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden will normally automatically cross file system boundaries in
+order to archive files which are part of a directory tree. You can
+change this behavior by running @command{tar} and specifying
address@hidden This option only affects files that are
+archived because they are in a directory that is being archived;
address@hidden will still archive files explicitly named on the command line
+or through @option{--files-from}, regardless of where they reside.
+
address@hidden @option
address@hidden one-file-system
address@hidden --one-file-system
+Prevents @command{tar} from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
address@hidden table
+
+The @option{--one-file-system} option causes @command{tar} to modify its
+normal behavior in archiving the contents of directories. If a file in
+a directory is not on the same file system as the directory itself, then
address@hidden will not archive that file. If the file is a directory
+itself, @command{tar} will not archive anything beneath it; in other words,
address@hidden will not cross mount points.
+
+This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
address@hidden (@option{-v}), files that are excluded are
+mentioned by name on the standard error.
+
address@hidden
+* directory:: Changing Directory
+* absolute:: Absolute File Names
address@hidden menu
+
address@hidden directory
address@hidden Changing the Working Directory
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
address@hidden Changing directory mid-stream
address@hidden Directory, changing mid-stream
address@hidden Working directory, specifying
+To change the working directory in the middle of a list of file names,
+either on the command line or in a file specified using
address@hidden (@option{-T}), use @option{--directory} (@option{-C}).
+This will change the working directory to the specified directory
+after that point in the list.
+
address@hidden @option
address@hidden directory
address@hidden address@hidden
address@hidden -C @var{directory}
+Changes the working directory in the middle of a command line.
address@hidden table
+
+For example,
+
address@hidden
+$ @kbd{tar -c -f jams.tar grape prune -C food cherry}
address@hidden smallexample
+
address@hidden
+will place the files @file{grape} and @file{prune} from the current
+directory into the archive @file{jams.tar}, followed by the file
address@hidden from the directory @file{food}. This option is especially
+useful when you have several widely separated files that you want to
+store in the same archive.
+
+Note that the file @file{cherry} is recorded in the archive under the
+precise name @file{cherry}, @emph{not} @file{food/cherry}. Thus, the
+archive will contain three files that all appear to have come from the
+same directory; if the archive is extracted with plain @samp{tar
+--extract}, all three files will be written in the current directory.
+
+Contrast this with the command,
+
address@hidden
+$ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
address@hidden smallexample
+
address@hidden
+which records the third file in the archive under the name
address@hidden/cherry} so that, if the archive is extracted using
address@hidden --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.
+The following command places the files @file{/etc/passwd},
address@hidden/etc/hosts}, and @file{/lib/libc.a} into the archive
address@hidden:
+
address@hidden
+$ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
address@hidden smallexample
+
address@hidden
+However, the names of the archive members will be exactly what they were
+on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
+They will not appear to be related by file name to the original
+directories where those files were located.
+
+Note that @option{--directory} options are interpreted consecutively. If
address@hidden specifies a relative file name, it is interpreted
+relative to the then current directory, which might not be the same as
+the original current working directory of @command{tar}, due to a previous
address@hidden option.
+
+When using @option{--files-from} (@pxref{files}), you can put various
address@hidden options (including @option{-C}) in the file list. Notice,
+however, that in this case the option and its argument may not be
+separated by whitespace. If you use short option, its argument must
+either follow the option letter immediately, without any intervening
+whitespace, or occupy the next line. Otherwise, if you use long
+option, separate its argument by an equal sign.
+
+For instance, the file list for the above example will be:
+
address@hidden
address@hidden
+-C
+/etc
+passwd
+hosts
+-C
+/lib
+libc.a
address@hidden group
address@hidden smallexample
+
address@hidden
+To use it, you would invoke @command{tar} as follows:
+
address@hidden
+$ @kbd{tar -c -f foo.tar --files-from list}
address@hidden smallexample
+
+Notice also that you can only use the short option variant in the file
+list, i.e., always use @option{-C}, not @option{--directory}.
+
+The interpretation of @option{--directory} is disabled by
address@hidden option.
+
address@hidden absolute
address@hidden Absolute File Names
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @option
address@hidden absolute-names
address@hidden --absolute-names
address@hidden -P
+Do not strip leading slashes from file names, and permit file names
+containing a @file{..} file name component.
address@hidden table
+
+By default, @acronym{GNU} @command{tar} drops a leading @samp{/} on
+input or output, and complains about file names containing a @file{..}
+component. This option turns off this behavior.
+
+When @command{tar} extracts archive members from an archive, it strips any
+leading slashes (@samp{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+allows you to have such members extracted wherever you want, instead of
+being restricted to extracting the member in the exact directory named
+in the archive. For example, if the archive member has the name
address@hidden/etc/passwd}, @command{tar} will extract it as if the name were
+really @file{etc/passwd}.
+
+File names containing @file{..} can cause problems when extracting, so
address@hidden normally warns you about such files when creating an
+archive, and rejects attempts to extracts such files.
+
+Other @command{tar} programs do not do this. As a result, if you
+create an archive whose member names start with a slash, they will be
+difficult for other people with a address@hidden @command{tar}
+program to use. Therefore, @acronym{GNU} @command{tar} also strips
+leading slashes from member names when putting members into the
+archive. For example, if you ask @command{tar} to add the file
address@hidden/bin/ls} to an archive, it will do so, but the member name will
+be @file{bin/address@hidden side effect of this is that when
address@hidden is used with @option{--verbose} the resulting output
+is not, generally speaking, the same as the one you'd get running
address@hidden --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.}
+
+If you use the @option{--absolute-names} (@option{-P}) option,
address@hidden will do none of these transformations.
+
+To archive or extract files relative to the root directory, specify
+the @option{--absolute-names} (@option{-P}) option.
+
+Normally, @command{tar} acts on files relative to the working
+directory---ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+
+When you specify @option{--absolute-names} (@option{-P}),
address@hidden stores file names including all superior directory
+names, and preserves leading slashes. If you only invoked
address@hidden from the root directory you would never need the
address@hidden option, but using this option
+may be more convenient than switching to root.
+
address@hidden
address@hidden
+
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden --absolute-names
+Preserves full file names (including superior directory names) when
+archiving files. Preserves leading slash when extracting files.
+
address@hidden table
+
address@hidden
address@hidden
+
+
address@hidden prints out a message about removing the @samp{/} from
+file names. This message appears once per @acronym{GNU} @command{tar}
+invocation. It represents something which ought to be told; ignoring
+what it means can cause very serious surprises, later.
+
+Some people, nevertheless, do not want to see this message. Wanting to
+play really dangerously, one may of course redirect @command{tar} standard
+error to the sink. For example, under @command{sh}:
+
address@hidden
+$ @kbd{tar -c -f archive.tar /home 2> /dev/null}
address@hidden smallexample
+
address@hidden
+Another solution, both nicer and simpler, would be to change to
+the @file{/} directory first, and then avoid absolute notation.
+For example:
+
address@hidden
+$ @kbd{(cd / && tar -c -f archive.tar home)}
+# @i{or}:
+$ @kbd{tar -c -f archive.tar -C / home}
address@hidden smallexample
+
address@hidden GNU date syntax documentation
+
address@hidden Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
2002,
address@hidden 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+
address@hidden Permission is granted to copy, distribute and/or modify this
document
address@hidden under the terms of the GNU Free Documentation License, Version
1.1 or
address@hidden any later version published by the Free Software Foundation;
with no
address@hidden Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover
address@hidden Texts. A copy of the license is included in the ``GNU Free
address@hidden Documentation License'' file as part of this distribution.
+
address@hidden Date input formats
address@hidden Date input formats
+
address@hidden date input formats
address@hidden get_date
+
+First, a quote:
+
address@hidden
+Our units of temporal measurement, from seconds on up to months, are so
+complicated, asymmetrical and disjunctive so as to make coherent mental
+reckoning in time all but impossible. Indeed, had some tyrannical god
+contrived to enslave our minds to time, to make it all but impossible
+for us to escape subjection to sodden routines and unpleasant surprises,
+he could hardly have done better than handing down our present system.
+It is like a set of trapezoidal building blocks, with no vertical or
+horizontal surfaces, like a language in which the simplest thought
+demands ornate constructions, useless particles and lengthy
+circumlocutions. Unlike the more successful patterns of language and
+science, which enable us to face experience boldly or at least
+level-headedly, our system of temporal calculation silently and
+persistently encourages our terror of time.
+
address@hidden It is as though architects had to measure length in feet, width
+in meters and height in ells; as though basic instruction manuals
+demanded a knowledge of five different languages. It is no wonder then
+that we often look into our own immediate past or future, last Tuesday
+or a week from Sunday, with feelings of helpless confusion. @dots{}
+
+--- Robert Grudin, @cite{Time and the Art of Living}.
address@hidden quotation
+
+This section describes the textual date representations that @sc{gnu}
+programs accept. These are the strings you, as a user, can supply as
+arguments to the various programs. The C interface (via the
address@hidden function) is not described here.
+
address@hidden
+* General date syntax:: Common rules.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
address@hidden menu
+
+
address@hidden General date syntax
address@hidden General date syntax
+
address@hidden general date syntax
+
address@hidden items in date strings
+A @dfn{date} is a string, possibly empty, containing many items
+separated by whitespace. The whitespace may be omitted when no
+ambiguity arises. The empty string means the beginning of today (i.e.,
+midnight). Order of the items is immaterial. A date string may contain
+many flavors of items:
+
address@hidden @bullet
address@hidden calendar date items
address@hidden time of day items
address@hidden time zone items
address@hidden day of the week items
address@hidden relative items
address@hidden pure numbers.
address@hidden itemize
+
address@hidden We describe each of these item types in turn, below.
+
address@hidden numbers, written-out
address@hidden ordinal numbers
address@hidden first @r{in date strings}
address@hidden next @r{in date strings}
address@hidden last @r{in date strings}
+A few ordinal numbers may be written out in words in some contexts. This is
+most useful for specifying day of the week items or relative items (see
+below). Among the most commonly used ordinal numbers, the word
address@hidden stands for @math{-1}, @samp{this} stands for 0, and
address@hidden and @samp{next} both stand for 1. Because the word
address@hidden stands for the unit of time there is no way to write the
+ordinal number 2, but for convenience @samp{third} stands for 3,
address@hidden for 4, @samp{fifth} for 5,
address@hidden for 6, @samp{seventh} for 7, @samp{eighth} for 8,
address@hidden for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
address@hidden for 12.
+
address@hidden months, written-out
+When a month is written this way, it is still considered to be written
+numerically, instead of being ``spelled in full''; this changes the
+allowed strings.
+
address@hidden language, in dates
+In the current implementation, only English is supported for words and
+abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
address@hidden, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
+
address@hidden language, in dates
address@hidden time zone item
+The output of the @command{date} command
+is not always acceptable as a date string,
+not only because of the language problem, but also because there is no
+standard meaning for time zone items like @samp{IST}. When using
address@hidden to generate a date string intended to be parsed later,
+specify a date format that is independent of language and that does not
+use time zone items other than @samp{UTC} and @samp{Z}. Here are some
+ways to do this:
+
address@hidden
+$ LC_ALL=C TZ=UTC0 date
+Mon Mar 1 00:21:42 UTC 2004
+$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+2004-03-01 00:21:42Z
+$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
+2004-02-29 16:21:42,692722128-0800
+$ date --rfc-2822 # a GNU extension
+Sun, 29 Feb 2004 16:21:42 -0800
+$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
+2004-02-29 16:21:42 -0800
+$ date +'@@%s.%N' # %s and %N are GNU extensions.
+@@1078100502.692722128
address@hidden example
+
address@hidden case, ignored in dates
address@hidden comments, in dates
+Alphabetic case is completely ignored in dates. Comments may be introduced
+between round parentheses, as long as included parentheses are properly
+nested. Hyphens not followed by a digit are currently ignored. Leading
+zeros on numbers are ignored.
+
+Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
+rejected. In the typical case of a host that does not support leap
+seconds, a time like @samp{23:59:60} is rejected even if it
+corresponds to a valid leap second.
+
+
address@hidden Calendar date items
address@hidden Calendar date items
+
address@hidden calendar date item
+
+A @dfn{calendar date item} specifies a day of the year. It is
+specified differently, depending on whether the month is specified
+numerically or literally. All these strings specify the same calendar date:
+
address@hidden
+1972-09-24 # @sc{iso} 8601.
+72-9-24 # Assume 19xx for 69 through 99,
+ # 20xx for 00 through 68.
+72-09-24 # Leading zeros are ignored.
+9/24/72 # Common U.S. writing.
+24 September 1972
+24 Sept 72 # September has a special abbreviation.
+24 Sep 72 # Three-letter abbreviations always allowed.
+Sep 24, 1972
+24-sep-72
+24sep72
address@hidden example
+
+The year can also be omitted. In this case, the last specified year is
+used, or the current year if none. For example:
+
address@hidden
+9/24
+sep 24
address@hidden example
+
+Here are the rules.
+
address@hidden @sc{iso} 8601 date format
address@hidden date format, @sc{iso} 8601
+For numeric months, the @sc{iso} 8601 format
address@hidden@address@hidden@var{day}} is allowed, where @var{year} is
+any positive number, @var{month} is a number between 01 and 12, and
address@hidden is a number between 01 and 31. A leading zero must be present
+if a number is less than ten. If @var{year} is 68 or smaller, then 2000
+is added to it; otherwise, if @var{year} is less than 100,
+then 1900 is added to it. The construct
address@hidden@var{month}/@var{day}/@var{year}}, popular in the United States,
+is accepted. Also @address@hidden/@var{day}}, omitting the year.
+
address@hidden month names in date strings
address@hidden abbreviations for months
+Literal months may be spelled out in full: @samp{January},
address@hidden, @samp{March}, @samp{April}, @samp{May}, @samp{June},
address@hidden, @samp{August}, @samp{September}, @samp{October},
address@hidden or @samp{December}. Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write @samp{Sept} instead of @samp{September}.
+
+When months are written literally, the calendar date may be given as any
+of the following:
+
address@hidden
address@hidden @var{month} @var{year}
address@hidden @var{month}
address@hidden @var{day} @var{year}
address@hidden@address@hidden
address@hidden example
+
+Or, omitting the year:
+
address@hidden
address@hidden @var{day}
address@hidden example
+
+
address@hidden Time of day items
address@hidden Time of day items
+
address@hidden time of day item
+
+A @dfn{time of day item} in date strings specifies the time on a given
+day. Here are some examples, all of which represent the same time:
+
address@hidden
+20:02:00.000000
+20:02
+8:02pm
+20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
address@hidden example
+
+More generally, the time of day may be given as
address@hidden@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
+a number between 0 and 23, @var{minute} is a number between 0 and
+59, and @var{second} is a number between 0 and 59 possibly followed by
address@hidden or @samp{,} and a fraction containing one or more digits.
+Alternatively,
address@hidden:@var{second}} can be omitted, in which case it is taken to
+be zero. On the rare hosts that support leap seconds, @var{second}
+may be 60.
+
address@hidden am @r{in date strings}
address@hidden pm @r{in date strings}
address@hidden midnight @r{in date strings}
address@hidden noon @r{in date strings}
+If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
+or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
address@hidden:@var{minute}} may be omitted (taken to be zero). @samp{am}
+indicates the first half of the day, @samp{pm} indicates the second
+half of the day. In this notation, 12 is the predecessor of 1:
+midnight is @samp{12am} while noon is @samp{12pm}.
+(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
+as opposed to the old tradition derived from Latin
+which uses @samp{12m} for noon and @samp{12pm} for midnight.)
+
address@hidden time zone correction
address@hidden minutes, time zone correction by
+The time may alternatively be followed by a time zone correction,
+expressed as @address@hidden@address@hidden, where @var{s} is @samp{+}
+or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
+of zone minutes. You can also separate @var{hh} from @var{mm} with a colon.
+When a time zone correction is given this way, it
+forces interpretation of the time relative to
+Coordinated Universal Time (@sc{utc}), overriding any previous
+specification for the time zone or the local time zone. For example,
address@hidden and @samp{+05:30} both stand for the time zone 5.5 hours
+ahead of @sc{utc} (e.g., India). The @var{minute}
+part of the time of day may not be elided when a time zone correction
+is used. This is the best way to specify a time zone correction by
+fractional parts of an hour.
+
+Either @samp{am}/@samp{pm} or a time zone correction may be specified,
+but not both.
+
+
address@hidden Time zone items
address@hidden Time zone items
+
address@hidden time zone item
+
+A @dfn{time zone item} specifies an international time zone, indicated
+by a small set of letters, e.g., @samp{UTC} or @samp{Z}
+for Coordinated Universal
+Time. Any included periods are ignored. By following a
+non-daylight-saving time zone by the string @samp{DST} in a separate
+word (that is, separated by some white space), the corresponding
+daylight saving time zone may be specified.
+Alternatively, a non-daylight-saving time zone can be followed by a
+time zone correction, to add the two values. This is normally done
+only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
address@hidden:30}.
+
+Time zone items other than @samp{UTC} and @samp{Z}
+are obsolescent and are not recommended, because they
+are ambiguous; for example, @samp{EST} has a different meaning in
+Australia than in the United States. Instead, it's better to use
+unambiguous numeric time zone corrections like @samp{-0500}, as
+described in the previous section.
+
+If neither a time zone item nor a time zone correction is supplied,
+time stamps are interpreted using the rules of the default time zone
+(@pxref{Specifying time zone rules}).
+
+
address@hidden Day of week items
address@hidden Day of week items
+
address@hidden day of week item
+
+The explicit mention of a day of the week will forward the date
+(only if necessary) to reach that day of the week in the future.
+
+Days of the week may be spelled out in full: @samp{Sunday},
address@hidden, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
address@hidden or @samp{Saturday}. Days may be abbreviated to their
+first three letters, optionally followed by a period. The special
+abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
address@hidden and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
+also allowed.
+
address@hidden next @var{day}
address@hidden last @var{day}
+A number may precede a day of the week item to move forward
+supplementary weeks. It is best used in expression like @samp{third
+monday}. In this context, @samp{last @var{day}} or @samp{next
address@hidden is also acceptable; they move one week before or after
+the day that @var{day} by itself would represent.
+
+A comma following a day of the week item is ignored.
+
+
address@hidden Relative items in date strings
address@hidden Relative items in date strings
+
address@hidden relative items in date strings
address@hidden displacement of dates
+
address@hidden items} adjust a date (or the current date if none) forward
+or backward. The effects of relative items accumulate. Here are some
+examples:
+
address@hidden
+1 year
+1 year ago
+3 years
+2 days
address@hidden example
+
address@hidden year @r{in date strings}
address@hidden month @r{in date strings}
address@hidden fortnight @r{in date strings}
address@hidden week @r{in date strings}
address@hidden day @r{in date strings}
address@hidden hour @r{in date strings}
address@hidden minute @r{in date strings}
+The unit of time displacement may be selected by the string @samp{year}
+or @samp{month} for moving by whole years or months. These are fuzzy
+units, as years and months are not all of equal duration. More precise
+units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
+days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
address@hidden or @samp{min} worth 60 seconds, and @samp{second} or
address@hidden worth one second. An @samp{s} suffix on these units is
+accepted and ignored.
+
address@hidden ago @r{in date strings}
+The unit of time may be preceded by a multiplier, given as an optionally
+signed number. Unsigned numbers are taken as positively signed. No
+number at all implies 1 for a multiplier. Following a relative item by
+the string @samp{ago} is equivalent to preceding the unit by a
+multiplier with value @math{-1}.
+
address@hidden day @r{in date strings}
address@hidden tomorrow @r{in date strings}
address@hidden yesterday @r{in date strings}
+The string @samp{tomorrow} is worth one day in the future (equivalent
+to @samp{day}), the string @samp{yesterday} is worth
+one day in the past (equivalent to @samp{day ago}).
+
address@hidden now @r{in date strings}
address@hidden today @r{in date strings}
address@hidden this @r{in date strings}
+The strings @samp{now} or @samp{today} are relative items corresponding
+to zero-valued time displacement, these strings come from the fact
+a zero-valued time displacement represents the current time when not
+otherwise changed by previous items. They may be used to stress other
+items, like in @samp{12:00 today}. The string @samp{this} also has
+the meaning of a zero-valued time displacement, but is preferred in
+date strings like @samp{this thursday}.
+
+When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time,
+the resulting date and time are adjusted accordingly.
+
+The fuzz in units can cause problems with relative items. For
+example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
+because 2003-06-31 is an invalid date. To determine the previous
+month more reliably, you can ask for the month before the 15th of the
+current month. For example:
+
address@hidden
+$ date -R
+Thu, 31 Jul 2003 13:02:39 -0700
+$ date --date='-1 month' +'Last month was %B?'
+Last month was July?
+$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+Last month was June!
address@hidden example
+
+Also, take care when manipulating dates around clock changes such as
+daylight saving leaps. In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the @env{TZ} environment variable to
address@hidden before embarking on calendrical calculations.
+
address@hidden Pure numbers in date strings
address@hidden Pure numbers in date strings
+
address@hidden pure numbers in date strings
+
+The precise interpretation of a pure decimal number depends
+on the context in the date string.
+
+If the decimal number is of the form @address@hidden@var{dd} and no
+other calendar date item (@pxref{Calendar date items}) appears before it
+in the date string, then @var{yyyy} is read as the year, @var{mm} as the
+month number and @var{dd} as the day of the month, for the specified
+calendar date.
+
+If the decimal number is of the form @address@hidden and no other time
+of day item appears before it in the date string, then @var{hh} is read
+as the hour of the day and @var{mm} as the minute of the hour, for the
+specified time of day. @var{mm} can also be omitted.
+
+If both a calendar date and a time of day appear to the left of a number
+in the date string, but no relative item, then the number overrides the
+year.
+
+
address@hidden Seconds since the Epoch
address@hidden Seconds since the Epoch
+
+If you precede a number with @samp{@@}, it represents an internal time
+stamp as a count of seconds. The number can contain an internal
+decimal point (either @samp{.} or @samp{,}); any excess precision not
+supported by the internal representation is truncated toward minus
+infinity. Such a number cannot be combined with any other date
+item, as it specifies a complete time stamp.
+
address@hidden beginning of time, for @acronym{POSIX}
address@hidden epoch, for @acronym{POSIX}
+Internally, computer times are represented as a count of seconds since
+an epoch---a well-defined point of time. On @acronym{GNU} and
address@hidden systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
address@hidden@@0} represents this time, @samp{@@1} represents 1970-01-01
+00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
address@hidden systems support such times as an extension
+to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
+represents 1969-12-31 23:59:59 @sc{utc}.
+
+Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
+of seconds with nanosecond subcounts, and can represent all the times
+in the known lifetime of the universe to a resolution of 1 nanosecond.
+
+On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts @samp{@@915148799} represents 1998-12-31
+23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
address@hidden, and there is no way to represent the intervening leap second
+1998-12-31 23:59:60 @sc{utc}.
+
address@hidden Specifying time zone rules
address@hidden Specifying time zone rules
+
address@hidden TZ
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the @env{TZ} environment
+variable, or by a system default if @env{TZ} is not set. To specify a
+different set of default time zone rules that apply just to one date,
+start the date with a string of the form @samp{TZ="@var{rule}"}. The
+two quote characters (@samp{"}) must be present in the date, and any
+quotes or backslashes within @var{rule} must be escaped by a
+backslash.
+
+For example, with the @acronym{GNU} @command{date} command you can
+answer the question ``What time is it in New York when a Paris clock
+shows 6:30am on October 31, 2004?'' by using a date beginning with
address@hidden"Europe/Paris"} as shown in the following shell transcript:
+
address@hidden
+$ export TZ="America/New_York"
+$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+Sun Oct 31 01:30:00 EDT 2004
address@hidden example
+
+In this example, the @option{--date} operand begins with its own
address@hidden setting, so the rest of that operand is processed according
+to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
+06:30} as if it were in Paris. However, since the output of the
address@hidden command is processed according to the overall time zone
+rules, it uses New York time. (Paris was normally six hours ahead of
+New York in 2004, but this example refers to a brief Halloween period
+when the gap was five hours.)
+
+A @env{TZ} value is a rule that typically names a location in the
address@hidden://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
+A recent catalog of location names appears in the
address@hidden://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
+Gateway}. A few address@hidden hosts require a colon before a
+location name in a @env{TZ} setting, e.g.,
address@hidden":America/New_York"}.
+
+The @samp{tz} database includes a wide variety of locations ranging
+from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
+if you are at sea and have your own private time zone, or if you are
+using a address@hidden host that does not support the @samp{tz}
+database, you may need to use a @acronym{POSIX} rule instead. Simple
address@hidden rules like @samp{UTC0} specify a time zone without
+daylight saving time; other rules can specify simple daylight saving
+regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
+libc, The GNU C Library}.
+
address@hidden Authors of get_date
address@hidden Authors of @code{get_date}
+
address@hidden authors of @code{get_date}
+
address@hidden Bellovin, Steven M.
address@hidden Salz, Rich
address@hidden Berets, Jim
address@hidden MacKenzie, David
address@hidden Meyering, Jim
address@hidden Eggert, Paul
address@hidden was originally implemented by Steven M. Bellovin
+(@email{smb@@research.att.com}) while at the University of North Carolina
+at Chapel Hill. The code was later tweaked by a couple of people on
+Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
+and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
+revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
+Paul Eggert and others.
+
address@hidden Pinard, F.
address@hidden Berry, K.
+This chapter was originally produced by Fran@,{c}ois Pinard
+(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
+and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
+
address@hidden Formats
address@hidden Controlling the Archive Format
+
address@hidden Tar archive formats
+Due to historical reasons, there are several formats of tar archives.
+All of them are based on the same principles, but have some subtle
+differences that often make them incompatible with each other.
+
+GNU tar is able to create and handle archives in a variety of formats.
+The most frequently used formats are (in alphabetical order):
+
address@hidden @asis
address@hidden gnu
+Format used by @acronym{GNU} @command{tar} versions up to 1.13.25. This
format derived
+from an early @acronym{POSIX} standard, adding some improvements such as
+sparse file handling and incremental archives. Unfortunately these
+features were implemented in a way incompatible with other archive
+formats.
+
+Archives in @samp{gnu} format are able to hold pathnames of unlimited
+length.
+
address@hidden oldgnu
+Format used by @acronym{GNU} @command{tar} of versions prior to 1.12.
+
address@hidden v7
+Archive format, compatible with the V7 implementation of tar. This
+format imposes a number of limitations. The most important of them
+are:
+
address@hidden
address@hidden The maximum length of a file name is limited to 99 characters.
address@hidden The maximum length of a symbolic link is limited to 99
characters.
address@hidden It is impossible to store special files (block and character
+devices, fifos etc.)
address@hidden Maximum value of user or group ID is limited to 2097151 (7777777
+octal)
address@hidden V7 archives do not contain symbolic ownership information (user
+and group name of the file owner).
address@hidden enumerate
+
+This format has traditionally been used by Automake when producing
+Makefiles. This practice will change in the future, in the meantime,
+however this means that projects containing filenames more than 99
+characters long will not be able to use @acronym{GNU} @command{tar} 1.15.92 and
+Automake prior to 1.9.
+
address@hidden ustar
+Archive format defined by @acronym{POSIX.1-1988} specification. It stores
+symbolic ownership information. It is also able to store
+special files. However, it imposes several restrictions as well:
+
address@hidden
address@hidden The maximum length of a file name is limited to 256 characters,
+provided that the filename can be split at directory separator in
+two parts, first of them being at most 155 bytes long. So, in most
+cases the maximum file name length will be shorter than 256
+characters.
address@hidden The maximum length of a symbolic link name is limited to
+100 characters.
address@hidden Maximum size of a file the archive is able to accomodate
+is 8GB
address@hidden Maximum value of UID/GID is 2097151.
address@hidden Maximum number of bits in device major and minor numbers is 21.
address@hidden enumerate
+
address@hidden star
+Format used by J@"org Schilling @command{star}
+implementation. @acronym{GNU} @command{tar} is able to read @samp{star}
archives but
+currently does not produce them.
+
address@hidden posix
+Archive format defined by @acronym{POSIX.1-2001} specification. This is the
+most flexible and feature-rich format. It does not impose any
+restrictions on file sizes or filename lengths. This format is quite
+recent, so not all tar implementations are able to handle it properly.
+However, this format is designed in such a way that any tar
+implementation able to read @samp{ustar} archives will be able to read
+most @samp{posix} archives as well, with the only exception that any
+additional information (such as long file names etc.) will in such
+case be extracted as plain text files along with the files it refers to.
+
+This archive format will be the default format for future versions
+of @acronym{GNU} @command{tar}.
+
address@hidden table
+
+The following table summarizes the limitations of each of these
+formats:
+
address@hidden @columnfractions .10 .20 .20 .20 .20
address@hidden Format @tab UID @tab File Size @tab Path Name @tab Devn
address@hidden gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
address@hidden oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
address@hidden v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
address@hidden ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
address@hidden posix @tab Unlimited @tab Unlimited @tab Unlimited @tab
Unlimited
address@hidden multitable
+
+The default format for @acronym{GNU} @command{tar} is defined at compilation
+time. You may check it by running @command{tar --help}, and examining
+the last lines of its output. Usually, @acronym{GNU} @command{tar} is
configured
+to create archives in @samp{gnu} format, however, future version will
+switch to @samp{posix}.
+
address@hidden
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making @command{tar} Archives More Portable
+* cpio:: Comparison of @command{tar} and @command{cpio}
address@hidden menu
+
address@hidden Compression
address@hidden Using Less Space through Compression
+
address@hidden
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
address@hidden menu
+
address@hidden gzip
address@hidden Creating and Reading Compressed Archives
address@hidden Compressed archives
address@hidden Storing archives in compressed format
+
address@hidden @command{tar} is able to create and read compressed archives.
It supports
address@hidden and @command{bzip2} compression programs. For backward
+compatibilty, 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 less
+effective than @command{gzip} and @command{bzip2}.
+
+Creating a compressed archive is simple: you just specify a
address@hidden 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, and
address@hidden (@option{--compress}) to use @command{compress} program.
+For example:
+
address@hidden
+$ @kbd{tar cfz archive.tar.gz .}
address@hidden smallexample
+
+Reading compressed archive is even simpler: you don't need to specify
+any additional options as @acronym{GNU} @command{tar} recognizes its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+
address@hidden
+# List the compressed archive
+$ @kbd{tar tf archive.tar.gz}
+# Extract the compressed archive
+$ @kbd{tar xf archive.tar.gz}
address@hidden smallexample
+
+The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case @acronym{GNU}
@command{tar}
+will indicate which option you should use. For example:
+
address@hidden
+$ @kbd{cat archive.tar.gz | tar tf -}
+tar: Archive is compressed. Use -z option
+tar: Error is not recoverable: exiting now
address@hidden smallexample
+
+If you see such diagnostics, just add the suggested option to the
+invocation of @acronym{GNU} @command{tar}:
+
address@hidden
+$ @kbd{cat archive.tar.gz | tar tfz -}
address@hidden smallexample
+
+Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e., you cannot update (@option{--update} (@option{-u})) them or
delete
+(@option{--delete}) members from them. Likewise, you cannot append
+another @command{tar} archive to a compressed archive using
address@hidden (@option{-r})). Secondly, multi-volume archives cannot be
+compressed.
+
+The following table summarizes compression options used by @acronym{GNU}
@command{tar}.
+
address@hidden @option
address@hidden gzip
address@hidden ungzip
address@hidden -z
address@hidden --gzip
address@hidden --ungzip
+Filter the archive through @command{gzip}.
+
+You can use @option{--gzip} and @option{--gunzip} on physical devices
+(tape drives, etc.) and remote files as well as on normal files; data
+to or from such devices or remote files is reblocked by another copy
+of the @command{tar} program to enforce the specified (or default) record
+size. The default compression parameters are used; if you need to
+override them, set @env{GZIP} environment variable, e.g.:
+
address@hidden
+$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
address@hidden smallexample
+
address@hidden
+Another way would be to avoid the @option{--gzip} (@option{--gunzip},
@option{--ungzip}, @option{-z}) option and run
address@hidden explicitly:
+
address@hidden
+$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
address@hidden smallexample
+
address@hidden corrupted archives
+About corrupted compressed archives: @command{gzip}'ed files have no
+redundancy, for maximum compression. The adaptive nature of the
+compression scheme means that the compression tables are implicitly
+spread all over the archive. If you lose a few blocks, the dynamic
+construction of the compression tables becomes unsynchronized, and there
+is little chance that you could recover later in the archive.
+
+There are pending suggestions for having a per-volume or per-file
+compression in @acronym{GNU} @command{tar}. This would allow for viewing the
+contents without decompression, and for resynchronizing decompression at
+every volume or file, in case of corrupted archives. Doing so, we might
+lose some compressibility. But this would have make recovering easier.
+So, there are pros and cons. We'll see!
+
address@hidden bzip2
address@hidden -j
address@hidden --bzip2
+Filter the archive through @code{bzip2}. Otherwise like @option{--gzip}.
+
address@hidden compress
address@hidden uncompress
address@hidden -Z
address@hidden --compress
address@hidden --uncompress
+Filter the archive through @command{compress}. Otherwise like @option{--gzip}.
+
+The @acronym{GNU} Project recommends you not use
address@hidden, because there is a patent covering the algorithm it
+uses. You could be sued for patent infringement merely by running
address@hidden
+
address@hidden use-compress-program
address@hidden address@hidden
+Use external compression program @var{prog}. Use this option if you
+have a compression program that @acronym{GNU} @command{tar} does not support.
There
+are two requirements to which @var{prog} should comply:
+
+First, when called without options, it should read data from standard
+input, compress it and output it on standard output.
+
+Secondly, if called with @option{-d} argument, it should do exactly
+the opposite, i.e., read the compressed data from the standard input
+and produce uncompressed data on the standard output.
address@hidden table
+
address@hidden gpg, using with tar
address@hidden gnupg, using with tar
address@hidden Using encrypted archives
+The @option{--use-compress-program} option, in particular, lets you
+implement your own filters, not necessarily dealing with
+compression/decomression. For example, suppose you wish to implement
+PGP encryption on top of compression, using @command{gpg} (@pxref{Top,
+gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard
+Manual}). The following script does that:
+
address@hidden
address@hidden
+#! /bin/sh
+case $1 in
+-d) gpg --decrypt - | gzip -d -c;;
+'') gzip -c | gpg -s ;;
+*) echo "Unknown option $1">&2; exit 1;;
+esac
address@hidden group
address@hidden smallexample
+
+Suppose you name it @file{gpgz} and save it somewhere in your
address@hidden Then the following command will create a commpressed
+archive signed with your private key:
+
address@hidden
+$ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
address@hidden smallexample
+
address@hidden
+Likewise, the following command will list its contents:
+
address@hidden
+$ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
address@hidden smallexample
+
+
address@hidden sparse
address@hidden Archiving Sparse Files
address@hidden Sparse Files
+
+Files in the file system occasionally have @dfn{holes}. A @dfn{hole}
+in a file is a section of the file's contents which was never written.
+The contents of a hole reads as all zeros. On many operating systems,
+actual disk storage is not allocated for holes, but they are counted
+in the length of the file. If you archive such a file, @command{tar}
+could create an archive longer than the original. To have @command{tar}
+attempt to recognize the holes in a file, use @option{--sparse}
+(@option{-S}). When you use this option, then, for any file using
+less disk space than would be expected from its length, @command{tar}
+searches the file for consecutive stretches of zeros. It then records
+in the archive for the file where the consecutive stretches of zeros
+are, and only archives the ``real contents'' of the file. On
+extraction (using @option{--sparse} is not needed on extraction) any
+such files have holes created wherever the continuous stretches of zeros
+were found. Thus, if you use @option{--sparse}, @command{tar} archives
+won't take more space than the original.
+
address@hidden @option
address@hidden sparse
address@hidden -S
address@hidden --sparse
+This option istructs @command{tar} to test each file for sparseness
+before attempting to archive it. If the file is found to be sparse it
+is treated specially, thus allowing to decrease the amount of space
+used by its image in the archive.
+
+This option is meaningful only when creating or updating archives. It
+has no effect on extraction.
address@hidden table
+
+Consider using @option{--sparse} when performing file system backups,
+to avoid archiving the expanded forms of files stored sparsely in the
+system.
+
+Even if your system has no sparse files currently, some may be
+created in the future. If you use @option{--sparse} while making file
+system backups as a matter of course, you can be assured the archive
+will never take more space on the media than the files take on disk
+(otherwise, archiving a disk filled with sparse files might take
+hundreds of tapes). @xref{Incremental Dumps}.
+
+However, be aware that @option{--sparse} option presents a serious
+drawback. Namely, in order to determine if the file is sparse
address@hidden has to read it before trying to archive it, so in total
+the file is read @strong{twice}. So, always bear in mind that the
+time needed to process all files with this option is roughly twice
+the time needed to archive them without it.
address@hidden
address@hidden
+
+
address@hidden sparse formats, defined
+When using @samp{POSIX} archive format, @acronym{GNU} @command{tar} is able to
store
+sparse files using in three distinct ways, called @dfn{sparse
+formats}. A sparse format is identified by its @dfn{number},
+consisting, as usual of two decimal numbers, delimited by a dot. By
+default, format @samp{1.0} is used. If, for some reason, you wish to
+use an earlier format, you can select it using
address@hidden option.
+
address@hidden @option
address@hidden sparse-version
address@hidden address@hidden
+
+Select the format to store sparse files in. Valid @var{version} values
+are: @samp{0.0}, @samp{0.1} and @samp{1.0}. @xref{Sparse Formats},
+for a detailed description of each format.
address@hidden table
+
+Using @option{--sparse-format} option implies @option{--sparse}.
+
address@hidden Attributes
address@hidden Handling File Attributes
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+When @command{tar} reads files, it updates their access times. To
+avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either
+reset the access time retroactively or avoid changing it in the first
+place.
+
+Handling of file attributes
+
address@hidden @option
address@hidden atime-preserve
address@hidden --atime-preserve
address@hidden --atime-preserve=replace
address@hidden --atime-preserve=system
+Preserve the access times of files that are read. This works only for
+files that you own, unless you have superuser privileges.
+
address@hidden works on most systems, but it also
+restores the data modification time and updates the status change
+time. Hence it doesn't interact with incremental dumps nicely
+(@pxref{Incremental Dumps}), and it can set access or data modification times
+incorrectly if other programs access the file while @command{tar} is
+running.
+
address@hidden avoids changing the access time in
+the first place, if the operating system supports this.
+Unfortunately, this may or may not work on any given operating system
+or file system. If @command{tar} knows for sure it won't work, it
+complains right away.
+
+Currently @option{--atime-preserve} with no operand defaults to
address@hidden, but this is intended to change to
address@hidden when the latter is better-supported.
+
address@hidden touch
address@hidden -m
address@hidden --touch
+Do not extract data modification time.
+
+When this option is used, @command{tar} leaves the data modification times
+of the files it extracts as the times when the files were extracted,
+instead of setting it to the times recorded in the archive.
+
+This option is meaningless with @option{--list} (@option{-t}).
+
address@hidden same-owner
address@hidden --same-owner
+Create extracted files with the same ownership they have in the
+archive.
+
+This is the default behavior for the superuser,
+so this option is meaningful only for non-root users, when @command{tar}
+is executed on those systems able to give files away. This is
+considered as a security flaw by many people, at least because it
+makes quite difficult to correctly account users for the disk space
+they occupy. Also, the @code{suid} or @code{sgid} attributes of
+files are easily and silently lost when files are given away.
+
+When writing an archive, @command{tar} writes the user id and user name
+separately. If it can't find a user name (because the user id is not
+in @file{/etc/passwd}), then it does not write one. When restoring,
+it tries to look the name (if one was written) up in
address@hidden/etc/passwd}. If it fails, then it uses the user id stored in
+the archive instead.
+
address@hidden no-same-owner
address@hidden --no-same-owner
address@hidden -o
+Do not attempt to restore ownership when extracting. This is the
+default behavior for ordinary users, so this option has an effect
+only for the superuser.
+
address@hidden numeric-owner
address@hidden --numeric-owner
+The @option{--numeric-owner} option allows (ANSI) archives to be written
+without user/group name information or such information to be ignored
+when extracting. It effectively disables the generation and/or use
+of user/group name information. This option forces extraction using
+the numeric ids from the archive, ignoring the names.
+
+This is useful in certain circumstances, when restoring a backup from
+an emergency floppy with different passwd/group files for example.
+It is otherwise impossible to extract files with the right ownerships
+if the password file in use during the extraction does not match the
+one belonging to the file system(s) being extracted. This occurs,
+for example, if you are restoring your files after a major crash and
+had booted from an emergency floppy with no password file or put your
+disk into another machine to do the restore.
+
+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
+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.
+
+When making a @command{tar} file for distribution to other sites, it
+is sometimes cleaner to use a single owner for all files in the
+distribution, and nicer to specify the write permission bits of the
+files as stored in the archive independently of their actual value on
+the file system. The way to prepare a clean distribution is usually
+to have some Makefile rule creating a directory, copying all needed
+files in that directory, then setting ownership and permissions as
+wanted (there are a lot of possible schemes), and only then making a
address@hidden archive out of this directory, before cleaning
+everything out. Of course, we could add a lot of options to
address@hidden @command{tar} for fine tuning permissions and ownership.
+This is not the good way, I think. @acronym{GNU} @command{tar} is
+already crowded with options and moreover, the approach just explained
+gives you a great deal of control already.
+
address@hidden address@hidden, short description}
address@hidden address@hidden, short description}
address@hidden -p
address@hidden --same-permissions
address@hidden --preserve-permissions
+Extract all protection information.
+
+This option causes @command{tar} to set the modes (access permissions) of
+extracted files exactly as recorded in the archive. If this option
+is not used, the current @code{umask} setting limits the permissions
+on extracted files. This option is by default enabled when
address@hidden is executed by a superuser.
+
+
+This option is meaningless with @option{--list} (@option{-t}).
+
address@hidden preserve
address@hidden --preserve
+Same as both @option{--same-permissions} and @option{--same-order}.
+
+The @option{--preserve} option has no equivalent short option name.
+It is equivalent to @option{--same-permissions} plus @option{--same-order}.
+
address@hidden
address@hidden
+
+
address@hidden table
+
address@hidden Portability
address@hidden Making @command{tar} Archives More Portable
+
+Creating a @command{tar} archive on a particular system that is meant to be
+useful later on many other machines and with other versions of @command{tar}
+is more challenging than you might think. @command{tar} archive formats
+have been evolving since the first versions of Unix. Many such formats
+are around, and are not always compatible with each other. This section
+discusses a few problems, and gives some advice about making @command{tar}
+archives more portable.
+
+One golden rule is simplicity. For example, limit your @command{tar}
+archives to contain only regular files and directories, avoiding
+other kind of special files. Do not attempt to save sparse files or
+contiguous files as such. Let's discuss a few more problems, in turn.
+
address@hidden
address@hidden
+
+
address@hidden
+* Portable Names:: Portable Names
+* dereference:: Symbolic Links
+* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
+* posix:: @acronym{POSIX} archives
+* Checksumming:: Checksumming Problems
+* Large or Negative Values:: Large files, negative time stamps, etc.
+* Other Tars:: How to Extract GNU-Specific Data Using
+ Other @command{tar} Implementations
address@hidden menu
+
address@hidden Portable Names
address@hidden Portable Names
+
+Use portable file and member names. A name is portable if it contains
+only ASCII letters and digits, @samp{/}, @samp{.}, @samp{_}, and
address@hidden; it cannot be empty, start with @samp{-} or @samp{//}, or
+contain @samp{/-}. Avoid deep directory nesting. For portability to
+old Unix hosts, limit your file name components to 14 characters or
+less.
+
+If you intend to have your @command{tar} archives to be read under
+MSDOS, you should not rely on case distinction for file names, and you
+might use the @acronym{GNU} @command{doschk} program for helping you
+further diagnosing illegal MSDOS names, which are even more limited
+than System V's.
+
address@hidden dereference
address@hidden Symbolic Links
address@hidden File names, using symbolic links
address@hidden Symbolic link as file name
+
address@hidden dereference
+Normally, when @command{tar} archives a symbolic link, it writes a
+block to the archive naming the target of the link. In that way, the
address@hidden archive is a faithful record of the file system contents.
address@hidden (@option{-h}) is used with @option{--create} (@option{-c}), and
causes
address@hidden to archive the files symbolic links point to, instead of
+the links themselves. When this option is used, when @command{tar}
+encounters a symbolic link, it will archive the linked-to file,
+instead of simply recording the presence of a symbolic link.
+
+The name under which the file is stored in the file system is not
+recorded in the archive. To record both the symbolic link name and
+the file name in the system, archive the file under both names. If
+all links were recorded automatically by @command{tar}, an extracted file
+might be linked to a file name that no longer exists in the file
+system.
+
+If a linked-to file is encountered again by @command{tar} while creating
+the same archive, an entire second copy of it will be stored. (This
address@hidden be considered a bug.)
+
+So, for portable archives, do not archive symbolic links as such,
+and use @option{--dereference} (@option{-h}): many systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
+
address@hidden old
address@hidden Old V7 Archives
address@hidden Format, old style
address@hidden Old style format
address@hidden Old style archives
address@hidden v7 archive format
+
+Certain old versions of @command{tar} cannot handle additional
+information recorded by newer @command{tar} programs. To create an
+archive in V7 format (not ANSI), which can be read by these old
+versions, specify the @option{--format=v7} option in
+conjunction with the @option{--create} (@option{-c}) (@command{tar} also
+accepts @option{--portability} or @option{--old-archive} for this
+option). When you specify it,
address@hidden leaves out information about directories, pipes, fifos,
+contiguous files, and device files, and specifies file ownership by
+group and user IDs instead of group and user names.
+
+When updating an archive, do not use @option{--format=v7}
+unless the archive was created using this option.
+
+In most cases, a @emph{new} format archive can be read by an @emph{old}
address@hidden program without serious trouble, so this option should
+seldom be needed. On the other hand, most modern @command{tar}s are
+able to read old format archives, so it might be safer for you to
+always use @option{--format=v7} for your distributions. Notice,
+however, that @samp{ustar} format is a better alternative, as it is
+free from many of @samp{v7}'s drawbacks.
+
address@hidden ustar
address@hidden Ustar Archive Format
+
address@hidden ustar archive format
+Archive format defined by @acronym{POSIX}.1-1988 specification is called
address@hidden Although it is more flexible than the V7 format, it
+still has many restrictions (@xref{Formats,ustar}, for the detailed
+description of @code{ustar} format). Along with V7 format,
address@hidden format is a good choice for archives intended to be read
+with other implementations of @command{tar}.
+
+To create archive in @code{ustar} format, use @option{--format=ustar}
+option in conjunction with the @option{--create} (@option{-c}).
+
address@hidden gnu
address@hidden @acronym{GNU} and old @acronym{GNU} @command{tar} format
+
address@hidden GNU archive format
address@hidden Old GNU archive format
address@hidden @command{tar} was based on an early draft of the
address@hidden 1003.1 @code{ustar} standard. @acronym{GNU} extensions to
address@hidden, such as the support for file names longer than 100
+characters, use portions of the @command{tar} header record which were
+specified in that @acronym{POSIX} draft as unused. Subsequent changes in
address@hidden have allocated the same parts of the header record for
+other purposes. As a result, @acronym{GNU} @command{tar} format is
+incompatible with the current @acronym{POSIX} specification, and with
address@hidden programs that follow it.
+
+In the majority of cases, @command{tar} will be configured to create
+this format by default. This will change in the future releases, since
+we plan to make @samp{POSIX} format the default.
+
+To force creation a @acronym{GNU} @command{tar} archive, use option
address@hidden
+
address@hidden posix
address@hidden @acronym{GNU} @command{tar} and @acronym{POSIX} @command{tar}
+
address@hidden POSIX archive format
address@hidden PAX archive format
+Starting from version 1.14 @acronym{GNU} @command{tar} features full support
for
address@hidden archives.
+
+A @acronym{POSIX} conformant archive will be created if @command{tar}
+was given @option{--format=posix} (@option{--format=pax}) option. No
+special option is required to read and extract from a @acronym{POSIX}
+archive.
+
address@hidden
+* PAX keywords:: Controlling Extended Header Keywords.
address@hidden menu
+
address@hidden PAX keywords
address@hidden Controlling Extended Header Keywords
+
address@hidden @option
address@hidden pax-option
address@hidden address@hidden
+Handle keywords in @acronym{PAX} extended headers. This option is
+equivalent to @option{-o} option of the @command{pax} utility.
address@hidden table
+
address@hidden is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+
address@hidden @code
address@hidden address@hidden
+When used with one of archive-creation commands,
+this option instructs @command{tar} to omit from extended header records
+that it produces any keywords matching the string @var{pattern}.
+
+When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given @var{pattern} in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in @acronym{POSIX 1003.2}, 3.13
+(@pxref{wildcards}). For example:
+
address@hidden
+--pax-option delete=security.*
address@hidden smallexample
+
+would suppress security-related information.
+
address@hidden address@hidden
+
+This keyword allows user control over the name that is written into the
+ustar header blocks for the extended headers. The name is obtained
+from @var{string} after making the following substitutions:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on the translated pathname.
address@hidden %f @tab The filename of the file, equivalent to the result
+of the @command{basename} utility on the translated pathname.
address@hidden %p @tab The process ID of the @command{tar} process.
address@hidden %% @tab A @samp{%} character.
address@hidden multitable
+
+Any other @samp{%} characters in @var{string} produce undefined
+results.
+
+If no option @samp{exthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
address@hidden
+%d/PaxHeaders.%p/%f
address@hidden smallexample
+
address@hidden address@hidden
+This keyword allows user control over the name that is written into
+the ustar header blocks for global extended header records. The name
+is obtained from the contents of @var{string}, after making
+the following substitutions:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %n @tab An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
address@hidden %p @tab The process ID of the @command{tar} process.
address@hidden %% @tab A @samp{%} character.
address@hidden multitable
+
+Any other @samp{%} characters in @var{string} produce undefined results.
+
+If no option @samp{globexthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
address@hidden
+$TMPDIR/GlobalHead.%p.%n
address@hidden smallexample
+
address@hidden
+where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
+environment variable. If @var{TMPDIR} is not set, @command{tar}
+uses @samp{/tmp}.
+
address@hidden @address@hidden
+When used with one of archive-creation commands, these keyword/value pairs
+will be included at the beginning of the archive in a global extended
+header record. When used with one of archive-reading commands,
address@hidden will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+
address@hidden @var{keyword}:address@hidden
+When used with one of archive-creation commands, these keyword/value pairs
+will be included as records at the beginning of an extended header for
+each file. This is effectively equivalent to @address@hidden
+form except that it creates no global extended header records.
+
+When used with one of archive-reading commands, @command{tar} will
+behave as if these keyword/value pairs were included as records at the
+end of each extended header; thus, they will override any global or
+file-specific extended header record keywords of the same names.
+For example, in the command:
+
address@hidden
+tar --format=posix --create \
+ --file archive --pax-option gname:=user .
address@hidden smallexample
+
+the group name will be forced to a new value for all files
+stored in the archive.
address@hidden table
+
address@hidden Checksumming
address@hidden Checksumming Problems
+
+SunOS and HP-UX @command{tar} fail to accept archives created using
address@hidden @command{tar} and containing non-ASCII file names, that
+is, file names having characters with the eight bit set, because they
+use signed checksums, while @acronym{GNU} @command{tar} uses unsigned
+checksums while creating archives, as per @acronym{POSIX} standards. On
+reading, @acronym{GNU} @command{tar} computes both checksums and
+accept any. It is somewhat worrying that a lot of people may go
+around doing backup of their files using faulty (or at least
+non-standard) software, not learning about it until it's time to
+restore their missing files with an incompatible file extractor, or
+vice versa.
+
address@hidden @command{tar} compute checksums both ways, and accept
+any on read, so @acronym{GNU} tar can read Sun tapes even with their
+wrong checksums. @acronym{GNU} @command{tar} produces the standard
+checksum, however, raising incompatibilities with Sun. That is to
+say, @acronym{GNU} @command{tar} has not been modified to
address@hidden incorrect archives to be read by buggy @command{tar}'s.
+I've been told that more recent Sun @command{tar} now read standard
+archives, so maybe Sun did a similar patch, after all?
+
+The story seems to be that when Sun first imported @command{tar}
+sources on their system, they recompiled it without realizing that
+the checksums were computed differently, because of a change in
+the default signing of @code{char}'s in their compiler. So they
+started computing checksums wrongly. When they later realized their
+mistake, they merely decided to stay compatible with it, and with
+themselves afterwards. Presumably, but I do not really know, HP-UX
+has chosen that their @command{tar} archives to be compatible with Sun's.
+The current standards do not favor Sun @command{tar} format. In any
+case, it now falls on the shoulders of SunOS and HP-UX users to get
+a @command{tar} able to read the good archives they receive.
+
address@hidden Large or Negative Values
address@hidden Large or Negative Values
address@hidden large values
address@hidden future time stamps
address@hidden negative time stamps
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+The above sections suggest to use @samp{oldest possible} archive
+format if in doubt. However, sometimes it is not possible. If you
+attempt to archive a file whose metadata cannot be represented using
+required format, @acronym{GNU} @command{tar} will print error message and
ignore such a
+file. You will than have to switch to a format that is able to
+handle such values. The format summary table (@pxref{Formats}) will
+help you to do so.
+
+In particular, when trying to archive files larger than 8GB or with
+timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
+12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and
address@hidden archive formats. When considering which format to
+choose, bear in mind that the @acronym{GNU} format uses
+two's-complement base-256 notation to store values that do not fit
+into standard @acronym{ustar} range. Such archives can generally be
+read only by a @acronym{GNU} @command{tar} implementation. Moreover, they
sometimes
+cannot be correctly restored on another hosts even by @acronym{GNU}
@command{tar}. For
+example, using two's complement representation for negative time
+stamps that assumes a signed 32-bit @code{time_t} generates archives
+that are not portable to hosts with differing @code{time_t}
+representations.
+
+On the other hand, @acronym{POSIX} archives, generally speaking, can
+be extracted by any tar implementation that understands older
address@hidden format. The only exception are files larger than 8GB.
+
address@hidden
address@hidden
+
+
address@hidden Other Tars
address@hidden How to Extract GNU-Specific Data Using Other @command{tar}
Implementations
+
+In previous sections you became acquainted with various quircks
+necessary to make your archives portable. Sometimes you may need to
+extract archives containing GNU-specific members using some
+third-party @command{tar} implementation or an older version of
address@hidden @command{tar}. Of course your best bet is to have @acronym{GNU}
@command{tar} installed,
+but if it is for some reason impossible, this section will explain
+how to cope without it.
+
+When we speak about @dfn{GNU-specific} members we mean two classes of
+them: members split between the volumes of a multi-volume archive and
+sparse members. You will be able to always recover such members if
+the archive is in PAX format. In addition split members can be
+recovered from archives in old GNU format. The following subsections
+describe the required procedures in detail.
+
address@hidden
+* Split Recovery:: Members Split Between Volumes
+* Sparse Recovery:: Sparse Members
address@hidden menu
+
address@hidden Split Recovery
address@hidden Extracting Members Split Between Volumes
+
address@hidden Mutli-volume archives, extracting using non-GNU tars
+If a member is split between several volumes of an old GNU format archive
+most third party @command{tar} implementation will fail to extract
+it. To extract it, use @command{tarcat} program (@pxref{Tarcat}).
+This program is available from
address@hidden://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html,
@acronym{GNU} @command{tar}
+home page}. It concatenates several archive volumes into a single
+valid archive. For example, if you have three volumes named from
address@hidden to @file{vol-2.tar}, you can do the following to
+extract them using a third-party @command{tar}:
+
address@hidden
+$ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -}
address@hidden smallexample
+
address@hidden Mutli-volume archives in PAX format, extracting using non-GNU
tars
+You could use this approach for many (although not all) PAX
+format archives as well. However, extracting split members from a PAX
+archive is a much easier task, because PAX volumes are constructed in
+such a way that each part of a split member is extracted as a
+different file by @command{tar} implementations that are not aware of
+GNU extensions. More specifically, the very first part retains its
+original name, and all subsequent parts are named using the pattern:
+
address@hidden
+%d/GNUFileParts.%p/%f.%n
address@hidden smallexample
+
address@hidden
+where symbols preceeded by @samp{%} are @dfn{macro characters} that
+have the following meaning:
+
address@hidden @columnfractions .25 .55
address@hidden Meta-character @tab Replaced By
address@hidden %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on its full name.
address@hidden %f @tab The file name of the file, equivalent to the result
+of the @command{basename} utility on its full name.
address@hidden %p @tab The process ID of the @command{tar} process that
+created the archive.
address@hidden %n @tab Ordinal number of this particular part.
address@hidden multitable
+
+For example, if, a file @file{var/longfile} was split during archive
+creation between three volumes, and the creator @command{tar} process
+had process ID @samp{27962}, then the member names will be:
+
address@hidden
+var/longfile
+var/GNUFileParts.27962/longfile.1
+var/GNUFileParts.27962/longfile.2
address@hidden smallexample
+
+When you extract your archive using a third-party @command{tar}, these
+files will be created on your disk, and the only thing you will need
+to do to restore your file in its original form is concatenate them in
+the proper order, for example:
+
address@hidden
address@hidden
+$ @kbd{cd var}
+$ @kbd{cat GNUFileParts.27962/longfile.1 \
+ GNUFileParts.27962/longfile.2 >> longfile}
+$ rm -f GNUFileParts.27962
address@hidden group
address@hidden smallexample
+
+Notice, that if the @command{tar} implementation you use supports PAX
+format archives, it will probably emit warnings about unknown keywords
+during extraction. They will lool like this:
+
address@hidden
address@hidden
+Tar file too small
+Unknown extended header keyword 'GNU.volume.filename' ignored.
+Unknown extended header keyword 'GNU.volume.size' ignored.
+Unknown extended header keyword 'GNU.volume.offset' ignored.
address@hidden group
address@hidden smallexample
+
address@hidden
+You can safely ignore these warnings.
+
+If your @command{tar} implementation is not PAX-aware, you will get
+more warnigns and more files generated on your disk, e.g.:
+
address@hidden
address@hidden
+$ @kbd{tar xf vol-1.tar}
+var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
+normal file
+Unexpected EOF in archive
+$ @kbd{tar xf vol-2.tar}
+tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
+GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
+'x', extracted as normal file
address@hidden group
address@hidden smallexample
+
+Ignore these warnings. The @file{PaxHeaders.*} directories created
+will contain files with @dfn{extended header keywords} describing the
+extracted files. You can delete them, unless they describe sparse
+members. Read further to learn more about them.
+
address@hidden Sparse Recovery
address@hidden Extracting Sparse Members
+
address@hidden sparse files, extracting with non-GNU tars
+Any @command{tar} implementation will be able to extract sparse members from a
+PAX archive. However, the extracted files will be @dfn{condensed},
+i.e. any zero blocks will be removed from them. When we restore such
+a condensed file to its original form, by adding zero bloks (or
address@hidden) back to their original locations, we call this process
address@hidden a compressed sparse file.
+
address@hidden xsparse
+To expand a file, you will need a simple auxiliary program called
address@hidden It is available in source form from
address@hidden://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html,
@acronym{GNU} @command{tar}
+home page}.
+
address@hidden sparse files v.1.0, extracting with non-GNU tars
+Let's begin with archive members in @dfn{sparse format
+version address@hidden@xref{PAX 1}.}, which are the easiest to expand.
+The condensed file will contain both file map and file data, so no
+additional data will be needed to restore it. If the original file
+name was @address@hidden/@var{name}}, then the condensed file will be
+named @address@hidden/@/address@hidden/@/@var{name}}, where
address@hidden is a decimal address@hidden speaking, @var{n} is a
address@hidden ID} of the @command{tar} process which created the
+archive (@pxref{PAX keywords}).}.
+
+To expand a version 1.0 file, run @command{xsparse} as follows:
+
address@hidden
+$ @kbd{xsparse @file{cond-file}}
address@hidden smallexample
+
address@hidden
+where @file{cond-file} is the name of the condensed file. The utility
+will deduce the name for the resulting expanded file using the
+following algorithm:
+
address@hidden 1
address@hidden If @file{cond-file} does not contain any directories,
address@hidden/cond-file} will be used;
+
address@hidden If @file{cond-file} has the form
address@hidden@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name}
+are simple names, with no @samp{/} characters in them, the output file
+name will be @address@hidden/@var{name}}.
+
address@hidden Otherwise, if @file{cond-file} has the form
address@hidden@var{dir}/@var{name}}, the output file name will be
address@hidden@var{name}}.
address@hidden enumerate
+
+In the unlikely case when this algorithm does not suite your needs,
+you can explicitely specify output file name as a second argument to
+the command:
+
address@hidden
+$ @kbd{xsparse @file{cond-file}}
address@hidden smallexample
+
+It is often a good idea to run @command{xsparse} in @dfn{dry run} mode
+first. In this mode, the command does not actually expand the file,
+but verbosely lists all actions it would be taking to do so. The dry
+run mode is enabled by @option{-n} command line argument:
+
address@hidden
address@hidden
+$ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Finished dry run
address@hidden group
address@hidden smallexample
+
+To actually expand the file, you would run:
+
address@hidden
+$ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile}
address@hidden smallexample
+
address@hidden
+The program behaves the same way all UNIX utilities do: it will keep
+quiet unless it has simething important to tell you (e.g. an error
+condition or something). If you wish it to produce verbose output,
+similar to that from the dry run mode, give it @option{-v} option:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
+Additionally, if your @command{tar} implementation has extracted the
address@hidden headers} for this file, you can instruct @command{xstar}
+to use them in order to verify the integrity of the expanded file.
+The option @option{-x} sets the name of the extended header file to
+use. Continuing our example:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
+ /home/gray/GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.major = 1
+Found variable GNU.sparse.minor = 0
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.realsize = 217481216
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
address@hidden sparse v.0.x}
address@hidden sparse files v.0.1, extracting with non-GNU tars
address@hidden sparse files v.0.0, extracting with non-GNU tars
+An @dfn{extended header} is a special @command{tar} archive header
+that precedes an archive member and contains a set of
address@hidden, describing the member properties that cannot be
+stored in the standard @code{ustar} header. While optional for
+expanding sparse version 1.0 members, use of extended headers is
+mandatory when expanding sparse members in older sparse formats: v.0.0
+and v.0.1 (The sparse formats are described in detail in @pxref{Sparse
+Formats}). So, for this format, the question is: how to obtain
+extended headers from the archive?
+
+If you use a @command{tar} implementation that does not support PAX
+format, extended headers for each member will be extracted as a
+separate file. If we represent the member name as
address@hidden@var{dir}/@var{name}}, then the extended header file will be
+named @address@hidden/@/address@hidden/@/@var{name}}, where
address@hidden is an integer number.
+
+Things become more difficult if your @command{tar} implementation
+does support PAX headers, because in this case you will have to
+manually extract the headers. We recommend the following algorithm:
+
address@hidden 1
address@hidden
+Consult the documentation for your @command{tar} implementation for an
+option that will print @dfn{block numbers} along with the archive
+listing (analogous to @acronym{GNU} @command{tar}'s @option{-R} option). For
example,
address@hidden has @option{-block-number}.
+
address@hidden
+Obtain the verbose listing using the @samp{block number} option, and
+find the position of the sparse member in question and the member
+immediately following it. For example, running @command{star} on our
+archive we obtain:
+
address@hidden
address@hidden
+$ @kbd{star -t -v -block-number -f arc.tar}
address@hidden
+star: Unknown extended header keyword 'GNU.sparse.size' ignored.
+star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
+star: Unknown extended header keyword 'GNU.sparse.name' ignored.
+star: Unknown extended header keyword 'GNU.sparse.map' ignored.
+block 56: 425984 -rw-r--r-- gray/users Jun 25 14:46 2006
GNUSparseFile.28124/sparsefile
+block 897: 65391 -rw-r--r-- gray/users Jun 24 20:06 2006 README
address@hidden
address@hidden group
address@hidden smallexample
+
address@hidden
+(as usual, ignore the warnings about unknown keywords.)
+
address@hidden
+Let @var{size} be the size of the sparse member, @var{Bs} be its block number
+and @var{Bn} be the block number of the next member.
+Compute:
+
address@hidden
address@hidden = @var{Bs} - @var{Bn} - @var{size}/512 - 2
address@hidden smallexample
+
address@hidden
+This number gives the size of the extended header part in tar @dfn{blocks}.
+In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2
+= 7}.
+
address@hidden
+Use @command{dd} to extract the headers:
+
address@hidden
address@hidden address@hidden address@hidden bs=512 address@hidden
address@hidden
address@hidden smallexample
+
address@hidden
+where @var{archive} is the archive name, @var{hname} is a name of the
+file to store the extended header in, @var{Bs} and @var{N} are
+computed in previous steps.
+
+In our example, this command will be
+
address@hidden
+$ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7}
address@hidden smallexample
address@hidden enumerate
+
+Finally, you can expand the condensed file, using the obtained header:
+
address@hidden
address@hidden
+$ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile}
+Reading extended header file
+Found variable GNU.sparse.size = 217481216
+Found variable GNU.sparse.numblocks = 208
+Found variable GNU.sparse.name = sparsefile
+Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
+Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
+Done
address@hidden group
address@hidden smallexample
+
address@hidden cpio
address@hidden Comparison of @command{tar} and @command{cpio}
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
+
+The @command{cpio} archive formats, like @command{tar}, do have maximum
+pathname lengths. The binary and old ASCII formats have a max path
+length of 256, and the new ASCII and CRC ASCII formats have a max
+path length of 1024. @acronym{GNU} @command{cpio} can read and write archives
+with arbitrary pathname lengths, but other @command{cpio} implementations
+may crash unexplainedly trying to read them.
+
address@hidden handles symbolic links in the form in which it comes in BSD;
address@hidden doesn't handle symbolic links in the form in which it comes
+in System V prior to SVR4, and some vendors may have added symlinks
+to their system without enhancing @command{cpio} to know about them.
+Others may have enhanced it in a way other than the way I did it
+at Sun, and which was adopted by AT&T (and which is, I think, also
+present in the @command{cpio} that Berkeley picked up from AT&T and put
+into a later BSD release---I think I gave them my changes).
+
+(SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio}
+can handle @command{tar} format input, and write it on output, and it
+probably handles symbolic links. They may not have bothered doing
+anything to enhance @command{tar} as a result.)
+
address@hidden handles special files; traditional @command{tar} doesn't.
+
address@hidden comes with V7, System III, System V, and BSD source;
address@hidden comes only with System III, System V, and later BSD
+(4.3-tahoe and later).
+
address@hidden's way of handling multiple hard links to a file can handle
+file systems that support 32-bit inumbers (e.g., the BSD file system);
address@hidden way requires you to play some games (in its "binary"
+format, i-numbers are only 16 bits, and in its "portable ASCII" format,
+they're 18 bits---it would have to play games with the "file system ID"
+field of the header to make sure that the file system ID/i-number pairs
+of different files were always different), and I don't know which
address@hidden, if any, play those games. Those that don't might get
+confused and think two files are the same file when they're not, and
+make hard links between them.
+
address@hidden way of handling multiple hard links to a file places only
+one copy of the link on the tape, but the name attached to that copy
+is the @emph{only} one you can use to retrieve the file; @command{cpio}s
+way puts one copy for every link, but you can retrieve it using any
+of the names.
+
address@hidden
+What type of check sum (if any) is used, and how is this calculated.
address@hidden quotation
+
+See the attached manual pages for @command{tar} and @command{cpio} format.
address@hidden uses a checksum which is the sum of all the bytes in the
address@hidden header for a file; @command{cpio} uses no checksum.
+
address@hidden
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene,
address@hidden quotation
+
+It wasn't. @command{cpio} first showed up in PWB/UNIX 1.0; no
+generally-available version of UNIX had @command{tar} at the time. I don't
+know whether any version that was generally available @emph{within AT&T}
+had @command{tar}, or, if so, whether the people within AT&T who did
address@hidden knew about it.
+
+On restore, if there is a corruption on a tape @command{tar} will stop at
+that point, while @command{cpio} will skip over it and try to restore the
+rest of the files.
+
+The main difference is just in the command syntax and header format.
+
address@hidden is a little more tape-oriented in that everything is blocked
+to start on a record boundary.
+
address@hidden
+Is there any differences between the ability to recover crashed
+archives between the two of them. (Is there any chance of recovering
+crashed archives at all.)
address@hidden quotation
+
+Theoretically it should be easier under @command{tar} since the blocking
+lets you find a header with some variation of @samp{dd address@hidden
+However, modern @command{cpio}'s and variations have an option to just
+search for the next file header after an error with a reasonable chance
+of resyncing. However, lots of tape driver software won't allow you to
+continue past a media error which should be the only reason for getting
+out of sync unless a file changed sizes while you were writing the
+archive.
+
address@hidden
+If anyone knows why @command{cpio} was made when @command{tar} was present
+at the unix scene, please tell me about this too.
address@hidden quotation
+
+Probably because it is more media efficient (by not blocking everything
+and using only the space needed for the headers where @command{tar}
+always uses 512 bytes per file header) and it knows how to archive
+special files.
+
+You might want to look at the freely available alternatives. The
+major ones are @command{afio}, @acronym{GNU} @command{tar}, and
address@hidden, each of which have their own extensions with some
+backwards compatibility.
+
+Sparse files were @command{tar}red as sparse files (which you can
+easily test, because the resulting archive gets smaller, and
address@hidden @command{cpio} can no longer read it).
+
address@hidden Media
address@hidden Tapes and Other Archive Media
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+A few special cases about tape handling warrant more detailed
+description. These special cases are discussed below.
+
+Many complexities surround the use of @command{tar} on tape drives. Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of @command{tar}, it contains many features making
+such manipulation easier.
+
+Archives are usually written on dismountable media---tape cartridges,
+mag tapes, or floppy disks.
+
+The amount of data a tape or disk holds depends not only on its size,
+but also on how it is formatted. A 2400 foot long reel of mag tape
+holds 40 megabytes of data when formatted at 1600 bits per inch. The
+physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
+
+Magnetic media are re-usable---once the archive on a tape is no longer
+needed, the archive can be erased and the tape or disk used over.
+Media quality does deteriorate with use, however. Most tapes or disks
+should be discarded when they begin to produce data errors. EXABYTE
+tape cartridges should be discarded when they generate an @dfn{error
+count} (number of non-usable bits) of more than 10k.
+
+Magnetic media are written and erased using magnetic fields, and
+should be protected from such fields to avoid damage to stored data.
+Sticking a floppy disk to a filing cabinet using a magnet is probably
+not a good idea.
+
address@hidden
+* Device:: Device selection and switching
+* Remote Tape Server::
+* Common Problems and Solutions::
+* Blocking:: Blocking
+* Many:: Many archives on one tape
+* Using Multiple Tapes:: Using Multiple Tapes
+* label:: Including a Label in the Archive
+* verify::
+* Write Protection::
address@hidden menu
+
address@hidden Device
address@hidden Device Selection and Switching
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden @option
address@hidden -f address@hidden:address@hidden
address@hidden address@hidden:address@hidden
+Use archive file or device @var{file} on @var{hostname}.
address@hidden table
+
+This option is used to specify the file name of the archive @command{tar}
+works on.
+
+If the file name is @samp{-}, @command{tar} reads the archive from standard
+input (when listing or extracting), or writes it to standard output
+(when creating). If the @samp{-} file name is given when updating an
+archive, @command{tar} will read the original archive from its standard
+input, and will write the entire new archive to its standard output.
+
+If the file name contains a @samp{:}, it is interpreted as
address@hidden:file name}. If the @var{hostname} contains an @dfn{at}
+sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In
+either case, @command{tar} will invoke the command @command{rsh} (or
address@hidden) 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
address@hidden
+Naturally, the remote machine must have an executable
address@hidden/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 @address@hidden/libexec/rmt}, where @var{prefix} stands for
+your installation prefix. This location may also be overridden at
+runtime by using @address@hidden 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}
+used a default archive name (which was picked when @command{tar} was
+compiled). The default is normally set up to be the @dfn{first} tape
+drive or other transportable I/O medium on the system.
+
+Starting with version 1.11.5, @acronym{GNU} @command{tar} uses
+standard input and standard output as the default device, and I will
+not try anymore supporting automatic device detection at installation
+time. This was failing really in too many cases, it was hopeless.
+This is now completely left to the installer to override standard
+input and standard output for default device, if this seems
+preferable. Further, I think @emph{most} actual usages of
address@hidden are done with pipes or disks, not really tapes,
+cartridges or diskettes.
+
+Some users think that using standard input and output is running
+after trouble. This could lead to a nasty surprise on your screen if
+you forget to specify an output file name---especially if you are going
+through a network or terminal server capable of buffering large amounts
+of output. We had so many bug reports in that area of configuring
+default tapes automatically, and so many contradicting requests, that
+we finally consider the problem to be portably intractable. We could
+of course use something like @samp{/dev/tape} as a default, but this
+is @emph{also} running after various kind of trouble, going from hung
+processes to accidental destruction of real tapes. After having seen
+all this mess, using standard input and output as a default really
+sounds like the only clean choice left, and a very useful one too.
+
address@hidden @command{tar} reads and writes archive in records, I
+suspect this is the main reason why block devices are preferred over
+character devices. Most probably, block devices are more efficient
+too. The installer could also check for @samp{DEFTAPE} in
address@hidden<sys/mtio.h>}.
+
address@hidden @option
address@hidden address@hidden, short description}
address@hidden --force-local
+Archive file is local even if it contains a colon.
+
address@hidden rsh-command
address@hidden address@hidden
+Use remote @var{command} instead of @command{rsh}. This option exists
+so that people who use something other than the standard @command{rsh}
+(e.g., a Kerberized @command{rsh}) can access a remote device.
+
+When this command is not used, the shell command found when
+the @command{tar} program was installed is used instead. This is
+the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh},
address@hidden/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}.
+The installer may have overridden this by defining the environment
+variable @env{RSH} @emph{at installation time}.
+
address@hidden -[0-7][lmh]
+Specify drive and density.
+
address@hidden address@hidden, short description}
address@hidden -M
address@hidden --multi-volume
+Create/list/extract multi-volume archive.
+
+This option causes @command{tar} to write a @dfn{multi-volume} archive---one
+that may be larger than will fit on the medium used to hold it.
address@hidden Archives}.
+
address@hidden address@hidden, short description}
address@hidden -L @var{num}
address@hidden address@hidden
+Change tape after writing @var{num} x 1024 bytes.
+
+This option might be useful when your tape drivers do not properly
+detect end of physical tapes. By being slightly conservative on the
+maximum tape length, you might avoid the problem entirely.
+
address@hidden address@hidden, short description}
address@hidden address@hidden, short description}
address@hidden -F @var{file}
address@hidden address@hidden
address@hidden address@hidden
+Execute @file{file} at end of each tape. This implies
address@hidden (@option{-M}). @xref{info-script}, for a detailed
+description of this option.
address@hidden table
+
address@hidden Remote Tape Server
address@hidden The Remote Tape Server
+
address@hidden remote tape drive
address@hidden 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
address@hidden@var{prefix}/libexec/rmt} on any machine whose tape drive you
+want to use. @command{tar} calls @command{rmt} by running an
address@hidden or @command{remsh} to the remote machine, optionally
+using a different login name if one is supplied.
+
+A copy of the source for the remote tape server is provided. It is
+Copyright @copyright{} 1983 by the Regents of the University of
+California, but can be freely distributed. It is compiled and
+installed by default.
+
address@hidden absolute file names
+Unless you use the @option{--absolute-names} (@option{-P}) option,
address@hidden @command{tar} will not allow you to create an archive that
contains
+absolute file names (a file name beginning with @samp{/}.) If you try,
address@hidden will automatically remove the leading @samp{/} from the
+file names it stores in the archive. It will also type a warning
+message telling you what it is doing.
+
+When reading an archive that was created with a different
address@hidden program, @acronym{GNU} @command{tar} automatically
+extracts entries in the archive which have absolute file names as if
+the file names were not absolute. This is an important feature. A
+visitor here once gave a @command{tar} tape to an operator to restore;
+the operator used Sun @command{tar} instead of @acronym{GNU} @command{tar},
+and the result was that it replaced large portions of
+our @file{/bin} and friends with versions from the tape; needless to
+say, we were unhappy about having to recover the file system from
+backup tapes.
+
+For example, if the archive contained a file @file{/usr/bin/computoy},
address@hidden @command{tar} would extract the file to @file{usr/bin/computoy},
+relative to the current directory. If you want to extract the files in
+an archive to the same absolute names that they had when the archive
+was created, you should do a @samp{cd /} before extracting the files
+from the archive, or you should either use the @option{--absolute-names}
+option, or use the command @samp{tar -C / @dots{}}.
+
address@hidden Ultrix 3.1 and write failure
+Some versions of Unix (Ultrix 3.1 is known to have this problem),
+can claim that a short write near the end of a tape succeeded,
+when it actually failed. This will result in the -M option not
+working correctly. The best workaround at the moment is to use a
+significantly larger blocking factor than the default 20.
+
+In order to update an archive, @command{tar} must be able to backspace the
+archive in order to reread or rewrite a record that was just read (or
+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}.
+
+This means that the @option{--append}, @option{--concatenate}, and
address@hidden commands will not work on any other kind of file.
+Some media simply cannot be backspaced, which means these commands and
+options will never be able to work on them. These non-backspacing
+media include pipes and cartridge tape drives.
+
+Some other media can be backspaced, and @command{tar} will work on them
+once @command{tar} is modified to do so.
+
+Archives created with the @option{--multi-volume}, @option{--label}, and
address@hidden (@option{-G}) options may not be readable by other version
+of @command{tar}. In particular, restoring a file that was split over
+a volume boundary will require some careful work with @command{dd}, if
+it can be done at all. Other versions of @command{tar} may also create
+an empty file whose name is that of the volume header. Some versions
+of @command{tar} may create normal files instead of directories archived
+with the @option{--incremental} (@option{-G}) option.
+
address@hidden Common Problems and Solutions
address@hidden Some Common Problems and their Solutions
+
+
address@hidden
+errors from system:
+permission denied
+no such file or directory
+not owner
+
+errors from @command{tar}:
+directory checksum error
+header format error
+
+errors from media/system:
+i/o error
+device busy
address@hidden format
+
+
address@hidden Blocking
address@hidden Blocking
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden and @dfn{record} terminology is rather confused, and it
+is also confusing to the expert reader. On the other hand, readers
+who are new to the field have a fresh mind, and they may safely skip
+the next two paragraphs, as the remainder of this manual uses those
+two terms in a quite consistent way.
+
+John Gilmore, the writer of the public domain @command{tar} from which
address@hidden @command{tar} was originally derived, wrote (June 1995):
+
address@hidden
+The nomenclature of tape drives comes from IBM, where I believe
+they were invented for the IBM 650 or so. On IBM mainframes, what
+is recorded on tape are tape blocks. The logical organization of
+data is into records. There are various ways of putting records into
+blocks, including @code{F} (fixed sized records), @code{V} (variable
+sized records), @code{FB} (fixed blocked: fixed size records, @var{n}
+to a block), @code{VB} (variable size records, @var{n} to a block),
address@hidden (variable spanned blocked: variable sized records that can
+occupy more than one block), etc. The @code{JCL} @samp{DD RECFORM=}
+parameter specified this to the operating system.
+
+The Unix man page on @command{tar} was totally confused about this.
+When I wrote @code{PD TAR}, I used the historically correct terminology
+(@command{tar} writes data records, which are grouped into blocks).
+It appears that the bogus terminology made it into @acronym{POSIX} (no surprise
+here), and now Fran@,{c}ois has migrated that terminology back
+into the source code too.
address@hidden quotation
+
+The term @dfn{physical block} means the basic transfer chunk from or
+to a device, after which reading or writing may stop without anything
+being lost. In this manual, the term @dfn{block} usually refers to
+a disk physical block, @emph{assuming} that each disk block is 512
+bytes in length. It is true that some disk devices have different
+physical blocks, but @command{tar} ignore these differences in its own
+format, which is meant to be portable, so a @command{tar} block is always
+512 bytes in length, and @dfn{block} always mean a @command{tar} block.
+The term @dfn{logical block} often represents the basic chunk of
+allocation of many disk blocks as a single entity, which the operating
+system treats somewhat atomically; this concept is only barely used
+in @acronym{GNU} @command{tar}.
+
+The term @dfn{physical record} is another way to speak of a physical
+block, those two terms are somewhat interchangeable. In this manual,
+the term @dfn{record} usually refers to a tape physical block,
address@hidden that the @command{tar} archive is kept on magnetic tape.
+It is true that archives may be put on disk or used with pipes,
+but nevertheless, @command{tar} tries to read and write the archive one
address@hidden at a time, whatever the medium in use. One record is made
+up of an integral number of blocks, and this operation of putting many
+disk blocks into a single tape block is called @dfn{reblocking}, or
+more simply, @dfn{blocking}. The term @dfn{logical record} refers to
+the logical organization of many characters into something meaningful
+to the application. The term @dfn{unit record} describes a small set
+of characters which are transmitted whole to or by the application,
+and often refers to a line of text. Those two last terms are unrelated
+to what we call a @dfn{record} in @acronym{GNU} @command{tar}.
+
+When writing to tapes, @command{tar} writes the contents of the archive
+in chunks known as @dfn{records}. To change the default blocking
+factor, use the @address@hidden (@option{-b
address@hidden) option. Each record will then be composed of
address@hidden blocks. (Each @command{tar} block is 512 bytes.
address@hidden) Each file written to the archive uses at least one
+full record. As a result, using a larger record size can result in
+more wasted space for small files. On the other hand, a larger record
+size can often be read and written much more efficiently.
+
+Further complicating the problem is that some tape drives ignore the
+blocking entirely. For these, a larger record size can still improve
+performance (because the software layers above the tape drive still
+honor the blocking), but not as dramatically as on tape drives that
+honor blocking.
+
+When reading an archive, @command{tar} can usually figure out the
+record size on itself. When this is the case, and a non-standard
+record size was used when the archive was created, @command{tar} will
+print a message about a non-standard blocking factor, and then operate
+normally. On some tape devices, however, @command{tar} cannot figure
+out the record size itself. On most of those, you can specify a
+blocking factor (with @option{--blocking-factor}) larger than the
+actual blocking factor, and then use the @option{--read-full-records}
+(@option{-B}) option. (If you specify a blocking factor with
address@hidden and don't use the
address@hidden option, then @command{tar} will not
+attempt to figure out the recording size itself.) On some devices,
+you must always specify the record size exactly with
address@hidden when reading, because @command{tar} cannot
+figure it out. In any case, use @option{--list} (@option{-t}) before
+doing any extractions to see whether @command{tar} is reading the archive
+correctly.
+
address@hidden blocks are all fixed size (512 bytes), and its scheme for
+putting them into records is to put a whole number of them (one or
+more) into each record. @command{tar} records are all the same size;
+at the end of the file there's a block containing all zeros, which
+is how you tell that the remainder of the last record(s) are garbage.
+
+In a standard @command{tar} file (no options), the block size is 512
+and the record size is 10240, for a blocking factor of 20. What the
address@hidden option does is sets the blocking factor,
+changing the record size while leaving the block size at 512 bytes.
+20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives;
+most tape drives these days prefer much bigger records in order to
+stream and not waste tape. When writing tapes for myself, some tend
+to use a factor of the order of 2048, say, giving a record size of
+around one megabyte.
+
+If you use a blocking factor larger than 20, older @command{tar}
+programs might not be able to read the archive, so we recommend this
+as a limit to use in practice. @acronym{GNU} @command{tar}, however,
+will support arbitrarily large record sizes, limited only by the
+amount of virtual memory or the physical characteristics of the tape
+device.
+
address@hidden
+* Format Variations:: Format Variations
+* Blocking Factor:: The Blocking Factor of an Archive
address@hidden menu
+
address@hidden Format Variations
address@hidden Format Variations
address@hidden Format Parameters
address@hidden Format Options
address@hidden Options, archive format specifying
address@hidden Options, format specifying
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Format parameters specify how an archive is written on the archive
+media. The best choice of format parameters will vary depending on
+the type and number of files being archived, and on the media used to
+store the archive.
+
+To specify format parameters when accessing or creating an archive,
+you can use the options described in the following sections.
+If you do not specify any format parameters, @command{tar} uses
+default parameters. You cannot modify a compressed archive.
+If you create an archive with the @option{--blocking-factor} option
+specified (@pxref{Blocking Factor}), you must specify that
+blocking-factor when operating on the archive. @xref{Formats}, for other
+examples of format parameter considerations.
+
address@hidden Blocking Factor
address@hidden The Blocking Factor of an Archive
address@hidden Blocking Factor
address@hidden Record Size
address@hidden Number of blocks per record
address@hidden Number of bytes per record
address@hidden Bytes per record
address@hidden Blocks per record
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden blocking-factor
+The data in an archive is grouped into blocks, which are 512 bytes.
+Blocks are read and written in whole number multiples called
address@hidden The number of blocks in a record (i.e. the size of a
+record in units of 512 bytes) is called the @dfn{blocking factor}.
+The @address@hidden (@option{-b
address@hidden) option specifies the blocking factor of an archive.
+The default blocking factor is typically 20 (i.e., 10240 bytes), but
+can be specified at installation. To find out the blocking factor of
+an existing archive, use @samp{tar --list address@hidden
+This may not work on some devices.
+
+Records are separated by gaps, which waste space on the archive media.
+If you are archiving on magnetic tape, using a larger blocking factor
+(and therefore larger records) provides faster throughput and allows you
+to fit more data on a tape (because there are fewer gaps). If you are
+archiving on cartridge, a very large blocking factor (say 126 or more)
+greatly increases performance. A smaller blocking factor, on the other
+hand, may be useful when archiving small files, to avoid archiving lots
+of nulls as @command{tar} fills out the archive to the end of the record.
+In general, the ideal record size depends on the size of the
+inter-record gaps on the tape you are using, and the average size of the
+files you are archiving. @xref{create}, for information on
+writing archives.
+
address@hidden
address@hidden
+
+
+Archives with blocking factors larger than 20 cannot be read
+by very old versions of @command{tar}, or by some newer versions
+of @command{tar} running on old machines with small address spaces.
+With @acronym{GNU} @command{tar}, the blocking factor of an archive is limited
+only by the maximum record size of the device containing the archive,
+or by the amount of available virtual memory.
+
+Also, on some systems, not using adequate blocking factors, as sometimes
+imposed by the device drivers, may yield unexpected diagnostics. For
+example, this has been reported:
+
address@hidden
+Cannot write to /dev/dlt: Invalid argument
address@hidden smallexample
+
address@hidden
+In such cases, it sometimes happen that the @command{tar} bundled by
+the system is aware of block size idiosyncrasies, while @acronym{GNU}
@command{tar}
+requires an explicit specification for the block size,
+which it cannot guess. This yields some people to consider
address@hidden @command{tar} is misbehaving, because by comparison,
address@hidden bundle @command{tar} works OK}. Adding @address@hidden 256}},
+for example, might resolve the problem.
+
+If you use a non-default blocking factor when you create an archive, you
+must specify the same blocking factor when you modify that archive. Some
+archive devices will also require you to specify the blocking factor when
+reading that archive, however this is not typically the case. Usually, you
+can use @option{--list} (@option{-t}) without specifying a blocking
address@hidden
+reports a non-default record size and then lists the archive members as
+it would normally. To extract files from an archive with a non-standard
+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}.
address@hidden, for more information on the @option{--list} (@option{-t})
+operation. @xref{Reading}, for a more detailed explanation of that option.
+
address@hidden @option
address@hidden address@hidden
address@hidden -b @var{number}
+Specifies the blocking factor of an archive. Can be used with any
+operation, but is usually not necessary with @option{--list} (@option{-t}).
address@hidden table
+
+Device blocking
+
address@hidden @option
address@hidden -b @var{blocks}
address@hidden address@hidden
+Set record size to @address@hidden * 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
+of the archive in records of @address@hidden bytes. This is true
+even when the archive is compressed. Some devices requires that all
+write operations be a multiple of a certain size, and so, @command{tar}
+pads the archive out to the next record boundary.
+
+The default blocking factor is set when @command{tar} is compiled, and is
+typically 20. Blocking factors larger than 20 cannot be read by very
+old versions of @command{tar}, or by some newer versions of @command{tar}
+running on old machines with small address spaces.
+
+With a magnetic tape, larger records give faster throughput and fit
+more data on a tape (because there are fewer inter-record gaps).
+If the archive is in a disk file or a pipe, you may want to specify
+a smaller blocking factor, since a large one will result in a large
+number of null bytes at the end of the archive.
+
+When writing cartridge or other streaming tapes, a much larger
+blocking factor (say 126 or more) will greatly increase performance.
+However, you must specify the same blocking factor when reading or
+updating the archive.
+
+Apparently, Exabyte drives have a physical block size of 8K bytes.
+If we choose our blocksize as a multiple of 8k bytes, then the problem
+seems to disappear. Id est, we are using block size of 112 right
+now, and we haven't had the problem since we address@hidden
+
+With @acronym{GNU} @command{tar} the blocking factor is limited only
+by the maximum record size of the device containing the archive, or by
+the amount of available virtual memory.
+
+However, deblocking or reblocking is virtually avoided in a special
+case which often occurs in practice, but which requires all the
+following conditions to be simultaneously true:
address@hidden @bullet
address@hidden
+the archive is subject to a compression option,
address@hidden
+the archive is not handled through standard input or output, nor
+redirected nor piped,
address@hidden
+the archive is directly handled to a local disk, instead of any special
+device,
address@hidden
address@hidden is not explicitly specified on the @command{tar}
+invocation.
address@hidden itemize
+
+If the output goes directly to a local disk, and not through
+stdout, then the last write is not extended to a full record size.
+Otherwise, reblocking occurs. Here are a few other remarks on this
+topic:
+
address@hidden @bullet
+
address@hidden
address@hidden will complain about trailing garbage if asked to
+uncompress a compressed archive on tape, there is an option to turn
+the message off, but it breaks the regularity of simply having to use
address@hidden@var{prog} -d} for decompression. It would be nice if gzip was
+silently ignoring any number of trailing zeros. I'll ask Jean-loup
+Gailly, by sending a copy of this message to him.
+
address@hidden
address@hidden does not show this problem, but as Jean-loup pointed
+out to Michael, @samp{compress -d} silently adds garbage after
+the result of decompression, which tar ignores because it already
+recognized its end-of-file indicator. So this bug may be safely
+ignored.
+
address@hidden
address@hidden -d -q} will be silent about the trailing zeros indeed,
+but will still return an exit status of 2 which tar reports in turn.
address@hidden might ignore the exit status returned, but I hate doing
+that, as it weakens the protection @command{tar} offers users against
+other possible problems at decompression time. If @command{gzip} was
+silently skipping trailing zeros @emph{and} also avoiding setting the
+exit status in this innocuous case, that would solve this situation.
+
address@hidden
address@hidden should become more solid at not stopping to read a pipe at
+the first null block encountered. This inelegantly breaks the pipe.
address@hidden should rather drain the pipe out before exiting itself.
address@hidden itemize
+
address@hidden address@hidden, short description}
address@hidden -i
address@hidden --ignore-zeros
+Ignore blocks of zeros in archive (means EOF).
+
+The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to
ignore blocks
+of zeros in the archive. Normally a block of zeros indicates the
+end of the archive, but when reading a damaged archive, or one which
+was created by concatenating several archives together, this option
+allows @command{tar} to read the entire archive. This option is not on
+by default because many versions of @command{tar} write garbage after
+the zeroed blocks.
+
+Note that this option causes @command{tar} to read to the end of the
+archive file, which may sometimes avoid problems when multiple files
+are stored on a single physical tape.
+
address@hidden address@hidden, short description}
address@hidden -B
address@hidden --read-full-records
+Reblock as we read (for reading 4.2BSD pipes).
+
+If @option{--read-full-records} is used, @command{tar}
+will not panic if an attempt to read a record from the archive does
+not return a full record. Instead, @command{tar} will keep reading
+until it has obtained a full
+record.
+
+This option is turned on by default when @command{tar} is reading
+an archive from standard input, or from a remote machine. This is
+because on BSD Unix systems, a read of a pipe will return however
+much happens to be in the pipe, even if it is less than @command{tar}
+requested. If this option was not used, @command{tar} would fail as
+soon as it read an incomplete record from the pipe.
+
+This option is also useful with the commands for updating an archive.
+
address@hidden table
+
+Tape blocking
+
address@hidden
address@hidden
+
+
address@hidden blocking factor
address@hidden tape blocking
+
+When handling various tapes or cartridges, you have to take care of
+selecting a proper blocking, that is, the number of disk blocks you
+put together as a single tape block on the tape, without intervening
+tape gaps. A @dfn{tape gap} is a small landing area on the tape
+with no information on it, used for decelerating the tape to a
+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.
+
address@hidden Exabyte blocking
address@hidden DAT blocking
+Using higher blocking (putting more disk blocks per tape block) will use
+the tape more efficiently as there will be less tape gaps. But reading
+such tapes may be more difficult for the system, as more memory will be
+required to receive at once the whole record. Further, if there is a
+reading error on a huge record, this is less likely that the system will
+succeed in recovering the information. So, blocking should not be too
+low, nor it should be too high. @command{tar} uses by default a blocking of
+20 for historical reasons, and it does not really matter when reading or
+writing to disk. Current tape technology would easily accommodate higher
+blockings. Sun recommends a blocking of 126 for Exabytes and 96 for DATs.
+We were told that for some DLT drives, the blocking should be a multiple
+of 4Kb, preferably 64Kb (@address@hidden 128}}) or 256 for decent performance.
+Other manufacturers may use different recommendations for the same tapes.
+This might also depends of the buffering techniques used inside modern
+tape controllers. Some imposes a minimum blocking, or a maximum blocking.
+Others request blocking to be some exponent of two.
+
+So, there is no fixed rule for blocking. But blocking at read time
+should ideally be the same as blocking used at write time. At one place
+I know, with a wide variety of equipment, they found it best to use a
+blocking of 32 to guarantee that their tapes are fully interchangeable.
+
+I was also told that, for recycled tapes, prior erasure (by the same
+drive unit that will be used to create the archives) sometimes lowers
+the error rates observed at rewriting time.
+
+I might also use @option{--number-blocks} instead of
address@hidden, so @option{--block} will then expand to
address@hidden unambiguously.
+
address@hidden Many
address@hidden Many Archives on One Tape
+
address@hidden
address@hidden
+
+
address@hidden ntape @r{device}
+Most tape devices have two entries in the @file{/dev} directory, or
+entries that come in pairs, which differ only in the minor number for
+this device. Let's take for example @file{/dev/tape}, which often
+points to the only or usual tape device of a given system. There might
+be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}. The simpler
+name is the @emph{rewinding} version of the device, while the name
+having @samp{nr} in it is the @emph{no rewinding} version of the same
+device.
+
+A rewinding tape device will bring back the tape to its beginning point
+automatically when this device is opened or closed. Since @command{tar}
+opens the archive file before using it and closes it afterwards, this
+means that a simple:
+
address@hidden
+$ @kbd{tar cf /dev/tape @var{directory}}
address@hidden smallexample
+
address@hidden
+will reposition the tape to its beginning both prior and after saving
address@hidden contents to it, thus erasing prior tape contents and
+making it so that any subsequent write operation will destroy what has
+just been saved.
+
address@hidden tape positioning
+So, a rewinding device is normally meant to hold one and only one file.
+If you want to put more than one @command{tar} archive on a given tape, you
+will need to avoid using the rewinding version of the tape device. You
+will also have to pay special attention to tape positioning. Errors in
+positioning may overwrite the valuable data already on your tape. Many
+people, burnt by past experiences, will only use rewinding devices and
+limit themselves to one file per tape, precisely to avoid the risk of
+such errors. Be fully aware that writing at the wrong position on a
+tape loses all information past this point and most probably until the
+end of the tape, and this destroyed information @emph{cannot} be
+recovered.
+
+To save @var{directory-1} as a first archive at the beginning of a
+tape, and leave that tape ready for a second archive, you should use:
+
address@hidden
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{tar cf /dev/nrtape @var{directory-1}}
address@hidden smallexample
+
address@hidden tape marks
address@hidden marks} are special magnetic patterns written on the tape
+media, which are later recognizable by the reading hardware. These
+marks are used after each file, when there are many on a single tape.
+An empty file (that is to say, two tape marks in a row) signal the
+logical end of the tape, after which no file exist. Usually,
+non-rewinding tape device drivers will react to the close request issued
+by @command{tar} by first writing two tape marks after your archive, and by
+backspacing over one of these. So, if you remove the tape at that time
+from the tape drive, it is properly terminated. But if you write
+another file at the current position, the second tape mark will be
+erased by the new information, leaving only one tape mark between files.
+
+So, you may now save @var{directory-2} as a second archive after the
+first on the same tape by issuing the command:
+
address@hidden
+$ @kbd{tar cf /dev/nrtape @var{directory-2}}
address@hidden smallexample
+
address@hidden
+and so on for all the archives you want to put on the same tape.
+
+Another usual case is that you do not write all the archives the same
+day, and you need to remove and store the tape between two archive
+sessions. In general, you must remember how many files are already
+saved on your tape. Suppose your tape already has 16 files on it, and
+that you are ready to write the 17th. You have to take care of skipping
+the first 16 tape marks before saving @var{directory-17}, say, by using
+these commands:
+
address@hidden
+$ @kbd{mt -f /dev/nrtape rewind}
+$ @kbd{mt -f /dev/nrtape fsf 16}
+$ @kbd{tar cf /dev/nrtape @var{directory-17}}
address@hidden smallexample
+
+In all the previous examples, we put aside blocking considerations, but
+you should do the proper things for that as well. @xref{Blocking}.
+
address@hidden
+* Tape Positioning:: Tape Positions and Tape Marks
+* mt:: The @command{mt} Utility
address@hidden menu
+
address@hidden Tape Positioning
address@hidden Tape Positions and Tape Marks
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+Just as archives can store more than one file from the file system,
+tapes can store more than one archive file. To keep track of where
+archive files (or any other type of file stored on tape) begin and
+end, tape archive devices write magnetic @dfn{tape marks} on the
+archive media. Tape drives write one tape mark between files,
+two at the end of all the file entries.
+
+If you think of data as a series of records "rrrr"'s, and tape marks as
+"*"'s, a tape might look like the following:
+
address@hidden
+rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
address@hidden smallexample
+
+Tape devices read and write tapes using a read/write @dfn{tape
+head}---a physical part of the device which can only access one
+point on the tape at a time. When you use @command{tar} to read or
+write archive data from a tape device, the device will begin reading
+or writing from wherever on the tape the tape head happens to be,
+regardless of which archive or what part of the archive the tape
+head is on. Before writing an archive, you should make sure that no
+data on the tape will be overwritten (unless it is no longer needed).
+Before reading an archive, you should make sure the tape head is at
+the beginning of the archive you want to read. You can do it manually
+via @code{mt} utility (@pxref{mt}). The @code{restore} script does
+that automatically (@pxref{Scripted Restoration}).
+
+If you want to add new archive file entries to a tape, you should
+advance the tape to the end of the existing file entries, backspace
+over the last tape mark, and write the new archive file. If you were
+to add two archives to the example above, the tape might look like the
+following:
+
address@hidden
+rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
address@hidden smallexample
+
address@hidden mt
address@hidden The @command{mt} Utility
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden
address@hidden
+
address@hidden Factor}.
+
+You can use the @command{mt} utility to advance or rewind a tape past a
+specified number of archive files on the tape. This will allow you
+to move to the beginning of an archive before extracting or reading
+it, or to the end of all the archives before writing a new one.
address@hidden
address@hidden
+
+
+The syntax of the @command{mt} command is:
+
address@hidden
address@hidden [-f @var{tapename}] @var{operation} address@hidden
address@hidden smallexample
+
+where @var{tapename} is the name of the tape device, @var{number} is
+the number of times an operation is performed (with a default of one),
+and @var{operation} is one of the following:
+
address@hidden
address@hidden
+
+
address@hidden @option
address@hidden eof
address@hidden weof
+Writes @var{number} tape marks at the current position on the tape.
+
address@hidden fsf
+Moves tape position forward @var{number} files.
+
address@hidden bsf
+Moves tape position back @var{number} files.
+
address@hidden rewind
+Rewinds the tape. (Ignores @var{number}).
+
address@hidden offline
address@hidden rewoff1
+Rewinds the tape and takes the tape device off-line. (Ignores @var{number}).
+
address@hidden status
+Prints status information about the tape unit.
+
address@hidden table
+
address@hidden
address@hidden
+
+
+If you don't specify a @var{tapename}, @command{mt} uses the environment
+variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
+the default device specified in your @file{sys/mtio.h} file
+(@code{DEFTAPE} variable). If this is not defined, the program will
+display a descriptive error message and exit with code 1.
+
address@hidden returns a 0 exit status when the operation(s) were
+successful, 1 if the command was unrecognized, and 2 if an operation
+failed.
+
address@hidden Using Multiple Tapes
address@hidden Using Multiple Tapes
+
+Often you might want to write a large archive, one larger than will fit
+on the actual tape you are using. In such a case, you can run multiple
address@hidden commands, but this can be inconvenient, particularly if you
+are using options like @address@hidden or dumping entire file systems.
+Therefore, @command{tar} provides a special mode for creating
+multi-volume archives.
+
address@hidden archive is a single @command{tar} archive, stored
+on several media volumes of fixed size. Although in this section we will
+often call @samp{volume} a @dfn{tape}, there is absolutely no
+requirement for multi-volume archives to be stored on tapes. Instead,
+they can use whatever media type the user finds convenient, they can
+even be located on files.
+
+When creating a multi-volume arvhive, @acronym{GNU} @command{tar} continues to
fill
+current volume until it runs out of space, then it switches to
+next volume (usually the operator is queried to replace the tape on
+this point), and continues working on the new volume. This operation
+continues untill all requested files are dumped. If @acronym{GNU}
@command{tar} detects
+end of media while dumping a file, such a file is archived in split
+form. Some very big files can even be split across several volumes.
+
+Each volume is itself a valid @acronym{GNU} @command{tar} archive, so it can
be read
+without any special options. Consequently any file member residing
+entirely on one volume can be extracted or otherwise operated upon
+without needing the other volume. Sure enough, to extract a split
+member you would need all volumes its parts reside on.
+
+Multi-volume archives suffer from several limitations. In particular,
+they cannot be compressed.
+
address@hidden @command{tar} is able to create multi-volume archives of two
formats
+(@pxref{Formats}): @samp{GNU} and @samp{POSIX}.
+
address@hidden
+* Multi-Volume Archives:: Archives Longer than One Tape or Disk
+* Tape Files:: Tape Files
+* Tarcat:: Concatenate Volumes into a Single Archive
+
address@hidden menu
+
address@hidden Multi-Volume Archives
address@hidden Archives Longer than One Tape or Disk
address@hidden Multi-volume archives
+
address@hidden multi-volume
+To create an archive that is larger than will fit on a single unit of
+the media, use the @option{--multi-volume} (@option{-M}) option in conjunction
with
+the @option{--create} option (@pxref{create}). A @dfn{multi-volume}
+archive can be manipulated like any other archive (provided the
address@hidden option is specified), but is stored on more
+than one tape or disk.
+
+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
+the end of the media (when writing). Instead, it prompts you to load
+a new storage volume. If the archive is on a magnetic tape, you
+should change tapes when you see the prompt; if the archive is on a
+floppy disk, you should change disks; etc.
+
address@hidden @option
address@hidden --multi-volume
address@hidden -M
+Creates a multi-volume archive, when used in conjunction with
address@hidden (@option{-c}). To perform any other operation on a multi-volume
+archive, specify @option{--multi-volume} in conjunction with that
+operation.
+For example:
+
address@hidden
+$ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}}
address@hidden smallexample
address@hidden table
+
+The method @command{tar} uses to detect end of tape is not perfect, and
+fails on some operating systems or on some devices. If @command{tar}
+cannot detect the end of the tape itself, you can use
address@hidden option to inform it about the capacity of the
+tape:
+
address@hidden
address@hidden @option
address@hidden tape-length
address@hidden address@hidden
address@hidden -L @var{size}
+Set maximum length of a volume. The @var{size} argument should then
+be the usable size of the tape in units of 1024 bytes. This option
+selects @option{--multi-volume} automatically. For example:
+
address@hidden
+$ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}}
address@hidden smallexample
address@hidden table
+
address@hidden volume prompt}
+When @acronym{GNU} @command{tar} comes to the end of a storage media, it asks
you to
+change the volume. The built-in prompt for POSIX locale
address@hidden you run @acronym{GNU} @command{tar} under a different locale, the
+translation to the locale's language will be used.}:
+
address@hidden
+Prepare volume address@hidden for address@hidden' and hit return:
address@hidden smallexample
+
address@hidden
+where @var{n} is the ordinal number of the volume to be created and
address@hidden is archive file or device name.
+
+When prompting for a new tape, @command{tar} accepts any of the following
+responses:
+
address@hidden @kbd
address@hidden ?
+Request @command{tar} to explain possible responses
address@hidden q
+Request @command{tar} to exit immediately.
address@hidden n @var{file-name}
+Request @command{tar} to write the next volume on the file @var{file-name}.
address@hidden !
+Request @command{tar} to run a subshell. This option can be disabled
+by giving @option{--restrict} command line option to
address@hidden@address@hidden, for more information about
+this option}.
address@hidden y
+Request @command{tar} to begin writing the next volume.
address@hidden table
+
+(You should only type @samp{y} after you have changed the tape;
+otherwise @command{tar} will write over the volume it just finished.)
+
address@hidden Volume number file
address@hidden volno file
address@hidden
address@hidden volno-file
+The volume number used by @command{tar} in its tape-changing prompt
+can be changed; if you give the
address@hidden@var{file-of-number}} option, then
address@hidden should be an unexisting file to be created, or
+else, a file already containing a decimal number. That number will be
+used as the volume number of the first volume written. When
address@hidden is finished, it will rewrite the file with the
+now-current volume number. (This does not change the volume number
+written on a tape label, as per @ref{label}, it @emph{only} affects
+the number used in the prompt.)
+
address@hidden End-of-archive info script
address@hidden Info script
address@hidden
address@hidden info-script
address@hidden new-volume-script
+If you want more elaborate behavior than this, you can write a special
address@hidden volume script}, that will be responsible for changing the
+volume, and instruct @command{tar} to use it instead of its normal
+prompting procedure:
+
address@hidden @option
address@hidden address@hidden
address@hidden address@hidden
address@hidden -F @var{script-name}
+Specify the full name of the volume script to use. The script can be
+used to eject cassettes, or to broadcast messages such as
address@hidden please come change my tape} when performing unattended
+backups.
address@hidden table
+
+The @var{script-name} is executed without any command line
+arguments. It inherits @command{tar}'s shell environment.
+Additional data is passed to it via the following
+environment variables:
+
address@hidden @env
address@hidden TAR_VERSION, info script environment variable
address@hidden TAR_VERSION
address@hidden @command{tar} version number.
+
address@hidden TAR_ARCHIVE, info script environment variable
address@hidden TAR_ARCHIVE
+The name of the archive @command{tar} is processing.
+
address@hidden TAR_VOLUME, info script environment variable
address@hidden TAR_VOLUME
+Ordinal number of the volume @command{tar} is about to start.
+
address@hidden TAR_SUBCOMMAND, info script environment variable
address@hidden TAR_SUBCOMMAND
+Short option describing the operation @command{tar} is executing
address@hidden, for a complete list of subcommand options.
+
address@hidden TAR_FORMAT, info script environment variable
address@hidden TAR_FORMAT
+Format of the archive being processed. @xref{Formats}, for a complete
+list of archive format names.
address@hidden table
+
+The volume script can instruct @command{tar} to use new archive name,
+by writing in to file descriptor 3 (see below for an example).
+
+If the info script fails, @command{tar} exits; otherwise, it begins
+writing the next volume.
+
+If you want @command{tar} to cycle through a series of files or tape
+drives, there are three approaches to choose from. First of all, you
+can give @command{tar} multiple @option{--file} options. In this case
+the specified files will be used, in sequence, as the successive
+volumes of the archive. Only when the first one in the sequence needs
+to be used again will @command{tar} prompt for a tape change (or run
+the info script). For example, suppose someone has two tape drives on
+a system named @file{/dev/tape0} and @file{/dev/tape1}. For having
address@hidden @command{tar} to switch to the second drive when it needs to
write the
+second tape, and then back to the first tape, etc., just do either of:
+
address@hidden
+$ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1
@var{files}}
+$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
address@hidden smallexample
+
+The second method is to use the @samp{n} response to the tape-change
+prompt.
+
+Finally, the most flexible approach is to use a volume script, that
+writes new archive name to the file descriptor #3. For example, the
+following volume script will create a series of archive files, named
address@hidden@address@hidden, where @var{archive} is the name of the
+archive being created (as given by @option{--file} option) and
address@hidden is the ordinal number of the archive being created:
+
address@hidden
address@hidden
+#! /bin/sh
+echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+
+name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+case $TAR_SUBCOMMAND in
+-c) ;;
+-d|-x|-t) test -r address@hidden:address@hidden || exit 1
+ ;;
+*) exit 1
+esac
+
+echo address@hidden:address@hidden >&3
address@hidden group
address@hidden smallexample
+
+The same script cant be used while listing, comparing or extracting
+from the created archive. For example:
+
address@hidden
address@hidden
+# @r{Create a multi-volume archive:}
+$ @kbd{tar -c -L1024 -f archive.tar -F new-volume .}
+# @r{Extract from the created archive:}
+$ @kbd{tar -x -f archive.tar -F new-volume .}
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that the first command had to use @option{-L} option, since
+otherwise @acronym{GNU} @command{tar} will end up writing everything to file
address@hidden
+
+You can read each individual volume of a multi-volume archive as if it
+were an archive by itself. For example, to list the contents of one
+volume, use @option{--list}, without @option{--multi-volume} specified.
+To extract an archive member from one volume (assuming it is described
+that volume), use @option{--extract}, again without
address@hidden
+
+If an archive member is split across volumes (i.e. its entry begins on
+one volume of the media and ends on another), you need to specify
address@hidden to extract it successfully. In this case, you
+should load the volume where the archive member starts, and use
address@hidden --extract address@hidden will prompt for later
+volumes as it needs them. @xref{extracting archives}, for more
+information about extracting archives.
+
+Multi-volume archives can be modified like any other archive. To add
+files to a multi-volume archive, you need to only mount the last
+volume of the archive media (and new volumes, if needed). For all
+other operations, you need to use the entire archive.
+
+If a multi-volume archive was labeled using
address@hidden@var{archive-label}} (@pxref{label}) when it was
+created, @command{tar} will not automatically label volumes which are
+added later. To label subsequent volumes, specify
address@hidden@var{archive-label}} again in conjunction with the
address@hidden, @option{--update} or @option{--concatenate} operation.
+
+Notice that multi-volume support is a GNU extension and the archives
+created in this mode should be read only using @acronym{GNU} @command{tar}.
If you
+absolutely have to process such archives using a third-party @command{tar}
+implementation, read @ref{Split Recovery}.
+
address@hidden Tape Files
address@hidden Tape Files
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+To give the archive a name which will be recorded in it, use the
address@hidden@var{volume-label}} (@option{-V @var{volume-label}})
+option. This will write a special block identifying
address@hidden as the name of the archive to the front of the
+archive which will be displayed when the archive is listed with
address@hidden If you are creating a multi-volume archive with
address@hidden (@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 @address@hidden) option when
+reading an archive, it checks to make sure the label on the tape
+matches the one you give. @xref{label}.
+
+When @command{tar} writes an archive to tape, it creates a single
+tape file. If multiple archives are written to the same tape, one
+after the other, they each get written as separate tape files. When
+extracting, it is necessary to position the tape at the right place
+before running @command{tar}. To do this, use the @command{mt} command.
+For more information on the @command{mt} command and on the organization
+of tapes into a sequence of tape files, see @ref{mt}.
+
+People seem to often do:
+
address@hidden
address@hidden"@var{some-prefix} `date address@hidden"}
address@hidden smallexample
+
+or such, for pushing a common date in all volumes or an archive set.
+
address@hidden Tarcat
address@hidden Concatenate Volumes into a Single Archive
+
address@hidden tarcat
+ Sometimes it is necessary to convert existing @acronym{GNU} @command{tar}
multi-volume
+archive to a single @command{tar} archive. Simply concatenating all
+volumes into one will not work, since each volume carries an additional
+information at the beginning. @acronym{GNU} @command{tar} is shipped with the
shell
+script @command{tarcat} designed for this purpose.
+
+ The script takes a list of files comprising a multi-volume archive
+and creates the resulting archive at the standard output. For example:
+
address@hidden
address@hidden vol.1 vol.2 vol.3 | tar tf -}
address@hidden smallexample
+
+ The script implements a simple heuristics to determine the format of
+the first volume file and to decide how to process the rest of the
+files. However, it makes no attempt to verify whether the files are
+given in order or even if they are valid @command{tar} archives.
+It uses @command{dd} and does not filter its standard error, so you
+will usually see lots of spurious messages.
+
address@hidden
address@hidden
+
+
address@hidden label
address@hidden Including a Label in the Archive
address@hidden Labeling an archive
address@hidden Labels on the archive media
address@hidden Labeling multi-volume archives
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
address@hidden label
+ To avoid problems caused by misplaced paper labels on the archive
+media, you can include a @dfn{label} entry---an archive member which
+contains the name of the archive---in the archive itself. Use the
address@hidden@var{archive-label}} (@option{-V @var{archive-label}})
+option in conjunction with the @option{--create} operation to include
+a label entry in the archive as it is being created.
+
address@hidden @option
address@hidden address@hidden
address@hidden -V @var{archive-label}
+Includes an @dfn{archive-label} at the beginning of the archive when
+the archive is being created, when used in conjunction with the
address@hidden operation. Checks to make sure the archive label
+matches the one specified (when used in conjunction with any other
+operation.
address@hidden table
+
+ If you create an archive using both
address@hidden@var{archive-label}} (@option{-V @var{archive-label}})
+and @option{--multi-volume} (@option{-M}), each volume of the archive
+will have an archive label of the form @address@hidden
+Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
+next, and so on. @xref{Using Multiple Tapes}, for information on
+creating multiple volume archives.
+
address@hidden Volume label, listing
address@hidden Listing volume label
+ The volume label will be displayed by @option{--list} along with
+the file contents. If verbose display is requested, it will also be
+explicitely marked as in the example below:
+
address@hidden
address@hidden
+$ @kbd{tar --verbose --list --file=iamanarchive}
+V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
address@hidden group
address@hidden smallexample
+
address@hidden test-label
address@hidden option}
+ However, @option{--list} option will cause listing entire
+contents of the archive, which may be undesirable (for example, if the
+archive is stored on a tape). You can request checking only the volume
+by specifying @option{--test-label} option. This option reads only the
+first block of an archive, so it can be used with slow storage
+devices. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --test-label --file=iamanarchive}
+iamalabel
address@hidden group
address@hidden smallexample
+
+ If @option{--test-label} is used with a single command line
+argument, @command{tar} compares the volume label with the
+argument. It exits with code 0 if the two strings match, and with code
+2 otherwise. In this case no output is displayed. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
address@hidden 0
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
address@hidden 1
address@hidden group
address@hidden smallexample
+
+ If you request any operation, other than @option{--create}, along
+with using @option{--label} option, @command{tar} will first check if
+the archive label matches the one specified and will refuse to proceed
+if it does not. Use this as a safety precaution to avoid accidentally
+overwriting existing archives. For example, if you wish to add files
+to @file{archive}, presumably labelled with string @samp{My volume},
+you will get:
+
address@hidden
address@hidden
+$ @kbd{tar -rf archive --label 'My volume' .}
+tar: Archive not labeled to match `My volume'
address@hidden group
address@hidden smallexample
+
address@hidden
+in case its label does not match. This will work even if
address@hidden is not labelled at all.
+
+ Similarly, @command{tar} will refuse to list or extract the
+archive if its label doesn't match the @var{archive-label}
+specified. In those cases, @var{archive-label} argument is interpreted
+as a globbing-style pattern which must match the actual magnetic
+volume label. @xref{exclude}, for a precise description of how match
+is address@hidden versions of @command{tar} used full
+regular expression matching, or before that, only exact string
+matching, instead of wildcard matchers. We decided for the sake of
+simplicity to use a uniform matching device through
address@hidden If the switch @option{--multi-volume} (@option{-M}) is being
used,
+the volume label matcher will also suffix @var{archive-label} by
address@hidden@samp{ Volume [1-9]*}} if the initial match fails, before giving
+up. Since the volume numbering is automatically added in labels at
+creation time, it sounded logical to equally help the user taking care
+of it when the archive is being read.
+
+ The @option{--label} was once called @option{--volume}, but is not
+available under that name anymore.
+
+ You can also use @option{--label} to get a common information on
+all tapes of a series. For having this information different in each
+series created through a single script used on a regular basis, just
+manage to get some date string as part of the label. For example:
+
address@hidden
address@hidden
+$ @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`"}
address@hidden group
address@hidden smallexample
+
+ Also note that each label has its own date and time, which corresponds
+to when @acronym{GNU} @command{tar} initially attempted to write it,
+often soon after the operator launches @command{tar} or types the
+carriage return telling that the next tape is ready. Comparing date
+labels does give an idea of tape throughput only if the delays for
+rewinding tapes and the operator switching them were negligible, which
+is usually not the case.
+
address@hidden verify
address@hidden Verifying Data as It is Stored
address@hidden Verifying a write operation
address@hidden Double-checking a write operation
+
address@hidden @option
address@hidden -W
address@hidden --verify
address@hidden verify, short description
+Attempt to verify the archive after writing.
address@hidden table
+
+This option causes @command{tar} to verify the archive after writing it.
+Each volume is checked after it is written, and any discrepancies
+are recorded on the standard error output.
+
+Verification requires that the archive be on a back-space-able medium.
+This means pipes, some cartridge tape drives, and some other devices
+cannot be verified.
+
+You can insure the accuracy of an archive by comparing files in the
+system with archive members. @command{tar} can compare an archive to the
+file system as the archive is being written, to verify a write
+operation, or can compare a previously written archive, to insure that
+it is up to date.
+
address@hidden address@hidden, using with @option{--create}}
address@hidden address@hidden, using with @option{--verify}}
+To check for discrepancies in an archive immediately after it is
+written, use the @option{--verify} (@option{-W}) option in conjunction with
+the @option{--create} operation. When this option is
+specified, @command{tar} checks archive members against their counterparts
+in the file system, and reports discrepancies on the standard error.
+
+To verify an archive, you must be able to read it from before the end
+of the last written entry. This option is useful for detecting data
+errors on some tapes. Archives written to pipes, some cartridge tape
+drives, and some other devices cannot be verified.
+
+One can explicitly compare an already made archive with the file
+system by using the @option{--compare} (@option{--diff}, @option{-d})
+option, instead of using the more automatic @option{--verify} option.
address@hidden
+
+Note that these two options have a slightly different intent. The
address@hidden option checks how identical are the logical contents of some
+archive with what is on your disks, while the @option{--verify} option is
+really for checking if the physical contents agree and if the recording
+media itself is of dependable quality. So, for the @option{--verify}
+operation, @command{tar} tries to defeat all in-memory cache pertaining to
+the archive, while it lets the speed optimization undisturbed for the
address@hidden option. If you nevertheless use @option{--compare} for
+media verification, you may have to defeat the in-memory cache yourself,
+maybe by opening and reclosing the door latch of your recording unit,
+forcing some doubt in your operating system about the fact this is really
+the same volume as the one just written or read.
+
+The @option{--verify} option would not be necessary if drivers were indeed
+able to detect dependably all write failures. This sometimes require many
+magnetic heads, some able to read after the writes occurred. One would
+not say that drivers unable to detect all cases are necessarily flawed,
+as long as programming is concerned.
+
+The @option{--verify} (@option{-W}) option will not work in
+conjunction with the @option{--multi-volume} (@option{-M}) option or
+the @option{--append} (@option{-r}), @option{--update} (@option{-u})
+and @option{--delete} operations. @xref{Operations}, for more
+information on these operations.
+
+Also, since @command{tar} normally strips leading @samp{/} from file
+names (@pxref{absolute}), a command like @samp{tar --verify -cf
+/tmp/foo.tar /etc} will work as desired only if the working directory is
address@hidden/}, as @command{tar} uses the archive's relative member names
+(e.g., @file{etc/motd}) when verifying the archive.
+
address@hidden Write Protection
address@hidden Write Protection
+
+Almost all tapes and diskettes, and in a few rare cases, even disks can
+be @dfn{write protected}, to protect data on them from being changed.
+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).
+
+The write protection device itself is usually an integral part of the
+physical media, and can be a two position (write enabled/write
+disabled) switch, a notch which can be popped out or covered, a ring
+which can be removed from the center of a tape reel, or some other
+changeable feature.
+
address@hidden Changes
address@hidden Changes
+
+This appendix lists some important user-visible changes between
+version @acronym{GNU} @command{tar} 1.15.92 and previous versions. An
up-to-date
+version of this document is available at
address@hidden://www.gnu.org/@/software/@/tar/manual/changes.html,the
address@hidden @command{tar} documentation page}.
+
address@hidden @asis
address@hidden Use of globbing patterns when listing and extracting.
+
+Previous versions of GNU tar assumed shell-style globbing when
+extracting from or listing an archive. For example:
+
address@hidden
+$ @kbd{tar xf foo.tar '*.c'}
address@hidden smallexample
+
+would extract all files whose names end in @samp{.c}. This behavior
+was not documented and was incompatible with traditional tar
+implementations. Therefore, starting from version 1.15.91, GNU tar
+no longer uses globbing by default. For example, the above invocation
+is now interpreted as a request to extract from the archive the file
+named @file{*.c}.
+
+To facilitate transition to the new behavior for those users who got
+used to the previous incorrect one, @command{tar} will print a warning
+if it finds out that a requested member was not found in the archive
+and its name looks like a globbing pattern. For example:
+
address@hidden
+$ @kbd{tar xf foo.tar '*.c'}
+tar: Pattern matching characters used in file names. Please,
+tar: use --wildcards to enable pattern matching, or --no-wildcards to
+tar: suppress this warning.
+tar: *.c: Not found in archive
+tar: Error exit delayed from previous errors
address@hidden smallexample
+
+To treat member names as globbing patterns, use --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.
+
address@hidden, for the detailed discussion of the use of globbing
+patterns by @acronym{GNU} @command{tar}.
+
address@hidden Use of short option @option{-o}.
+
+Earlier versions of @acronym{GNU} @command{tar} understood @option{-o} command
line
+option as a synonym for @option{--old-archive}.
+
address@hidden @command{tar} starting from version 1.13.90 understands this
option as
+a synonym for @option{--no-same-owner}. This is compatible with
+UNIX98 @command{tar} implementations.
+
+However, to facilitate transition, @option{-o} option retains its
+old semantics when it is used with one of archive-creation commands.
+Users are encouraged to use @option{--format=oldgnu} instead.
+
+It is especially important, since versions of @acronym{GNU} Automake
+up to and including 1.8.4 invoke tar with this option to produce
+distribution tarballs. @xref{Formats,v7}, for the detailed discussion
+of this issue and its implications.
+
address@hidden
address@hidden
+.
address@hidden, tar-v7, Changing Automake's Behavior,
+automake, GNU Automake}, for a description on how to use various
+archive formats with @command{automake}.
+
+Future versions of @acronym{GNU} @command{tar} will understand @option{-o}
only as a
+synonym for @option{--no-same-owner}.
+
address@hidden Use of short option @option{-l}
+
+Earlier versions of @acronym{GNU} @command{tar} 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,
+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.
+
address@hidden Use of options @option{--portability} and @option{--old-archive}
+
+These options are deprecated. Please use @option{--format=v7} instead.
+
address@hidden Use of option @option{--posix}
+
+This option is deprecated. Please use @option{--format=posix} instead.
address@hidden table
+
address@hidden Configuring Help Summary
address@hidden Configuring Help Summary
+
+Running @kbd{tar --help} displays the short @command{tar} option
+summary (@pxref{help}). This summary is organised by @dfn{groups} of
+semantically close options. The options within each group are printed
+in the following order: a short option, eventually followed by a list
+of corresponding long option names, followed by a short description of
+the option. For example, here is an excerpt from the actual @kbd{tar
+--help} output:
+
address@hidden
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to an archive
+ -c, --create create a new archive
+ -d, --diff, --compare find differences between archive and
+ file system
+ --delete delete from the archive
address@hidden verbatim
+
address@hidden ARGP_HELP_FMT, environment variable
+The exact visual representation of the help output is configurable via
address@hidden environment variable. The value of this variable
+is a comma-separated list of @dfn{format variable} assignments. There
+are two kinds of format variables. An @dfn{offset variable} keeps the
+offset of some part of help output text from the leftmost column on
+the screen. A @dfn{boolean} variable is a flag that toggles some
+output feature on or off. Depending on the type of the corresponding
+variable, there are two kinds of assignments:
+
address@hidden @asis
address@hidden Offset assignment
+
+The assignment to an offset variable has the following syntax:
+
address@hidden
address@hidden@var{value}
address@hidden smallexample
+
address@hidden
+where @var{variable} is the variable name, and @var{value} is a
+numeric value to be assigned to the variable.
+
address@hidden Boolean assignment
+
+To assign @code{true} value to a variable, simply put this variable name. To
+assign @code{false} value, prefix the variable name with @samp{no-}. For
+example:
+
address@hidden
address@hidden
+# Assign @code{true} value:
+dup-args
+# Assign @code{false} value:
+no-dup-args
address@hidden group
address@hidden smallexample
address@hidden table
+
+Following variables are declared:
+
address@hidden {Help Output} boolean dup-args
+If true, arguments for an option are shown with both short and long
+options, even when a given option has both forms, for example:
+
address@hidden
+ -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden smallexample
+
+If false, then if an option has both short and long forms, the
+argument is only shown with the long one, for example:
+
address@hidden
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden smallexample
+
address@hidden
+and a message indicating that the argument is applicable to both
+forms is printed below the options. This message can be disabled
+using @code{dup-args-note} (see below).
+
+The default is false.
address@hidden deftypevr
+
address@hidden {Help Output} boolean dup-args-note
+If this variable is true, which is the default, the following notice
+is displayed at the end of the help output:
+
address@hidden
+Mandatory or optional arguments to long options are also mandatory or
+optional for any corresponding short options.
address@hidden quotation
+
+Setting @code{no-dup-args-note} inhibits this message. Normally, only one of
+variables @code{dup-args} or @code{dup-args-note} should be set.
address@hidden deftypevr
+
address@hidden {Help Output} offset short-opt-col
+Column in which short options start. Default is 2.
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset long-opt-col
+Column in which long options start. Default is 6. For example:
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset doc-opt-col
+Column in which @dfn{doc options} start. A doc option isn't actually
+an option, but rather an arbitrary piece of documentation that is
+displayed in much the same manner as the options. For example, in
+the description of @option{--format} option:
+
address@hidden
address@hidden
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
address@hidden group
address@hidden smallexample
+
address@hidden
+the format names are doc options. Thus, if you set
address@hidden the above part of the help output
+will look as follows:
+
address@hidden
address@hidden
+ -H, --format=FORMAT create archive of the given format.
+
+ FORMAT is one of the following:
+
+ gnu GNU tar 1.13.x format
+ oldgnu GNU format as per tar <= 1.12
+ pax POSIX 1003.1-2001 (pax) format
+ posix same as pax
+ ustar POSIX 1003.1-1988 (ustar) format
+ v7 old V7 tar format
address@hidden group
address@hidden smallexample
address@hidden deftypevr
+
address@hidden {Help Output} offset opt-doc-col
+Column in which option description starts. Default is 29.
+
address@hidden
address@hidden
+$ @kbd{tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE}
+ -f, --file=ARCHIVE
+ use archive file or device ARCHIVE
address@hidden group
address@hidden smallexample
+
address@hidden
+Notice, that the description starts on a separate line if
address@hidden value is too small.
address@hidden deftypevr
+
address@hidden {Help Output} offset header-col
+Column in which @dfn{group headers} are printed. A group header is a
+descriptive text preceding an option group. For example, in the
+following text:
+
address@hidden
+ Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to
+ an archive
+ -c, --create create a new archive
address@hidden verbatim
address@hidden
address@hidden operation mode:} is the group header.
+
+The default value is 1.
address@hidden deftypevr
+
address@hidden {Help Output} offset usage-indent
+Indentation of wrapped usage lines. Affects @option{--usage}
+output. Default is 12.
address@hidden deftypevr
+
address@hidden {Help Output} offset rmargin
+Right margin of the text output. Used for wrapping.
address@hidden deftypevr
+
address@hidden Tar Internals
address@hidden Tar Internals
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
+* Sparse Formats:: Storing Sparse Files
+* Snapshot Files::
+* Dumpdir::
address@hidden menu
+
address@hidden Standard
address@hidden Basic Tar Format
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+While an archive may contain many files, the archive itself is a
+single ordinary file. Like any other file, an archive file can be
+written to a storage device such as a tape or disk, sent through a
+pipe or over a network, saved on the active file system, or even
+stored in another archive. An archive file is not easy to read or
+manipulate without using the @command{tar} utility or Tar mode in
address@hidden Emacs.
+
+Physically, an archive consists of a series of file entries terminated
+by an end-of-archive entry, which consists of two 512 blocks of zero
+bytes. A file
+entry usually describes one of the files in the archive (an
address@hidden member}), and consists of a file header and the contents
+of the file. File headers contain file names and statistics, checksum
+information which @command{tar} uses to detect file corruption, and
+information about file types.
+
+Archives are permitted to have more than one member with the same
+member name. One way this situation can occur is if more than one
+version of a file has been stored in the archive. For information
+about adding new versions of a file to an archive, see @ref{update}.
address@hidden
+
+In addition to entries describing archive members, an archive may
+contain entries which @command{tar} itself uses to store information.
address@hidden, for an example of such an archive entry.
+
+A @command{tar} archive file contains a series of blocks. Each block
+contains @code{BLOCKSIZE} bytes. Although this format may be thought
+of as being on magnetic tape, other media are often used.
+
+Each file archived is represented by a header block which describes
+the file, followed by zero or more blocks which give the contents
+of the file. At the end of the archive file there are two 512-byte blocks
+filled with binary zeros as an end-of-file marker. A reasonable system
+should write such end-of-file marker at the end of an archive, but
+must not assume that such a block exists when reading an archive. In
+particular @acronym{GNU} @command{tar} always issues a warning if it does not
encounter it.
+
+The blocks may be @dfn{blocked} for physical I/O operations.
+Each record of @var{n} blocks (where @var{n} is set by the
address@hidden@var{512-size}} (@option{-b @var{512-size}}) option to
@command{tar}) is written with a single
address@hidden@samp{write ()}} operation. On magnetic tapes, the result of
+such a write is a single record. When writing an archive,
+the last record of blocks should be written at the full size, with
+blocks after the zero block containing all zeros. When reading
+an archive, a reasonable system should properly handle an archive
+whose last record is shorter than the rest, or which contains garbage
+records after a zero block.
+
+The header block is defined in C as follows. In the @acronym{GNU}
@command{tar}
+distribution, this is part of file @file{src/tar.h}:
+
address@hidden
address@hidden GNU tar Archive Format description.
address@hidden
address@hidden Copyright (C) 1988, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
1997,
address@hidden 2000, 2001, 2003, 2004, 2005, 2006 Free Software Foundation,
Inc.
address@hidden
address@hidden This program is free software; you can redistribute it and/or
modify it
address@hidden under the terms of the GNU General Public License as published
by the
address@hidden Free Software Foundation; either version 2, or (at your
option) any later
address@hidden version.
address@hidden
address@hidden This program is distributed in the hope that it will be
useful, but
address@hidden WITHOUT ANY WARRANTY; without even the implied warranty of
address@hidden MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General
address@hidden Public License for more details.
address@hidden
address@hidden You should have received a copy of the GNU General Public
License along
address@hidden with this program; if not, write to the Free Software
Foundation, Inc.,
address@hidden 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+/address@hidden tar Header Block, from POSIX 1003.1-1990. }*/
+
+/address@hidden POSIX header. }*/
+
+struct posix_header
address@hidden /address@hidden byte offset }*/
+ char name[100]; /address@hidden 0 }*/
+ char mode[8]; /address@hidden 100 }*/
+ char uid[8]; /address@hidden 108 }*/
+ char gid[8]; /address@hidden 116 }*/
+ char size[12]; /address@hidden 124 }*/
+ char mtime[12]; /address@hidden 136 }*/
+ char chksum[8]; /address@hidden 148 }*/
+ char typeflag; /address@hidden 156 }*/
+ char linkname[100]; /address@hidden 157 }*/
+ char magic[6]; /address@hidden 257 }*/
+ char version[2]; /address@hidden 263 }*/
+ char uname[32]; /address@hidden 265 }*/
+ char gname[32]; /address@hidden 297 }*/
+ char devmajor[8]; /address@hidden 329 }*/
+ char devminor[8]; /address@hidden 337 }*/
+ char prefix[155]; /address@hidden 345 }*/
+ /address@hidden 500 }*/
address@hidden;
+
+#define TMAGIC "ustar" /address@hidden ustar and a null }*/
+#define TMAGLEN 6
+#define TVERSION "00" /address@hidden 00 and no null }*/
+#define TVERSLEN 2
+
+/address@hidden Values used in typeflag field. }*/
+#define REGTYPE '0' /address@hidden regular file }*/
+#define AREGTYPE '\0' /address@hidden regular file }*/
+#define LNKTYPE '1' /address@hidden link }*/
+#define SYMTYPE '2' /address@hidden reserved }*/
+#define CHRTYPE '3' /address@hidden character special }*/
+#define BLKTYPE '4' /address@hidden block special }*/
+#define DIRTYPE '5' /address@hidden directory }*/
+#define FIFOTYPE '6' /address@hidden FIFO special }*/
+#define CONTTYPE '7' /address@hidden reserved }*/
+
+#define XHDTYPE 'x' /address@hidden Extended header referring to
the
+ next file in the archive }*/
+#define XGLTYPE 'g' /address@hidden Global extended header }*/
+
+/address@hidden Bits used in the mode field, values in octal. }*/
+#define TSUID 04000 /address@hidden set UID on execution }*/
+#define TSGID 02000 /address@hidden set GID on execution }*/
+#define TSVTX 01000 /address@hidden reserved }*/
+ /address@hidden file permissions }*/
+#define TUREAD 00400 /address@hidden read by owner }*/
+#define TUWRITE 00200 /address@hidden write by owner }*/
+#define TUEXEC 00100 /address@hidden execute/search by owner }*/
+#define TGREAD 00040 /address@hidden read by group }*/
+#define TGWRITE 00020 /address@hidden write by group }*/
+#define TGEXEC 00010 /address@hidden execute/search by group }*/
+#define TOREAD 00004 /address@hidden read by other }*/
+#define TOWRITE 00002 /address@hidden write by other }*/
+#define TOEXEC 00001 /address@hidden execute/search by other }*/
+
+/address@hidden tar Header Block, GNU extensions. }*/
+
+/address@hidden In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is
for
+ contiguous files, so maybe disobeying the `reserved' comment in POSIX
+ header description. I suspect these were meant to be used this way, and
+ should not have really been `reserved' in the published standards. }*/
+
+/address@hidden *BEWARE* *BEWARE* *BEWARE* that the following information is
still
+ boiling, and may change. Even if the OLDGNU format description should be
+ accurate, the so-called GNU format is not yet fully decided. It is
+ surely meant to use only extensions allowed by POSIX, but the sketch
+ below repeats some ugliness from the OLDGNU format, which should rather
+ go away. Sparse files should be saved in such a way that they do *not*
+ require two passes at archive creation time. Huge files get some POSIX
+ fields to overflow, alternate solutions have to be sought for this. }*/
+
+/address@hidden Descriptor for a single file hole. }*/
+
+struct sparse
address@hidden /address@hidden byte offset }*/
+ char offset[12]; /address@hidden 0 }*/
+ char numbytes[12]; /address@hidden 12 }*/
+ /address@hidden 24 }*/
address@hidden;
+
+/address@hidden Sparse files are not supported in POSIX ustar format. For
sparse files
+ with a POSIX header, a GNU extra header is provided which holds overall
+ sparse information and a few sparse descriptors. When an old GNU header
+ replaces both the POSIX header and the GNU extra header, it holds some
+ sparse descriptors too. Whether POSIX or not, if more sparse descriptors
+ are still needed, they are put into as many successive sparse headers as
+ necessary. The following constants tell how many sparse descriptors fit
+ in each kind of header able to hold them. }*/
+
+#define SPARSES_IN_EXTRA_HEADER 16
+#define SPARSES_IN_OLDGNU_HEADER 4
+#define SPARSES_IN_SPARSE_HEADER 21
+
+/address@hidden Extension header for sparse files, used immediately after the
GNU extra
+ header, and used only if all sparse information cannot fit into that
+ extra header. There might even be many such extension headers, one after
+ the other, until all sparse information has been recorded. }*/
+
+struct sparse_header
address@hidden /address@hidden byte offset }*/
+ struct sparse sp[SPARSES_IN_SPARSE_HEADER];
+ /address@hidden 0 }*/
+ char isextended; /address@hidden 504 }*/
+ /address@hidden 505 }*/
address@hidden;
+
+/address@hidden The old GNU format header conflicts with POSIX format in such
a way that
+ POSIX archives may fool old GNU tar's, and POSIX tar's might well be
+ fooled by old GNU tar archives. An old GNU format header uses the space
+ used by the prefix field in a POSIX header, and cumulates information
+ normally found in a GNU extra header. With an old GNU tar header, we
+ never see any POSIX header nor GNU extra header. Supplementary sparse
+ headers are allowed, however. }*/
+
+struct oldgnu_header
address@hidden /address@hidden byte offset }*/
+ char unused_pad1[345]; /address@hidden 0 }*/
+ char atime[12]; /address@hidden 345 Incr. archive: atime of
the file }*/
+ char ctime[12]; /address@hidden 357 Incr. archive: ctime of
the file }*/
+ char offset[12]; /address@hidden 369 Multivolume archive: the
offset of
+ the start of this volume }*/
+ char longnames[4]; /address@hidden 381 Not used }*/
+ char unused_pad2; /address@hidden 385 }*/
+ struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
+ /address@hidden 386 }*/
+ char isextended; /address@hidden 482 Sparse file: Extension
sparse header
+ follows }*/
+ char realsize[12]; /address@hidden 483 Sparse file: Real size}*/
+ /address@hidden 495 }*/
address@hidden;
+
+/address@hidden OLDGNU_MAGIC uses both magic and version fields, which are
contiguous.
+ Found in an archive, it indicates an old GNU header format, which will be
+ hopefully become obsolescent. With OLDGNU_MAGIC, uname and gname are
+ valid, though the header is not truly POSIX conforming. }*/
+#define OLDGNU_MAGIC "ustar " /address@hidden 7 chars and a null }*/
+
+/address@hidden The standards committee allows only capital A through capital
Z for
+ user-defined expansion. Other letters in use include:
+
+ 'A' Solaris Access Control List
+ 'E' Solaris Extended Attribute File
+ 'I' Inode only, as in 'star'
+ 'X' POSIX 1003.1-2001 eXtended (VU version) }*/
+
+/address@hidden This is a dir entry that contains the names of files that were
in the
+ dir at the time the dump was made. }*/
+#define GNUTYPE_DUMPDIR 'D'
+
+/address@hidden Identifies the *next* file on the tape as having a long
linkname. }*/
+#define GNUTYPE_LONGLINK 'K'
+
+/address@hidden Identifies the *next* file on the tape as having a long name.
}*/
+#define GNUTYPE_LONGNAME 'L'
+
+/address@hidden This is the continuation of a file that began on another
volume. }*/
+#define GNUTYPE_MULTIVOL 'M'
+
+/address@hidden For storing filenames that do not fit into the main header.
}*/
+#define GNUTYPE_NAMES 'N'
+
+/address@hidden This is for sparse files. }*/
+#define GNUTYPE_SPARSE 'S'
+
+/address@hidden This file is a tape/volume header. Ignore it on extraction.
}*/
+#define GNUTYPE_VOLHDR 'V'
+
+/address@hidden Solaris extended header }*/
+#define SOLARIS_XHDTYPE 'X'
+
+/address@hidden J@"org Schilling star header }*/
+
+struct star_header
address@hidden /address@hidden byte offset }*/
+ char name[100]; /address@hidden 0 }*/
+ char mode[8]; /address@hidden 100 }*/
+ char uid[8]; /address@hidden 108 }*/
+ char gid[8]; /address@hidden 116 }*/
+ char size[12]; /address@hidden 124 }*/
+ char mtime[12]; /address@hidden 136 }*/
+ char chksum[8]; /address@hidden 148 }*/
+ char typeflag; /address@hidden 156 }*/
+ char linkname[100]; /address@hidden 157 }*/
+ char magic[6]; /address@hidden 257 }*/
+ char version[2]; /address@hidden 263 }*/
+ char uname[32]; /address@hidden 265 }*/
+ char gname[32]; /address@hidden 297 }*/
+ char devmajor[8]; /address@hidden 329 }*/
+ char devminor[8]; /address@hidden 337 }*/
+ char prefix[131]; /address@hidden 345 }*/
+ char atime[12]; /address@hidden 476 }*/
+ char ctime[12]; /address@hidden 488 }*/
+ /address@hidden 500 }*/
address@hidden;
+
+#define SPARSES_IN_STAR_HEADER 4
+#define SPARSES_IN_STAR_EXT_HEADER 21
+
+struct star_in_header
address@hidden
+ char fill[345]; /address@hidden 0 Everything that is before
t_prefix }*/
+ char prefix[1]; /address@hidden 345 t_name prefix }*/
+ char fill2; /address@hidden 346 }*/
+ char fill3[8]; /address@hidden 347 }*/
+ char isextended; /address@hidden 355 }*/
+ struct sparse sp[SPARSES_IN_STAR_HEADER]; /address@hidden 356 }*/
+ char realsize[12]; /address@hidden 452 Actual size of the file }*/
+ char offset[12]; /address@hidden 464 Offset of multivolume contents }*/
+ char atime[12]; /address@hidden 476 }*/
+ char ctime[12]; /address@hidden 488 }*/
+ char mfill[8]; /address@hidden 500 }*/
+ char xmagic[4]; /address@hidden 508 "tar" }*/
address@hidden;
+
+struct star_ext_header
address@hidden
+ struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
+ char isextended;
address@hidden;
+
address@hidden smallexample
+
+All characters in header blocks are represented by using 8-bit
+characters in the local variant of ASCII. Each field within the
+structure is contiguous; that is, there is no padding used within
+the structure. Each character on the archive medium is stored
+contiguously.
+
+Bytes representing the contents of files (after the header block
+of each file) are not translated in any way and are not constrained
+to represent characters in any character set. The @command{tar} format
+does not distinguish text files from binary files, and no translation
+of file contents is performed.
+
+The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
address@hidden are null-terminated character strings. All other fields
+are zero-filled octal numbers in ASCII. Each numeric field of width
address@hidden contains @var{w} minus 1 digits, and a null.
+
+The @code{name} field is the file name of the file, with directory names
+(if any) preceding the file name, separated by slashes.
+
address@hidden
address@hidden
+
+
+The @code{mode} field provides nine bits specifying file permissions
+and three bits to specify the Set UID, Set GID, and Save Text
+(@dfn{sticky}) modes. Values for these bits are defined above.
+When special permissions are required to create a file with a given
+mode, and the user restoring files from the archive does not hold such
+permissions, the mode bit(s) specifying those special permissions
+are ignored. Modes which are not supported by the operating system
+restoring files from the archive will be ignored. Unsupported modes
+should be faked up when creating or updating an archive; e.g., the
+group permission could be copied from the @emph{other} permission.
+
+The @code{uid} and @code{gid} fields are the numeric user and group
+ID of the file owners, respectively. If the operating system does
+not support numeric user or group IDs, these fields should be ignored.
+
+The @code{size} field is the size of the file in bytes; linked files
+are archived with this field specified as zero. @quote-arg
+
+The @code{mtime} field is the data modification time of the file at
+the time it was archived. It is the ASCII representation of the octal
+value of the last time the file's contents were modified, represented
+as an integer number of
+seconds since January 1, 1970, 00:00 Coordinated Universal Time.
+
+The @code{chksum} field is the ASCII representation of the octal value
+of the simple sum of all bytes in the header block. Each 8-bit
+byte in the header is added to an unsigned integer, initialized to
+zero, the precision of which shall be no less than seventeen bits.
+When calculating the checksum, the @code{chksum} field is treated as
+if it were all blanks.
+
+The @code{typeflag} field specifies the type of file archived. If a
+particular implementation does not recognize or permit the specified
+type, the file will be extracted as if it were a regular file. As this
+action occurs, @command{tar} issues a warning to the standard error.
+
+The @code{atime} and @code{ctime} fields are used in making incremental
+backups; they store, respectively, the particular file's access and
+status change times.
+
+The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option,
when
+making a multi-volume archive. The offset is number of bytes into
+the file that we need to restart at to continue the file on the next
+tape, i.e., where we store the location that a continued file is
+continued at.
+
+The following fields were added to deal with sparse files. A file
+is @dfn{sparse} if it takes in unallocated blocks which end up being
+represented as zeros, i.e., no useful data. A test to see if a file
+is sparse is to look at the number blocks allocated for it versus the
+number of characters in the file; if there are fewer blocks allocated
+for the file than would normally be allocated for a file of that
+size, then the file is sparse. This is the method @command{tar} uses to
+detect a sparse file, and once such a file is detected, it is treated
+differently from non-sparse files.
+
+Sparse files are often @code{dbm} files, or other database-type files
+which have data at some points and emptiness in the greater part of
+the file. Such files can appear to be very large when an @samp{ls
+-l} is done on them, when in truth, there may be a very small amount
+of important data contained in the file. It is thus undesirable
+to have @command{tar} think that it must back up this entire file, as
+great quantities of room are wasted on empty blocks, which can lead
+to running out of room on a tape far earlier than is necessary.
+Thus, sparse files are dealt with so that these empty blocks are
+not written to the tape. Instead, what is written to the tape is a
+description, of sorts, of the sparse file: where the holes are, how
+big the holes are, and how much data is found at the end of the hole.
+This way, the file takes up potentially far less room on the tape,
+and when the file is extracted later on, it will look exactly the way
+it looked beforehand. The following is a description of the fields
+used to handle a sparse file:
+
+The @code{sp} is an array of @code{struct sparse}. Each @code{struct
+sparse} contains two 12-character strings which represent an offset
+into the file and a number of bytes to be written at that offset.
+The offset is absolute, and not relative to the offset in preceding
+array element.
+
+The header can hold four of these @code{struct sparse} at the moment;
+if more are needed, they are not stored in the header.
+
+The @code{isextended} flag is set when an @code{extended_header}
+is needed to deal with a file. Note that this means that this flag
+can only be set when dealing with a sparse file, and it is only set
+in the event that the description of the file will not fit in the
+allotted room for sparse structures in the header. In other words,
+an extended_header is needed.
+
+The @code{extended_header} structure is used for sparse files which
+need more sparse structures than can fit in the header. The header can
+fit 4 such structures; if more are needed, the flag @code{isextended}
+gets set and the next block is an @code{extended_header}.
+
+Each @code{extended_header} structure contains an array of 21
+sparse structures, along with a similar @code{isextended} flag
+that the header had. There can be an indeterminate number of such
address@hidden to describe a sparse file.
+
address@hidden @asis
+
address@hidden @code{REGTYPE}
address@hidden @code{AREGTYPE}
+These flags represent a regular file. In order to be compatible
+with older versions of @command{tar}, a @code{typeflag} value of
address@hidden should be silently recognized as a regular file.
+New archives should be created using @code{REGTYPE}. Also, for
+backward compatibility, @command{tar} treats a regular file whose name
+ends with a slash as a directory.
+
address@hidden @code{LNKTYPE}
+This flag represents a file linked to another file, of any type,
+previously archived. Such files are identified in Unix by each
+file having the same device and inode number. The linked-to name is
+specified in the @code{linkname} field with a trailing null.
+
address@hidden @code{SYMTYPE}
+This represents a symbolic link to another file. The linked-to name
+is specified in the @code{linkname} field with a trailing null.
+
address@hidden @code{CHRTYPE}
address@hidden @code{BLKTYPE}
+These represent character special files and block special files
+respectively. In this case the @code{devmajor} and @code{devminor}
+fields will contain the major and minor device numbers respectively.
+Operating systems may map the device specifications to their own
+local specification, or may ignore the entry.
+
address@hidden @code{DIRTYPE}
+This flag specifies a directory or sub-directory. The directory
+name in the @code{name} field should end with a slash. On systems where
+disk allocation is performed on a directory basis, the @code{size} field
+will contain the maximum number of bytes (which may be rounded to
+the nearest disk block allocation unit) which the directory may
+hold. A @code{size} field of zero indicates no such limiting. Systems
+which do not support limiting in this manner should ignore the
address@hidden field.
+
address@hidden @code{FIFOTYPE}
+This specifies a FIFO special file. Note that the archiving of a
+FIFO file archives the existence of this file and not its contents.
+
address@hidden @code{CONTTYPE}
+This specifies a contiguous file, which is the same as a normal
+file except that, in operating systems which support it, all its
+space is allocated contiguously on the disk. Operating systems
+which do not allow contiguous allocation should silently treat this
+type as a normal file.
+
address@hidden @code{A} @dots{} @code{Z}
+These are reserved for custom implementations. Some of these are
+used in the @acronym{GNU} modified format, as described below.
+
address@hidden table
+
+Other values are reserved for specification in future revisions of
+the P1003 standard, and should not be used by any @command{tar} program.
+
+The @code{magic} field indicates that this archive was output in
+the P1003 archive format. If this field contains @code{TMAGIC},
+the @code{uname} and @code{gname} fields will contain the ASCII
+representation of the owner and group of the file respectively.
+If found, the user and group IDs are used rather than the values in
+the @code{uid} and @code{gid} fields.
+
+For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
+169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
+IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
+(section E.4.48) for @cite{pax - Portable archive interchange}.
+
address@hidden Extensions
address@hidden @acronym{GNU} Extensions to the Archive Format
address@hidden
address@hidden(This message will disappear, once this node revised.)}
address@hidden quotation
+
+The @acronym{GNU} format uses additional file types to describe new types of
+files in an archive. These are listed below.
+
address@hidden @code
address@hidden GNUTYPE_DUMPDIR
address@hidden 'D'
+This represents a directory and a list of files created by the
address@hidden (@option{-G}) option. The @code{size} field gives the total
+size of the associated list of files. Each file name is preceded by
+either a @samp{Y} (the file should be in this archive) or an @samp{N}.
+(The file is a directory, or is not stored in the archive.) Each file
+name is terminated by a null. There is an additional null after the
+last file name.
+
address@hidden GNUTYPE_MULTIVOL
address@hidden 'M'
+This represents a file continued from another volume of a multi-volume
+archive created with the @option{--multi-volume} (@option{-M}) option. The
original
+type of the file is not given here. The @code{size} field gives the
+maximum size of this piece of the file (assuming the volume does
+not end before the file is written out). The @code{offset} field
+gives the offset from the beginning of the file where this part of
+the file begins. Thus @code{size} plus @code{offset} should equal
+the original size of the file.
+
address@hidden GNUTYPE_SPARSE
address@hidden 'S'
+This flag indicates that we are dealing with a sparse file. Note
+that archiving a sparse file requires special operations to find
+holes in the file, which mark the positions of these holes, along
+with the number of bytes of data to be found after the hole.
+
address@hidden GNUTYPE_VOLHDR
address@hidden 'V'
+This file type is used to mark the volume header that was given with
+the @address@hidden (@option{-V @var{archive-label}}) option when the archive
was created. The @code{name}
+field contains the @code{name} given after the @address@hidden (@option{-V
@var{archive-label}}) option.
+The @code{size} field is zero. Only the first file in each volume
+of an archive should have this type.
+
address@hidden table
+
+You may have trouble reading a @acronym{GNU} format archive on a
address@hidden system if the options @option{--incremental} (@option{-G}),
address@hidden (@option{-M}), @option{--sparse} (@option{-S}), or
@address@hidden (@option{-V @var{archive-label}}) were
+used when writing the archive. In general, if @command{tar} does not
+use the @acronym{GNU}-added fields of the header, other versions of
address@hidden should be able to read the archive. Otherwise, the
address@hidden program will give an error, the most likely one being a
+checksum error.
+
address@hidden Sparse Formats
address@hidden Storing Sparse Files
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden sparse formats
address@hidden sparse versions
+The notion of sparse file, and the ways of handling it from the point
+of view of @acronym{GNU} @command{tar} user have been described in detail in
address@hidden This chapter describes the internal format @acronym{GNU}
@command{tar}
+uses to store such files.
+
+The support for sparse files in @acronym{GNU} @command{tar} has a long
history. The
+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
address@hidden GNU} sparse format and in spite of the fact that its design
+contained many flaws, it was the only format @acronym{GNU} @command{tar}
supported
+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
+improved in versions 1.15.2 (November, 2005) and 1.15.92 (June,
+2006).
+
+In addition to GNU sparse format, @acronym{GNU} @command{tar} is able to read
and
+extract sparse files archived by @command{star}.
+
+The following subsections describe each format in detail.
+
address@hidden
+* Old GNU Format::
+* PAX 0:: PAX Format, Versions 0.0 and 0.1
+* PAX 1:: PAX Format, Version 1.0
address@hidden menu
+
address@hidden Old GNU Format
address@hidden Old GNU Format
+
address@hidden sparse formats, Old GNU
address@hidden Old GNU sparse format
+The format introduced some time around 1990 (v. 1.09). It was
+designed on top of standard @code{ustar} headers in such an
+unfortunate way that some of its fields overwrote fields required by
+POSIX.
+
+An old GNU sparse header is designated by type @samp{S}
+(@code{GNUTYPE_SPARSE}) and has the following layout:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.20 0.40
address@hidden Offset @tab Size @tab Name @tab Data type @tab Contents
address@hidden 0 @tab 345 @tab @tab N/A @tab Not used.
address@hidden 345 @tab 12 @tab atime @tab Number @tab
@code{atime} of the file.
address@hidden 357 @tab 12 @tab ctime @tab Number @tab
@code{ctime} of the file .
address@hidden 369 @tab 12 @tab offset @tab Number @tab For
+multivolume archives: the offset of the start of this volume.
address@hidden 381 @tab 4 @tab @tab N/A @tab Not used.
address@hidden 385 @tab 1 @tab @tab N/A @tab Not used.
address@hidden 386 @tab 96 @tab sp @tab @code{sparse_header} @tab
(4 entries) File map.
address@hidden 482 @tab 1 @tab isextended @tab Bool @tab
@code{1} if an
+extension sparse header follows, @code{0} otherwise.
address@hidden 483 @tab 12 @tab realsize @tab Number @tab Real
size of the file.
address@hidden multitable
+
+Each of @code{sparse_header} object at offset 386 describes a single
+data chunk. It has the following structure:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.60
address@hidden Offset @tab Size @tab Data type @tab Contents
address@hidden 0 @tab 12 @tab Number @tab Offset of the
+beginning of the chunk.
address@hidden 12 @tab 12 @tab Number @tab Size of the chunk.
address@hidden multitable
+
+If the member contains more than four chunks, the @code{isextended}
+field of the header has the value @code{1} and the main header is
+followed by one or more @dfn{extension headers}. Each such header has
+the following structure:
+
address@hidden @columnfractions 0.10 0.10 0.20 0.20 0.40
address@hidden Offset @tab Size @tab Name @tab Data type @tab Contents
address@hidden 0 @tab 21 @tab sp @tab @code{sparse_header} @tab
+(21 entires) File map.
address@hidden 504 @tab 1 @tab isextended @tab Bool @tab @code{1}
if an
+extension sparse header follows, or @code{0} otherwise.
address@hidden multitable
+
+A header with @code{isextended=0} ends the map.
+
address@hidden PAX 0
address@hidden PAX Format, Versions 0.0 and 0.1
+
address@hidden sparse formats, v.0.0
+There are two formats available in this branch. The version @code{0.0}
+is the initial version of sparse format used by @command{tar}
+versions 1.14--1.15.1. The sparse file map is kept in extended
+(@code{x}) PAX header variables:
+
address@hidden @code
address@hidden GNU.sparse.size, extended header variable
address@hidden GNU.sparse.size
+Real size of the stored file
+
address@hidden GNU.sparse.numblocks
address@hidden GNU.sparse.numblocks, extended header variable
+Number of blocks in the sparse map
+
address@hidden GNU.sparse.offset
address@hidden GNU.sparse.offset, extended header variable
+Offset of the data block
+
address@hidden GNU.sparse.numbytes
address@hidden GNU.sparse.numbytes, extended header variable
+Size of the data block
address@hidden table
+
+The latter two variables repeat for each data block, so the overall
+structure is like this:
+
address@hidden
address@hidden
address@hidden
address@hidden
+repeat @var{numblocks} times
+ address@hidden
+ address@hidden
+end repeat
address@hidden group
address@hidden smallexample
+
+This format presented the following two problems:
+
address@hidden 1
address@hidden
+Whereas the POSIX specification allows a variable to appear multiple
+times in a header, it requires that only the last occurrence be
+meaningful. Thus, multiple ocurrences of @code{GNU.sparse.offset} and
address@hidden are conficting with the POSIX specs.
+
address@hidden
+Attempting to extract such archives using a third-party @command{tar}s
+results in extraction of sparse files in @emph{compressed 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
+state. However, posix-aware @command{tar}s will usually ignore the
+unknown variables, which makes restoring the file more
+difficult. @xref{extracting sparse v.0.x, Extraction of sparse
+members in v.0.0 format}, for the detailed description of how to
+restore such members using non-GNU @command{tar}s.
address@hidden enumerate
+
address@hidden sparse formats, v.0.1
address@hidden @command{tar} 1.15.2 introduced sparse format version
@code{0.1}, which
+attempted to solve these problems. As its predecessor, this format
+stores sparse map in the extended POSIX header. It retains
address@hidden and @code{GNU.sparse.numblocks} variables, but
+instead of @code{GNU.sparse.offset}/@code{GNU.sparse.numbytes} pairs
+it uses a single variable:
+
address@hidden @code
address@hidden GNU.sparse.map
address@hidden 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}...]"
address@hidden table
+
+To address the 2nd problem, the @code{name} field in @code{ustar}
+is replaced with a special name, constructed using the following pattern:
+
address@hidden
+%d/GNUSparseFile.%p/%f
address@hidden smallexample
+
address@hidden GNU.sparse.name, extended header variable
+The real name of the sparse file is stored in the variable
address@hidden Thus, those @command{tar} implementations
+that are not aware of GNU extensions will at least extract the files
+into separate directories, giving the user a possibility to expand it
+afterwards. @xref{extracting sparse v.0.x, Extraction of sparse
+members in v.0.1 format}, for the detailed description of how to
+restore such members using non-GNU @command{tar}s.
+
+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.
+
address@hidden PAX 1
address@hidden PAX Format, Version 1.0
+
address@hidden sparse formats, v.1.0
+The version @code{1.0} of sparse format was introduced with @acronym{GNU}
@command{tar}
+1.15.92. Its main objective was to make the resulting file
+extractable with little effort even by non-posix aware @command{tar}
+implementations. Starting from this version, the extended header
+preceding a sparse member always contains the following variables that
+identify the format being used:
+
address@hidden @code
address@hidden GNU.sparse.major
address@hidden GNU.sparse.major, extended header variable
+Major version
+
address@hidden GNU.sparse.minor
address@hidden GNU.sparse.minor, extended header variable
+Minor version
address@hidden table
+
+The @code{name} field in @code{ustar} header contains a special name,
+constructed using the following pattern:
+
address@hidden
+%d/GNUSparseFile.%p/%f
address@hidden smallexample
+
address@hidden GNU.sparse.name, extended header variable, in v.1.0
address@hidden GNU.sparse.realsize, extended header variable
+The real name of the sparse file is stored in the variable
address@hidden The real size of the file is stored in the
+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
+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
+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 @acronym{GNU}
@command{tar}.
address@hidden Recovery}, for the detailed information on how to extract
+sparse members without @acronym{GNU} @command{tar}.
+
+
address@hidden Snapshot Files
address@hidden Format of the Incremental Snapshot Files
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2005 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
+ A @dfn{snapshot file} (or @dfn{directory file}) is created during
+incremental backups (@pxref{Incremental Dumps}). It
+contains the status of the filesystem at the time of the dump and is
+used to determine which files were modified since the last backup.
+
+ @acronym{GNU} @command{tar} version 1.15.92 supports two snapshot file
+formats. The first format, called @dfn{format 0}, is the one used by
address@hidden @command{tar} versions up to 1.15.1. The second format, called
@dfn{format
+1} is an extended version of this format, that contains more metadata
+and allows for further extensions.
+
+ @samp{Format 0} snapshot file begins with a line containing a
+decimal number that represents the UNIX timestamp of the beginning of
+the last archivation. This line is followed by directory metadata
+descriptions, one per line. Each description has the following format:
+
address@hidden
address@hidden@var{dev} @var{inode} @var{name}
address@hidden smallexample
+
address@hidden
+where optional @var{nfs} is a single plus character (@samp{+}) if this
+directory is located on an NFS-mounted partition, @var{dev} and
address@hidden are the device and inode numbers of the directory, and
address@hidden is the directory name.
+
+ @samp{Format 1} snapshot file begins with a line specifying the
+format of the file. This line has the following structure:
+
address@hidden
address@hidden address@hidden@address@hidden
address@hidden smallexample
+
address@hidden
+where @var{tar-version} is the version of @acronym{GNU} @command{tar}
implementation
+that created this snapshot, and @var{incr-format-version} is the
+version number of the snapshot format (in this case @samp{1}).
+
+ The following line contains two decimal numbers, representing the
+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.
+
+ Following lines contain directory metadate, one line per
+directory. The line format is:
+
address@hidden
address@hidden@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
address@hidden smallexample
+
address@hidden
+where @var{mtime-sec} and @var{mtime-nsec} represent the last
+modification time of this directory with nanosecond precision;
address@hidden, @var{dev}, @var{inode} and @var{name} have the same meaning
+as with @samp{format 0}.
+
+
address@hidden End of snapshot.texi
+
+
+
address@hidden Dumpdir
address@hidden Dumpdir
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2006 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
+ Incremental archives keep information about contents of each
+dumped directory in special data blocks called @dfn{dumpdirs}.
+
+ Dumpdir is a sequence of entries of the following form:
+
address@hidden
address@hidden @var{filename} \0
address@hidden smallexample
+
address@hidden
+where @var{C} is one of the @dfn{control codes} described below,
address@hidden is the name of the file @var{C} operates upon, and
address@hidden represents a nul character (ASCII 0). The white space
+characters were added for readability, real dumpdirs do not contain
+them.
+
+ Each dumpdir ends with a single nul character.
+
+ The following table describes control codes and their meanings:
+
address@hidden @samp
address@hidden Y
address@hidden is contained in the archive.
+
address@hidden N
address@hidden was present in the directory at the time the archive
+was made, yet it was not dumped to the archive, because it had not
+changed since the last backup.
+
address@hidden D
address@hidden is a directory.
+
address@hidden R
+This code requests renaming of the @var{filename} to the name
+specified with the following @samp{T} command.
+
address@hidden T
+Specify target file name for @samp{R} command (see below).
+
address@hidden X
+Specify @dfn{temporary directory} name for a rename operation (see below).
address@hidden table
+
+ Codes @samp{Y}, @samp{N} and @samp{D} require @var{filename} argument
+to be a relative file name to the directory this dumpdir describes,
+whereas codes @samp{R}, @samp{T} and @samp{X} require their argument
+to be an absolute file name.
+
+ The three codes @samp{R}, @samp{T} and @samp{X} specify a
address@hidden operation}. In the simplest case it is:
+
address@hidden
address@hidden@file{dest}\0
address@hidden smallexample
+
address@hidden
+which means ``rename file @file{source} to file @file{dest}''.
+
+ However, there are cases that require using a @dfn{temporary
+directory}. For example, consider the following scenario:
+
address@hidden 1
address@hidden
+Previous run dumped a directory @file{foo} which contained the
+following three directories:
+
address@hidden
+a
+b
+c
address@hidden smallexample
+
address@hidden
+They were renamed @emph{cyclically}, so that:
+
address@hidden
address@hidden became @file{b}
address@hidden became @file{c}
address@hidden became @file{a}
address@hidden example
+
address@hidden
+New incremental dump was made.
address@hidden enumerate
+
+ This case cannot be handled by three successive renames, since
+renaming @file{a} to @file{b} will destroy existing directory.
+To handle such case a temporary directory is required. @acronym{GNU}
@command{tar}
+will create the following dumpdir (newlines have been added for
+readability):
+
address@hidden
address@hidden
+Xfoo\0
+Rfoo/a\0T\0
+Rfoo/b\0Tfoo/c\0
+Rfoo/c\0Tfoo/a\0
+R\0Tfoo/a\0
address@hidden group
address@hidden smallexample
+
+ The first command, @samp{Xfoo\0}, instructs the extractor to create a
+temporary directory in the directory @file{foo}. Second command,
address@hidden/aT\0}, says ``rename file @file{foo/a} to the temporary
+directory that has just been created'' (empty file name after a
+command means use temporary directory). Third and fourth commands
+work as usual, and, finally, the last command, @samp{R\0Tfoo/a\0}
+tells tar to rename the temporary directory to @file{foo/a}.
+
+ The exact placement of a dumpdir in the archive depends on the
+archive format (@pxref{Formats}):
+
address@hidden
address@hidden PAX archives
+
+In PAX archives, dumpdir is stored in the extended header of the
+corresponding directory, in variable @code{GNU.dumpdir}.
+
address@hidden GNU and old GNU archives
+
+These formats implement special header type @samp{D}, which is similar
+to ustar header @samp{5} (directory), except that it preceeds a data
+block containing the dumpdir.
address@hidden itemize
+
address@hidden End of dumpdir.texi
+
+
address@hidden Genfile
address@hidden Genfile
address@hidden This is part of the paxutils manual.
address@hidden Copyright (C) 2005, 2006 Free Software Foundation, Inc.
address@hidden Written by Sergey Poznyakoff
address@hidden This file is distributed under GFDL 1.1 or any later version
address@hidden published by the Free Software Foundation.
+
address@hidden genfile
+ This appendix describes @command{genfile}, an auxiliary program
+used in the GNU tar testsuite. If you are not interested in developing
+GNU tar, skip this appendix.
+
+ Initially, @command{genfile} was used to generate data files for
+the testsuite, hence its name. However, new operation modes were being
+implemented as the testsuite grew more sophisticated, and now
address@hidden is a multi-purpose instrument.
+
+ There are three basic operation modes:
+
address@hidden @asis
address@hidden File Generation
+ This is the default mode. In this mode, @command{genfile}
+generates data files.
+
address@hidden File Status
+ In this mode @command{genfile} displays status of specified files.
+
address@hidden Synchronous Execution.
+ In this mode @command{genfile} executes the given program with
address@hidden option and executes a set of actions when
+specified checkpoints are reached.
address@hidden table
+
address@hidden
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
address@hidden menu
+
address@hidden Generate Mode
address@hidden Generate Mode
+
address@hidden Generate Mode, @command{genfile}
address@hidden @command{genfile}, generate mode
address@hidden @command{genfile}, create file
+ In this mode @command{genfile} creates a data file for the test
+suite. The size of the file is given with the @option{--length}
+(@option{-l}) option. By default the file contents is written to the
+standard output, this can be changed using @option{--file}
+(@option{-f}) command line option. Thus, the following two commands
+are equivalent:
+
address@hidden
address@hidden
+genfile --length 100 > outfile
+genfile --length 100 --file outfile
address@hidden group
address@hidden smallexample
+
+ If @option{--length} is not given, @command{genfile} will
+generate an empty (zero-length) file.
+
address@hidden @command{genfile}, reading a list of file names
+ You can instruct @command{genfile} to create several files at one
+go, by giving it @option{--files-from} (@option{-T}) option followed
+by a name of file containing a list of file names. Using dash
+(@samp{-}) instead of the file name causes @command{genfile} to read
+file list from the standard input. For example:
+
address@hidden
address@hidden
+# Read file names from file @file{file.list}
+genfile --files-from file.list
+# Read file names from standard input
+genfile --files-from -
address@hidden group
address@hidden smallexample
+
address@hidden File lists separated by NUL characters
+ The list file is supposed to contain one file name per line. To
+use file lists separated by ASCII NUL character, use @option{--null}
+(@option{-0}) command line option:
+
address@hidden
+genfile --null --files-from file.list
address@hidden smallexample
+
address@hidden pattern, @command{genfile}
+ The default data pattern for filling the generated file consists
+of first 256 letters of ASCII code, repeated enough times to fill the
+entire file. This behavior can be changed with @option{--pattern}
+option. This option takes a mandatory argument, specifying pattern
+name to use. Currently two patterns are implemented:
+
address@hidden @option
address@hidden --pattern=default
+ The default pattern as described above.
+
address@hidden --pattern=zero
+ Fills the file with zeroes.
address@hidden table
+
+ If no file name was given, the program exits with the code
address@hidden Otherwise, it exits with @code{0} only if it was able to
+create a file of the specified length.
+
address@hidden Sparse files, creating using @command{genfile}
address@hidden @command{genfile}, creating sparse files
+ Special option @option{--sparse} (@option{-s}) instructs
address@hidden to create a sparse file. Sparse files consist of
address@hidden fragments}, separated by @dfn{holes} or blocks of zeros. On
+many operating systems, actual disk storage is not allocated for
+holes, but they are counted in the length of the file. To create a
+sparse file, @command{genfile} should know where to put data fragments,
+and what data to use to fill them. So, when @option{--sparse} is given
+the rest of the command line specifies a so-called @dfn{file map}.
+
+ The file map consists of any number of @dfn{fragment
+descriptors}. Each descriptor is composed of two values: a number,
+specifying fragment offset from the end of the previous fragment or,
+for the very first fragment, from the beginning of the file, and
address@hidden string}, i.e. a string of characters, specifying the
+pattern to fill the fragment with. File offset can be suffixed with
+the following quantifiers:
+
address@hidden @samp
address@hidden k
address@hidden K
+The number is expressed in kilobytes.
address@hidden m
address@hidden M
+The number is expressed in megabytes.
address@hidden g
address@hidden G
+The number is expressed in gigabytes.
address@hidden table
+
+ For each letter in contents string @command{genfile} will generate
+a @dfn{block} of data, filled with this letter and will write it to
+the fragment. The size of block is given by @option{--block-size}
+option. It defaults to 512. Thus, if the string consists of @var{n}
+characters, the resulting file fragment will contain
address@hidden@address@hidden of data.
+
+ Last fragment descriptor can have only file offset part. In this
+case @command{genfile} will create a hole at the end of the file up to
+the given offset.
+
+ For example, consider the following invocation:
+
address@hidden
+genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
address@hidden smallexample
+
address@hidden
+It will create 3101184-bytes long file of the following structure:
+
address@hidden @columnfractions .35 .20 .45
address@hidden Offset @tab Length @tab Contents
address@hidden 0 @tab 4*512=2048 @tab Four 512-byte blocks, filled with
+letters @samp{A}, @samp{B}, @samp{C} and @samp{D}.
address@hidden 2048 @tab 1046528 @tab Zero bytes
address@hidden 1050624 @tab 5*512=2560 @tab Five blocks, filled with letters
address@hidden, @samp{F}, @samp{G}, @samp{H}, @samp{I}.
address@hidden 1053184 @tab 2048000 @tab Zero bytes
address@hidden multitable
+
+ The exit code of @command{genfile --status} command is @code{0}
+only if created file is actually sparse.
+
address@hidden Status Mode
address@hidden Status Mode
+
+ In status mode, @command{genfile} prints file system status for
+each file specified in the command line. This mode is toggled by
address@hidden (@option{-S}) command line option. An optional argument to this
+option specifies output @dfn{format}: a comma-separated list of
address@hidden stat} fields to be displayed. This list can contain
+following identifiers @allow-recursion
address@hidden
+:
+
address@hidden @asis
address@hidden name
+ The file name.
+
address@hidden dev
address@hidden st_dev
+ Device number in decimal.
+
address@hidden ino
address@hidden st_ino
+ Inode number.
+
address@hidden address@hidden
address@hidden address@hidden
+ File mode in octal. Optional @var{number} specifies octal mask to
+be applied to the mode before outputting. For example, @code{--stat
+mode.777} will preserve lower nine bits of it. Notice, that you can
+use any punctuation caracter in place of @samp{.}.
+
address@hidden nlink
address@hidden st_nlink
+ Number of hard links.
+
address@hidden uid
address@hidden st_uid
+ User ID of owner.
+
address@hidden gid
address@hidden st_gid
+ Group ID of owner.
+
address@hidden size
address@hidden st_size
+ File size in decimal.
+
address@hidden blksize
address@hidden st_blksize
+ The size in bytes of each file block.
+
address@hidden blocks
address@hidden st_blocks
+ Number of blocks allocated.
+
address@hidden atime
address@hidden st_atime
+ Time of last access.
+
address@hidden mtime
address@hidden st_mtime
+ Time of last modification
+
address@hidden ctime
address@hidden st_ctime
+ Time of last status change
+
address@hidden sparse
+ A boolean value indicating whether the file is @samp{sparse}.
address@hidden table
+
+ Modification times are displayed in @acronym{UTC} as
address@hidden timestamps, unless suffixed with @samp{H} (for
+``human-readable''), as in @samp{ctimeH}, in which case usual
address@hidden tv} output format is used.
+
+ The default output format is: @samp{name,dev,ino,mode,
+nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}.
+
+ For example, the following command will display file names and
+corresponding times of last access for each file in the current working
+directory:
+
address@hidden
+genfile --stat=name,atime *
address@hidden smallexample
+
address@hidden Exec Mode
address@hidden Exec Mode
+
address@hidden Exec Mode, @command{genfile}
+ This mode is designed for testing the behavior of @code{paxutils}
+commands when some of the files change during archiving. It is an
+experimental mode.
+
+ The @samp{Exec Mode} is toggled by @option{--run} command line
+option (or its alias @option{-r}). The argument to this option gives
+the command line to be executed. The actual command line is
+constructed by inserting @option{--checkpoint} option between the
+command name and its first argument (if any). Due to this, the
+argument to @option{--run} may not use traditional @command{tar}
+option syntax, i.e. the following is wrong:
+
address@hidden
+# Wrong!
+genfile --run 'tar cf foo bar'
address@hidden smallexample
+
address@hidden
+
+Use the following syntax instead:
+
address@hidden
+genfile --run 'tar -cf foo bar'
address@hidden smallexample
+
+ The rest of command line after @option{--run} or its equivalent
+specifies checkpoint values and actions to be executed upon reaching
+them. Checkpoint values are introduced with @option{--checkpoint}
+command line option. Argument to this option is the number of
+checkpoint in decimal.
+
+ Any number of @dfn{actions} may be specified after a
+checkpoint. Available actions are
+
address@hidden @option
address@hidden --cut @var{file}
address@hidden --truncate @var{file}
+ Truncate @var{file} to the size specified by previous
address@hidden option (or 0, if it is not given).
+
address@hidden --append @var{file}
+ Append data to @var{file}. The size of data and its pattern are
+given by previous @option{--length} and @option{pattern} options.
+
address@hidden --touch @var{file}
+ Update the access and modification times of @var{file}. These
+timestamps are changed to the current time, unless @option{--date}
+option was given, in which case they are changed to the specified
+time. Argument to @option{--date} option is a date specification in
+an almost arbitrary format (@pxref{Date input formats}).
+
address@hidden --exec @var{command}
+ Execute given shell command.
+
address@hidden table
+
+ Option @option{--verbose} instructs @command{genfile} to print on
+standard output notifications about checkpoints being executed and to
+verbosely describe exit status of the command.
+
+ While the command is being executed its standard output remains
+connected to descriptor 1. All messages it prints to file descriptor
+2, except checkpoint notifications, are forwarded to standard
+error.
+
+ @command{Genfile} exits with the exit status of the executed command.
+
address@hidden Free Software Needs Free Documentation
address@hidden Free Software Needs Free Documentation
address@hidden free documentation
+
+The biggest deficiency in the free software community today is not in
+the software---it is the lack of good free documentation that we can
+include with the free software. Many of our most important
+programs do not come with free reference manuals and free introductory
+texts. Documentation is an essential part of any software package;
+when an important free software package does not come with a free
+manual and a free tutorial, that is a major gap. We have many such
+gaps today.
+
+Consider Perl, for instance. The tutorial manuals that people
+normally use are non-free. How did this come about? Because the
+authors of those manuals published them with restrictive terms---no
+copying, no modification, source files not available---which exclude
+them from the free software world.
+
+That wasn't the first time this sort of thing happened, and it was far
+from the last. Many times we have heard a GNU user eagerly describe a
+manual that he is writing, his intended contribution to the community,
+only to learn that he had ruined everything by signing a publication
+contract to make it non-free.
+
+Free documentation, like free software, is a matter of freedom, not
+price. The problem with the non-free manual is not that publishers
+charge a price for printed copies---that in itself is fine. (The Free
+Software Foundation sells printed copies of manuals, too.) The
+problem is the restrictions on the use of the manual. Free manuals
+are available in source code form, and give you permission to copy and
+modify. Non-free manuals do not allow this.
+
+The criteria of freedom for a free manual are roughly the same as for
+free software. Redistribution (including the normal kinds of
+commercial redistribution) must be permitted, so that the manual can
+accompany every copy of the program, both on-line and on paper.
+
+Permission for modification of the technical content is crucial too.
+When people modify the software, adding or changing features, if they
+are conscientious they will change the manual too---so they can
+provide accurate and clear documentation for the modified program. A
+manual that leaves you no choice but to write a new manual to document
+a changed version of the program is not really available to our
+community.
+
+Some kinds of limits on the way modification is handled are
+acceptable. For example, requirements to preserve the original
+author's copyright notice, the distribution terms, or the list of
+authors, are ok. It is also no problem to require modified versions
+to include notice that they were modified. Even entire sections that
+may not be deleted or changed are acceptable, as long as they deal
+with nontechnical topics (like this one). These kinds of restrictions
+are acceptable because they don't obstruct the community's normal use
+of the manual.
+
+However, it must be possible to modify all the @emph{technical}
+content of the manual, and then distribute the result in all the usual
+media, through all the usual channels. Otherwise, the restrictions
+obstruct the use of the manual, it is not free, and we need another
+manual to replace it.
+
+Please spread the word about this issue. Our community continues to
+lose manuals to proprietary publishing. If we spread the word that
+free software needs free reference manuals and free tutorials, perhaps
+the next person who wants to contribute by writing documentation will
+realize, before it is too late, that only free manuals contribute to
+the free software community.
+
+If you are writing documentation, please insist on publishing it under
+the GNU Free Documentation License or another free documentation
+license. Remember that this decision requires your approval---you
+don't have to let the publisher decide. Some commercial publishers
+will use a free license if you insist, but they will not propose the
+option; it is up to you to raise the issue and say firmly that this is
+what you want. If the publisher you are dealing with refuses, please
+try other publishers. If you're not sure whether a proposed license
+is free, write to @email{licensing@@gnu.org}.
+
+You can encourage commercial publishers to sell more free, copylefted
+manuals and tutorials by buying them, and particularly by buying
+copies from the publishers that paid for their writing or for major
+improvements. Meanwhile, try to avoid buying non-free documentation
+at all. Check the distribution terms of a manual before you buy it,
+and insist that whoever seeks your business must respect your freedom.
+Check the history of the book, and try reward the publishers that have
+paid or pay the authors to work on it.
+
+The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
address@hidden://www.fsf.org/doc/other-free-books.html}.
+
address@hidden Copying This Manual
address@hidden Copying This Manual
+
address@hidden
+* GNU Free Documentation License:: License for copying this manual
address@hidden menu
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.2, November 2002
+
address@hidden
+Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
+51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
address@hidden Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
address@hidden for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
address@hidden
+Preserve any Warranty Disclaimers.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with...Texts.'' line with this:
+
address@hidden
address@hidden
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
address@hidden group
address@hidden smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden Local Variables:
address@hidden ispell-local-pdict: "ispell-dict"
address@hidden End:
+
+
address@hidden Index of Command Line Options
address@hidden Index of Command Line Options
+
+This appendix contains an index of all @acronym{GNU} @command{tar} long
command line
+options. The options are listed without the preceeding double-dash.
+For a cross-reference of short command line options, @ref{Short Option
Summary}.
+
address@hidden op
+
address@hidden Index
address@hidden Index
+
address@hidden cp
+
address@hidden
address@hidden
address@hidden
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Texi2html-cvs] texi2html/test/tar_manual res/tar/tar.2 res/tar...,
Patrice Dumas <=