[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Texi2html-cvs] texi2html ChangeLog NEWS texi2html.init texi2ht...
|
From: |
Patrice Dumas |
|
Subject: |
[Texi2html-cvs] texi2html ChangeLog NEWS texi2html.init texi2ht... |
|
Date: |
Sun, 06 Aug 2006 21:12:39 +0000 |
CVSROOT: /cvsroot/texi2html
Module name: texi2html
Changes by: Patrice Dumas <pertusus> 06/08/06 21:12:37
Modified files:
. : ChangeLog NEWS texi2html.init texi2html.pl
Tests : Makefile.am Makefile.in test.sh
doc : stamp-vti texi2html.html version.texi
Added files:
Tests/macros : quote-args.txi
Tests/macros_res: quote-args.2 quote-args.html
quote-args.passfirst quote-args.passtexi
Tests/node_in_chapter_index_split_res: index.html
Tests/tar_res : tar.2 tar.html tar.passfirst tar.passtexi
Tests/tar_texi : config.texi dumpdir.texi fdl.texi
freemanuals.texi genfile.texi getdate.texi
header.texi intern.texi rendition.texi
snapshot.texi sparse.texi tar.texi value.texi
version.texi
Log message:
* texi2html.pl, texi2html.init: accept - in @-command names.
ignore @allow-recursion and @quote-arg.
In macro args parsing, a comma in brace is protected.
Rewrite index names handling to be simpler and
accept more than one prefix for an index name. The main
hash has now index names as key instead of prefixes.
* Tests/*: add the tar manual.
add macros/quote-args.txi from the makeinfo test suite.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texi2html/ChangeLog?cvsroot=texi2html&r1=1.253&r2=1.254
http://cvs.savannah.gnu.org/viewcvs/texi2html/NEWS?cvsroot=texi2html&r1=1.55&r2=1.56
http://cvs.savannah.gnu.org/viewcvs/texi2html/texi2html.init?cvsroot=texi2html&r1=1.109&r2=1.110
http://cvs.savannah.gnu.org/viewcvs/texi2html/texi2html.pl?cvsroot=texi2html&r1=1.175&r2=1.176
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/Makefile.am?cvsroot=texi2html&r1=1.18&r2=1.19
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/Makefile.in?cvsroot=texi2html&r1=1.38&r2=1.39
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/test.sh?cvsroot=texi2html&r1=1.62&r2=1.63
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/macros/quote-args.txi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/macros_res/quote-args.2?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/macros_res/quote-args.html?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/macros_res/quote-args.passfirst?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/macros_res/quote-args.passtexi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/node_in_chapter_index_split_res/index.html?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_res/tar.2?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_res/tar.html?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_res/tar.passfirst?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_res/tar.passtexi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/config.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/dumpdir.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/fdl.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/freemanuals.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/genfile.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/getdate.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/header.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/intern.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/rendition.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/snapshot.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/sparse.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/tar.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/value.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/Tests/tar_texi/version.texi?cvsroot=texi2html&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/texi2html/doc/stamp-vti?cvsroot=texi2html&r1=1.39&r2=1.40
http://cvs.savannah.gnu.org/viewcvs/texi2html/doc/texi2html.html?cvsroot=texi2html&r1=1.42&r2=1.43
http://cvs.savannah.gnu.org/viewcvs/texi2html/doc/version.texi?cvsroot=texi2html&r1=1.39&r2=1.40
Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/texi2html/texi2html/ChangeLog,v
retrieving revision 1.253
retrieving revision 1.254
diff -u -b -r1.253 -r1.254
--- ChangeLog 5 Aug 2006 12:09:22 -0000 1.253
+++ ChangeLog 6 Aug 2006 21:12:36 -0000 1.254
@@ -1,3 +1,14 @@
+2006-08-06 Patrice Dumas <address@hidden>
+
+ * texi2html.pl, texi2html.init: accept - in @-command names.
+ ignore @allow-recursion and @quote-arg.
+ In macro args parsing, a comma in brace is protected.
+ Rewrite index names handling to be simpler and
+ accept more than one prefix for an index name. The main
+ hash has now index names as key instead of prefixes.
+ * Tests/*: add the tar manual.
+ add macros/quote-args.txi from the makeinfo test suite.
+
2006-08-05 Patrice Dumas <address@hidden>
* texi2html.pl, texi2html.init: use the same code for file
Index: NEWS
===================================================================
RCS file: /cvsroot/texi2html/texi2html/NEWS,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -b -r1.55 -r1.56
--- NEWS 5 Aug 2006 09:24:44 -0000 1.55
+++ NEWS 6 Aug 2006 21:12:36 -0000 1.56
@@ -8,7 +8,8 @@
* Transliterate accented characters in file names. Use Text::Unidecode
if detected.
-* Handle @frenchspacing, @tie and @indent.
+* Handle @frenchspacing, @tie, @indent and the obsolete @allow-recursion
+ and @quote-arg.
* Use more numeric entities, especially for accented letters.
@@ -57,6 +58,11 @@
* avoid menu entry and description redundancy in the formatting function
and not in the main program.
+* accept - in @-command names (compatibility with makeinfo)
+
+* in user-defined macro arguments a comma in brace is escaped (compatibility
+ with makeinfo from texinfo 4.8.90)
+
* BUG FIXES
---------
Index: texi2html.init
===================================================================
RCS file: /cvsroot/texi2html/texi2html/texi2html.init,v
retrieving revision 1.109
retrieving revision 1.110
diff -u -b -r1.109 -r1.110
--- texi2html.init 5 Aug 2006 09:24:44 -0000 1.109
+++ texi2html.init 6 Aug 2006 21:12:36 -0000 1.110
@@ -12,7 +12,7 @@
# Afterwards, load the file with command-line
# option -init-file <your_init_file>
#
-# $Id: texi2html.init,v 1.109 2006/08/05 09:24:44 pertusus Exp $
+# $Id: texi2html.init,v 1.110 2006/08/06 21:12:36 pertusus Exp $
######################################################################
# The following variables can also be set by command-line options
@@ -2986,6 +2986,9 @@
'documentencoding' => {'arg' => 1}, # makeinfo ignore the whole line
# ???
'filbreak' => {},
+ # obsolete @-commands
+ 'quote-arg' => {},
+ 'allow-recursion' => {},
);
my %misc_command_old = (
# not needed for formatting
Index: texi2html.pl
===================================================================
RCS file: /cvsroot/texi2html/texi2html/texi2html.pl,v
retrieving revision 1.175
retrieving revision 1.176
diff -u -b -r1.175 -r1.176
--- texi2html.pl 5 Aug 2006 12:09:22 -0000 1.175
+++ texi2html.pl 6 Aug 2006 21:12:36 -0000 1.176
@@ -59,7 +59,7 @@
#--##########################################################################
# CVS version:
-# $Id: texi2html.pl,v 1.175 2006/08/05 12:09:22 pertusus Exp $
+# $Id: texi2html.pl,v 1.176 2006/08/06 21:12:36 pertusus Exp $
# Homepage:
my $T2H_HOMEPAGE = "http://www.nongnu.org/texi2html/";;
@@ -840,7 +840,7 @@
# variables which might be redefined by the user but aren't likely to be
# they seem to be in the main namespace
use vars qw(
-$index_properties
+%index_names
%predefined_index
%valid_index
%sec2level
@@ -969,24 +969,26 @@
#
# pre-defined indices
#
-$index_properties =
+
+my %index_prefix_to_name = ();
+
+%index_names =
+(
+ 'cp' => { 'prefix' => ['cp','c']},
+ 'fn' => { 'prefix' => ['fn', 'f'], code => 1},
+ 'vr' => { 'prefix' => ['vr', 'v'], code => 1},
+ 'ky' => { 'prefix' => ['ky', 'k'], code => 1},
+ 'pg' => { 'prefix' => ['pg', 'p'], code => 1},
+ 'tp' => { 'prefix' => ['tp', 't'], code => 1}
+);
+
+foreach my $name(keys(%index_names))
{
- 'c' => { name => 'cp'},
- 'f' => { name => 'fn', code => 1},
- 'v' => { name => 'vr', code => 1},
- 'k' => { name => 'ky', code => 1},
- 'p' => { name => 'pg', code => 1},
- 't' => { name => 'tp', code => 1}
-};
-
-# FIXME valid_index and predefined_index aren't used.
-foreach my $valid_key(keys(%$index_properties))
-{
- my $name = $index_properties->{$valid_key};
- $predefined_index{$name} = $valid_key;
- $valid_index{$valid_key} = 1;
- $forbidden_index_name{$valid_key} = 1;
- $forbidden_index_name{$name} = 1;
+ foreach my $prefix (@{$index_names{$name}->{'prefix'}})
+ {
+ $forbidden_index_name{$prefix} = 1;
+ $index_prefix_to_name{$prefix} = $name;
+ }
}
foreach my $other_forbidden_index_name ('info','ps','pdf','htm',
@@ -3724,25 +3726,23 @@
{
if ($line =~ /^\s+(\w+)\s+(\w+)/)
{
- my $from = $1;
- my $to = $2;
- my $prefix_from = index_name2prefix($from);
- my $prefix_to = index_name2prefix($to);
- echo_error ("unknown from index name $from in address@hidden",
$line_nr)
- unless $prefix_from;
- echo_error ("unknown to index name $to in address@hidden",
$line_nr)
- unless $prefix_to;
- if ($prefix_from and $prefix_to)
+ my $index_from = $1;
+ my $index_to = $2;
+ echo_error ("unknown from index name $index_from in
address@hidden", $line_nr)
+ unless $index_names{$index_from};
+ echo_error ("unknown to index name $index_to in address@hidden",
$line_nr)
+ unless $index_names{$index_to};
+ if ($index_names{$index_from} and $index_names{$index_to})
{
if ($macro eq 'syncodeindex')
{
-
$index_properties->{$prefix_to}->{'from_code'}->{$prefix_from} = 1;
+
$index_names{$index_to}->{'associated_indices_code'}->{$index_from} = 1;
}
else
{
- $index_properties->{$prefix_to}->{'from'}->{$prefix_from}
= 1;
+
$index_names{$index_to}->{'associated_indices'}->{$index_from} = 1;
}
- push @{$Texi2HTML::THISDOC{$macro}},
[$prefix_from,$prefix_to];
+ push @{$Texi2HTML::THISDOC{$macro}}, [$index_from,$index_to];
}
}
else
@@ -3761,8 +3761,9 @@
}
else
{
- $index_properties->{$name}->{'name'} = $name;
- $index_properties->{$name}->{'code'} = 1 if $macro eq
'defcodeindex';
+ @{$index_names{$name}->{'prefix'}} = ($name);
+ $index_names{$name}->{'code'} = 1 if $macro eq 'defcodeindex';
+ $index_prefix_to_name{$name} = $name;
push @{$Texi2HTML::THISDOC{$macro}}, $name;
}
}
@@ -4099,13 +4100,6 @@
my %printed_indices = (); # value is true for an index name not empty and
# printed
-
-sub element_is_top($)
-{
- my $element = shift;
- return ($element eq $element_top or (defined($element->{'section_ref'})
and $element->{'section_ref'} eq $element_top) or
(defined($element->{'node_ref'}) and $element->{'node_ref'} eq $element_top));
-}
-
# find next, prev, up, back, forward, fastback, fastforward
# find element id and file
# split index pages
@@ -4457,7 +4451,7 @@
# nodes are attached to the section preceding them if not allready
# associated with a section
# here we don't set @{$element->{'nodes'}} since it may be changed
- # below if split by indices. There fore we only set
+ # below if split by indices. Therefore we only set
# @{$element->{'all_elements'}} with all the elements associated
# with an element output, in the right order
print STDERR "# Find the section associated with each node\n"
@@ -5232,7 +5226,7 @@
$is_top = "top";
$element->{'file'} = $docu_top;
}
- elsif ($Texi2HTML::Config::NODE_FILES)# and
($Texi2HTML::Config::SPLIT eq 'node'))
+ elsif ($Texi2HTML::Config::NODE_FILES)
{
if ($new_file)
{
@@ -5566,7 +5560,7 @@
my $element = shift;
my $use_section_id = shift;
my $command = shift;
- unless (exists ($index_properties->{$prefix}))
+ unless ($index_prefix_to_name{$prefix})
{
echo_error ("Undefined index command: ${prefix}index", $line_nr);
$key = '';
@@ -5616,53 +5610,6 @@
push @index_labels, $index_entry unless ($place eq $region_place);
}
-# returns prefix of @?index command associated with 2 letters prefix name
-# for example returns 'c' for 'cp'
-sub index_name2prefix($)
-{
- my $name = shift;
- my $prefix;
-
- for $prefix (keys %$index_properties)
- {
- return $prefix if ($index_properties->{$prefix}->{'name'} eq $name);
- }
- return undef;
-}
-
-# get all the entries (for all the prefixes) in the $normal and $code
-# references, formatted with @code{code } if it is a $code entry.
-sub get_index_entries($$)
-{
- my $normal = shift;
- my $code = shift;
- my $entries = {};
- foreach my $prefix (keys %$normal)
- {
- for my $key (keys %{$index->{$prefix}})
- {
- $entries->{$key} = $index->{$prefix}->{$key};
- }
- }
-
- if (defined($code))
- {
- foreach my $prefix (keys %$code)
- {
- unless (exists $normal->{$prefix})
- {
- foreach my $key (keys %{$index->{$prefix}})
- {
- $entries->{$key} = $index->{$prefix}->{$key};
- # use @code for code style index entry
- $entries->{$key}->{'entry'} =
"address@hidden>{$key}->{entry}}";
- }
- }
- }
- }
- return $entries;
-}
-
# sort according to cmp if both $a and $b are alphabetical or non
alphabetical,
# otherwise the alphabetical is ranked first
sub by_alpha
@@ -5751,32 +5698,64 @@
return $pages;
}
+# return the page and the entries. Cache the result in %indices.
sub get_index($;$)
{
- my $name = shift;
+ my $index_name = shift;
my $line_nr = shift;
- return (@{$indices{$name}}) if ($indices{$name});
- my $prefix = index_name2prefix($name);
- unless ($prefix)
+
+ return (@{$indices{$index_name}}) if ($indices{$index_name});
+
+ unless (exists($index_names{$index_name}))
{
- echo_error ("Bad index name: $name", $line_nr);
- #warn "$ERROR Bad index name: $name\n";
+ echo_error ("Bad index name: $index_name", $line_nr);
return;
}
- if ($index_properties->{$prefix}->{'code'})
+ # add the index name itself to the index names searched for index
+ # prefixes. Only those found associated by synindex or syncodeindex are
+ # allready there (unless this code has allready been called).
+ if ($index_names{$index_name}->{'code'})
{
- $index_properties->{$prefix}->{'from_code'}->{$prefix} = 1;
+ $index_names{$index_name}->{'associated_indices_code'}->{$index_name}
= 1;
}
else
{
- $index_properties->{$prefix}->{'from'}->{$prefix}= 1;
+ $index_names{$index_name}->{'associated_indices'}->{$index_name} = 1;
+ }
+
+ # find all the index names associated with the prefixes and then
+ # all the entries associated with each prefix
+ my $entries = {};
+ foreach my $associated_indice(keys
%{$index_names{$index_name}->{'associated_indices'}})
+ {
+ foreach my $prefix(@{$index_names{$associated_indice}->{'prefix'}})
+ {
+ foreach my $key (keys %{$index->{$prefix}})
+ {
+ $entries->{$key} = $index->{$prefix}->{$key};
+ }
+ }
+ }
+
+ foreach my $associated_indice (keys
%{$index_names{$index_name}->{'associated_indices_code'}})
+ {
+ unless (exists
($index_names{$index_name}->{'associated_indices'}->{$associated_indice}))
+ {
+ foreach my $prefix
(@{$index_names{$associated_indice}->{'prefix'}})
+ {
+ foreach my $key (keys (%{$index->{$prefix}}))
+ {
+ $entries->{$key} = $index->{$prefix}->{$key};
+ # use @code for code style index entry
+ $entries->{$key}->{'entry'} =
"address@hidden>{$key}->{entry}}";
+ }
+ }
+ }
}
- my $entries = get_index_entries($index_properties->{$prefix}->{'from'},
- $index_properties->{$prefix}->{'from_code'});
return unless %$entries;
my $pages = get_index_pages($entries);
- $indices{$name} = [ $pages, $entries ];
+ $indices{$index_name} = [ $pages, $entries ];
return ($pages, $entries);
}
@@ -6274,7 +6253,7 @@
s/\s+(\w+)\s*//;
my $name = $1;
close_paragraph(\$text, address@hidden, \%state);
- next if (!index_name2prefix($name) or $empty_indices{$name});
+ next if (!$index_names{$name} or $empty_indices{$name});
$printed_indices{$name} = 1;
print STDERR "print index $name($index_nr) in
`$element->{'texi'}', element->{'indices'}: $element->{'indices'},\n" if
($T2H_DEBUG & $DEBUG_ELEMENTS or $T2H_DEBUG & $DEBUG_INDEX);
print STDERR "element->{'indices'}->[index_nr]:
$element->{'indices'}->[$index_nr] (@{$element->{'indices'}->[$index_nr]})\n"
if ($T2H_DEBUG & $DEBUG_ELEMENTS or $T2H_DEBUG & $DEBUG_INDEX);
@@ -6748,7 +6727,8 @@
sub next_tag($)
{
my $line = shift;
- if ($line =~ /^\s*\@(["'address@hidden,\.!\?\s\*\-\^`=:\|\/])/o or $line
=~ /^\s*\@([a-zA-Z]\w*)(address@hidden)/ or $line =~ /^\s*\@([a-zA-Z]\w*)$/)
+ # macro_regexp
+ if ($line =~ /^\s*\@(["'address@hidden,\.!\?\s\*\-\^`=:\|\/])/o or $line
=~ /^\s*\@([a-zA-Z][\w-]*)(address@hidden)/ or $line =~
/^\s*\@([a-zA-Z][\w-]*)$/)
{
return ($1);
}
@@ -7310,9 +7290,11 @@
my $line = shift;
my $tag = shift;
my $command = 'asis';
- if (($line =~ /^\s*\@([A-Za-z]\w*)(\{\})?$/ or $line =~
/^\s*\@([A-Za-z]\w*)(\{\})?\s/) and ($::things_map_ref->{$1} or
defined($::style_map_ref->{$1})))
+ # macro_regexp
+ if (($line =~ /^\s*\@([A-Za-z][\w-]*)(\{\})?$/ or $line =~
/^\s*\@([A-Za-z][\w-]*)(\{\})?\s/) and ($::things_map_ref->{$1} or
defined($::style_map_ref->{$1})))
{
- $line =~ s/^\s*\@([A-Za-z]\w*)(\{\})?\s*//;
+ # macro_regexp
+ $line =~ s/^\s*\@([A-Za-z][\w-]*)(\{\})?\s*//;
$command = $1;
}
return ('', $command) if ($line =~ /^\s*$/);
@@ -8498,11 +8480,18 @@
}
}
elsif ($2 eq ',')
+ { # in texinfo 4.8.90 a comma in braces is protected
+ if ($state->{'macro_depth'} > 1)
+ {
+ $state->{'macro_args'}->[-1] .= ',';
+ }
+ else
{ # separate args
print STDERR "# macro call: new arg\n" if ($T2H_DEBUG &
$DEBUG_MACROS);
s/^\s*//o;
push @{$state->{'macro_args'}}, '';
}
+ }
elsif ($2 eq '}')
{ # balanced } ends the macro call, otherwise it is in the arg
$state->{'macro_depth'}--;
@@ -8635,7 +8624,8 @@
# an @end tag
- if (s/^(address@hidden)address@hidden(\s+)([a-zA-Z]\w*)//)
+ # macro_regexp
+ if (s/^(address@hidden)address@hidden(\s+)([a-zA-Z][\w-]*)//)
{
my $leading_text = $1;
my $space = $2;
@@ -8671,7 +8661,8 @@
}
next;
}
- elsif
(s/^(address@hidden)\@(["'address@hidden,\.!\?\s\*\-\^`=:\|\/])//o or
s/^(address@hidden)\@([a-zA-Z]\w*)(address@hidden)/$3/o or
s/^(address@hidden)\@([a-zA-Z]\w*)$//o)
+ # macro_regexp
+ elsif
(s/^(address@hidden)\@(["'address@hidden,\.!\?\s\*\-\^`=:\|\/])//o or
s/^(address@hidden)\@([a-zA-Z][\w-]*)(address@hidden)/$3/o or
s/^(address@hidden)\@([a-zA-Z][\w-]*)$//o)
{# ARG_EXPANSION
add_prev($text, $stack, $1) unless $state->{'ignored'};
my $macro = $2;
@@ -8738,7 +8729,7 @@
elsif ($macro =~ /^r?macro$/)
{ #FIXME what to do if 'arg_expansion' is true (ie within another
# macro call arguments?
- if (/^\s+(\w+)\s*(.*)/)
+ if (/^\s+(\w[\w-]*)\s*(.*)/)
{
my $name = $1;
unless ($state->{'ignored'})
@@ -9249,7 +9240,8 @@
{
delete $state->{'after_element'};
}
- if (s/^(address@hidden)address@hidden([a-zA-Z]\w*)//)
+ # macro_regexp
+ if (s/^(address@hidden)address@hidden([a-zA-Z][\w-]*)//)
{
add_prev($text, $stack, $1);
my $end_tag = $2;
@@ -9305,7 +9297,8 @@
next;
}
#elsif
(s/^(address@hidden)\@([a-zA-Z]\w*|["'address@hidden,\.!\?\s\*\-\^`=:\/])//o)
- elsif
(s/^(address@hidden)\@(["'address@hidden,\.!\?\s\*\-\^`=:\|\/])//o or
s/^(address@hidden)\@([a-zA-Z]\w*)(address@hidden)/$3/o or
s/^(address@hidden)\@([a-zA-Z]\w*)$//o)
+ # macro_regexp
+ elsif
(s/^(address@hidden)\@(["'address@hidden,\.!\?\s\*\-\^`=:\|\/])//o or
s/^(address@hidden)\@([a-zA-Z][\w-]*)(address@hidden)/$3/o or
s/^(address@hidden)\@([a-zA-Z][\w-]*)$//o)
{
add_prev($text, $stack, $1);
my $macro = $2;
@@ -9775,19 +9768,21 @@
}
# We handle now the end tags
- if ($state->{'keep_texi'} and
s/^(address@hidden)address@hidden([a-zA-Z]\w*)//)
+ # macro_regexp
+ if ($state->{'keep_texi'} and
s/^(address@hidden)address@hidden([a-zA-Z][\w-]*)//)
{
my $end_tag = $2;
add_prev($text, $stack, $1 . "address@hidden $end_tag");
next;
}
- elsif ($state->{'remove_texi'} and
s/^(address@hidden)address@hidden([a-zA-Z]\w*)//)
+ # macro_regexp
+ elsif ($state->{'remove_texi'} and
s/^(address@hidden)address@hidden([a-zA-Z][\w-]*)//)
{
add_prev($text, $stack, $1);
next;
}
-
- if (s/^([^{}@,]*)address@hidden([a-zA-Z]\w*)\s//o or
s/^([^{}@,]*)address@hidden([a-zA-Z]\w*)$//o)
+ # macro_regexp
+ if (s/^([^{}@,]*)address@hidden([a-zA-Z][\w-]*)\s//o or
s/^([^{}@,]*)address@hidden([a-zA-Z][\w-]*)$//o)
{
add_prev($text, $stack, do_text($1, $state));
my $end_tag = $2;
@@ -9922,7 +9917,8 @@
}
# This is a macro
#elsif
(s/^(address@hidden)\@([a-zA-Z]\w*|["'address@hidden,\.!\?\s\*\-\^`=:\/])//o)
- elsif (s/^([^{},@]*)\@(["'address@hidden,\.!\?\s\*\-\^`=:\|\/])//o or
s/^([^{}@,]*)\@([a-zA-Z]\w*)(address@hidden)/$3/o or
s/^([^{},@]*)\@([a-zA-Z]\w*)$//o)
+ # macro_regexp
+ elsif (s/^([^{},@]*)\@(["'address@hidden,\.!\?\s\*\-\^`=:\|\/])//o or
s/^([^{}@,]*)\@([a-zA-Z][\w-]*)(address@hidden)/$3/o or
s/^([^{},@]*)\@([a-zA-Z][\w-]*)$//o)
{
add_prev($text, $stack, do_text($1, $state));
my $macro = $2;
@@ -11771,7 +11767,9 @@
print STDERR "[(index $command) $entry->{'entry'} $entry->{'label'}]\n"
if ($T2H_DEBUG & $DEBUG_INDEX);
- return &$Texi2HTML::Config::index_entry_label ($entry->{'label'},
$state->{'preformatted'}, substitute_line($entry->{'entry'}),
$index_properties->{$entry->{'prefix'}}->{'name'},$command);
+ return &$Texi2HTML::Config::index_entry_label ($entry->{'label'},
$state->{'preformatted'}, substitute_line($entry->{'entry'}),
+ $index_prefix_to_name{$prefix},
+ $command);
}
# decompose a decimal number on a given base. The algorithm looks like
@@ -11968,11 +11966,9 @@
}
if ($Texi2HTML::Config::IDX_SUMMARY)
{
- foreach my $entry (keys(%$index_properties))
+ foreach my $entry (keys(%index_names))
{
- my $name = $index_properties->{$entry}->{'name'};
- do_index_summary_file($name)
- unless ($empty_indices{$name});
+ do_index_summary_file($entry) unless ($empty_indices{$entry});
}
}
do_node_files() if ($Texi2HTML::Config::NODE_FILES);
Index: Tests/Makefile.am
===================================================================
RCS file: /cvsroot/texi2html/texi2html/Tests/Makefile.am,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -b -r1.18 -r1.19
--- Tests/Makefile.am 4 Aug 2006 12:51:01 -0000 1.18
+++ Tests/Makefile.am 6 Aug 2006 21:12:37 -0000 1.19
@@ -4,7 +4,7 @@
node_translit_no_unidecode node_utf8_translit \
node_utf8_translit_no_unidecode index_split_nodes \
more_before_top_section node_footnote node_in_chapter_index_split \
- index_nodes
+ index_nodes tar
#check-local:
Index: Tests/Makefile.in
===================================================================
RCS file: /cvsroot/texi2html/texi2html/Tests/Makefile.in,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -b -r1.38 -r1.39
--- Tests/Makefile.in 4 Aug 2006 12:51:01 -0000 1.38
+++ Tests/Makefile.in 6 Aug 2006 21:12:37 -0000 1.39
@@ -123,7 +123,7 @@
node_translit_no_unidecode node_utf8_translit \
node_utf8_translit_no_unidecode index_split_nodes \
more_before_top_section node_footnote node_in_chapter_index_split \
- index_nodes
+ index_nodes tar
all: all-am
Index: Tests/test.sh
===================================================================
RCS file: /cvsroot/texi2html/texi2html/Tests/test.sh,v
retrieving revision 1.62
retrieving revision 1.63
diff -u -b -r1.62 -r1.63
--- Tests/test.sh 4 Aug 2006 12:51:01 -0000 1.62
+++ Tests/test.sh 6 Aug 2006 21:12:37 -0000 1.63
@@ -186,6 +186,7 @@
test_texi macros ifset_in_macro.texi "-D notes -prefix set_ifset_in_macro" 0
texi set_ifset_in_macro
test_texi macros not_ifset_text.texi
test_texi macros bib-example.texi
+test_texi macros quote-args.txi "" 0 txi
test_texi sectionning
test_texi sectionning sectionning.texi "-init test_directions.init -prefix
sectionning_directions" 0 texi sectionning_directions
test_texi sectionning test_include.texi
@@ -292,5 +293,6 @@
test_texi texinfo texinfo.txi "-split chapter -ifinfo -output ." 0 txi texinfo
#ignore_tags
test_texi nodes_texinfo ../texinfo/texinfo.txi "-split node -node-files
-ifinfo -output . -I ../texinfo" 0 txi texinfo #ignore_tags
test_texi ccvs cvs.texinfo "-split chapter -output ." 0 texinfo
+test_texi tar ../tar_texi/tar.texi
#test_texi singular ../singular_texi/singular.tex "-init-file
../singular_texi/t2h_singular.init -l2h -short-ext -prefix sing -top-file
index.htm -noVerbose -output ." 0 tex sing #ignore_tags
#test_texi singular_httex ../singular_texi/singular.tex "-init-file
../singular_texi/t2h_singular.init -init ../../examples/tex4ht.init -short-ext
-prefix sing -top-file index.htm -noVerbose -output ." 0 tex sing #ignore_tags
Index: doc/stamp-vti
===================================================================
RCS file: /cvsroot/texi2html/texi2html/doc/stamp-vti,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -b -r1.39 -r1.40
--- doc/stamp-vti 17 May 2006 01:51:46 -0000 1.39
+++ doc/stamp-vti 6 Aug 2006 21:12:37 -0000 1.40
@@ -1,4 +1,4 @@
address@hidden UPDATED 17 May 2006
address@hidden UPDATED-MONTH May 2006
address@hidden UPDATED 5 August 2006
address@hidden UPDATED-MONTH August 2006
@set EDITION 1.77
@set VERSION 1.77
Index: doc/texi2html.html
===================================================================
RCS file: /cvsroot/texi2html/texi2html/doc/texi2html.html,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -b -r1.42 -r1.43
--- doc/texi2html.html 5 Aug 2006 09:24:46 -0000 1.42
+++ doc/texi2html.html 6 Aug 2006 21:12:37 -0000 1.43
@@ -131,7 +131,7 @@
<a name="SEC_Top"></a>
-<p>This manual, last updated 17 May 2006, describes version 1.77
+<p>This manual, last updated 5 August 2006, describes version 1.77
of the <code>texi2html</code> Perl script which converts
<a href="http://www.texinfo.org";>Texinfo</a> into <a
href="http://w3c.org";>HTML</a>.
</p>
Index: doc/version.texi
===================================================================
RCS file: /cvsroot/texi2html/texi2html/doc/version.texi,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -b -r1.39 -r1.40
--- doc/version.texi 17 May 2006 01:51:46 -0000 1.39
+++ doc/version.texi 6 Aug 2006 21:12:37 -0000 1.40
@@ -1,4 +1,4 @@
address@hidden UPDATED 17 May 2006
address@hidden UPDATED-MONTH May 2006
address@hidden UPDATED 5 August 2006
address@hidden UPDATED-MONTH August 2006
@set EDITION 1.77
@set VERSION 1.77
Index: Tests/macros/quote-args.txi
===================================================================
RCS file: Tests/macros/quote-args.txi
diff -N Tests/macros/quote-args.txi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/macros/quote-args.txi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,20 @@
+\input texinfo
address@hidden
address@hidden quote-args.info
address@hidden Quote-args facility in macros
+
address@hidden cat{a,b}
+\a\\b\
address@hidden rmacro
+
address@hidden FIXME{a}
address@hidden: \a\}
address@hidden macro
+
address@hidden Top, , (dir), (dir)
+
address@hidden
address@hidden arguments, separated by commas, are processed here}
address@hidden@address@hidden@address@hidden@cat{na, to}, po}, co}, tu},
oto},tam}
address@hidden
+
Index: Tests/macros_res/quote-args.2
===================================================================
RCS file: Tests/macros_res/quote-args.2
diff -N Tests/macros_res/quote-args.2
Index: Tests/macros_res/quote-args.html
===================================================================
RCS file: Tests/macros_res/quote-args.html
diff -N Tests/macros_res/quote-args.html
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/macros_res/quote-args.html 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,59 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html401/loose.dtd";>
+<html>
+<!-- Created on a sunny day by texi2html -->
+<!--
+Written by: Lionel Cons <address@hidden> (original author)
+ Karl Berry <address@hidden>
+ Olaf Bachmann <address@hidden>
+ and many others.
+Maintained by: Many creative people.
+Send bugs and suggestions to <address@hidden>
+
+-->
+<head>
+<title>Quote-args facility in macros: Top</title>
+
+<meta name="description" content="Quote-args facility in macros: Top">
+<meta name="keywords" content="Quote-args facility in macros: Top">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="texi2html">
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<style type="text/css">
+<!--
+a.summary-letter {text-decoration: none}
+pre.display {font-family: serif}
+pre.format {font-family: serif}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+pre.smalldisplay {font-family: serif; font-size: smaller}
+pre.smallexample {font-size: smaller}
+pre.smallformat {font-family: serif; font-size: smaller}
+pre.smalllisp {font-size: smaller}
+span.roman {font-family:serif; font-weight:normal;}
+span.sansserif {font-family:sans-serif; font-weight:normal;}
+ul.toc {list-style: none}
+-->
+</style>
+
+
+</head>
+
+<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF"
vlink="#800080" alink="#FF0000">
+
+<a name="Top"></a>
+<h1 class="node"> Quote-args facility in macros
+ </h1>
+
+<p><strong>FIXME: Many arguments, separated by commas, are processed
here</strong>
+natopocotuototam
+</p><hr size="1">
+<p>
+ <font size="-1">
+ This document was generated by <em>a tester</em> on <em>a sunny day</em>
using <a href="http://www.nongnu.org/texi2html/";><em>texi2html</em></a>.
+ </font>
+ <br>
+
+</p>
+</body>
+</html>
Index: Tests/macros_res/quote-args.passfirst
===================================================================
RCS file: Tests/macros_res/quote-args.passfirst
diff -N Tests/macros_res/quote-args.passfirst
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/macros_res/quote-args.passfirst 6 Aug 2006 21:12:37 -0000
1.1
@@ -0,0 +1,12 @@
+quote-args.txi(,2) @smallbook
+quote-args.txi(,3) @setfilename quote-args.info
+quote-args.txi(,4) @settitle Quote-args facility in macros
+quote-args.txi(,5)
+quote-args.txi(,9)
+quote-args.txi(,13)
+quote-args.txi(,14) @node Top, , (dir), (dir)
+quote-args.txi(,15)
+quote-args.txi(,16) @noindent
+quote-args.txi(FIXME,17) @strong{FIXME: Many arguments, separated by commas,
are processed here}
+quote-args.txi(cat,18) natopocotuototam
+quote-args.txi(,19) @bye
Index: Tests/macros_res/quote-args.passtexi
===================================================================
RCS file: Tests/macros_res/quote-args.passtexi
diff -N Tests/macros_res/quote-args.passtexi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/macros_res/quote-args.passtexi 6 Aug 2006 21:12:37 -0000
1.1
@@ -0,0 +1,12 @@
+quote-args.txi(,2) @smallbook
+quote-args.txi(,3) @setfilename quote-args.info
+quote-args.txi(,4) @settitle Quote-args facility in macros
+quote-args.txi(,5)
+quote-args.txi(,9)
+quote-args.txi(,13)
+quote-args.txi(,14) @node Top, , (dir), (dir)
+quote-args.txi(,15)
+quote-args.txi(,16) @noindent
+quote-args.txi(FIXME,17) @strong{FIXME: Many arguments, separated by commas,
are processed here}quote-args.txi(FIXME,17)
+quote-args.txi(cat,18) natopocotuototamquote-args.txi(cat,18)
+quote-args.txi(,19) @bye
Index: Tests/node_in_chapter_index_split_res/index.html
===================================================================
RCS file: Tests/node_in_chapter_index_split_res/index.html
diff -N Tests/node_in_chapter_index_split_res/index.html
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/node_in_chapter_index_split_res/index.html 6 Aug 2006 21:12:37
-0000 1.1
@@ -0,0 +1,46 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html401/loose.dtd";>
+<html>
+<!-- Created on a sunny day by texi2html -->
+<!--
+Written by: Lionel Cons <address@hidden> (original author)
+ Karl Berry <address@hidden>
+ Olaf Bachmann <address@hidden>
+ and many others.
+Maintained by: Many creative people.
+Send bugs and suggestions to <address@hidden>
+
+-->
+<head>
+<title>Untitled Document: Top</title>
+
+<meta name="description" content="Untitled Document: Top">
+<meta name="keywords" content="Untitled Document: Top">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="texi2html">
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<style type="text/css">
+<!--
+a.summary-letter {text-decoration: none}
+pre.display {font-family: serif}
+pre.format {font-family: serif}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+pre.smalldisplay {font-family: serif; font-size: smaller}
+pre.smallexample {font-size: smaller}
+pre.smallformat {font-family: serif; font-size: smaller}
+pre.smalllisp {font-size: smaller}
+span.roman {font-family:serif; font-weight:normal;}
+span.sansserif {font-family:sans-serif; font-weight:normal;}
+ul.toc {list-style: none}
+-->
+</style>
+
+<meta http-equiv="Refresh" content="2;
url=node_in_chapter_index_split.html#Top">
+
+</head>
+
+<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF"
vlink="#800080" alink="#FF0000">
+
+<p>The node you are looking for is at <a
href="node_in_chapter_index_split.html#Top">Top</a>.</p>
+</body>
Index: Tests/tar_res/tar.2
===================================================================
RCS file: Tests/tar_res/tar.2
diff -N Tests/tar_res/tar.2
Index: Tests/tar_res/tar.html
===================================================================
RCS file: Tests/tar_res/tar.html
diff -N Tests/tar_res/tar.html
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_res/tar.html 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,18118 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html401/loose.dtd";>
+<html>
+<!--
+This manual is for GNU tar (version
+1.15.92, 26 June 2006), which creates and extracts files
+from archives.
+
+Copyright C 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
+2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+
+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."
+
+ -->
+<!-- Created on a sunny day by texi2html -->
+<!--
+Written by: Lionel Cons <address@hidden> (original author)
+ Karl Berry <address@hidden>
+ Olaf Bachmann <address@hidden>
+ and many others.
+Maintained by: Many creative people.
+Send bugs and suggestions to <address@hidden>
+
+-->
+<head>
+<title>GNU tar 1.15.92: GNU tar: an archiver tool</title>
+
+<meta name="description" content="GNU tar 1.15.92: GNU tar: an archiver tool">
+<meta name="keywords" content="GNU tar 1.15.92: GNU tar: an archiver tool">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="texi2html">
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<style type="text/css">
+<!--
+a.summary-letter {text-decoration: none}
+pre.display {font-family: serif}
+pre.format {font-family: serif}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+pre.smalldisplay {font-family: serif; font-size: smaller}
+pre.smallexample {font-size: smaller}
+pre.smallformat {font-family: serif; font-size: smaller}
+pre.smalllisp {font-size: smaller}
+span.roman {font-family:serif; font-weight:normal;}
+span.sansserif {font-family:sans-serif; font-weight:normal;}
+ul.toc {list-style: none}
+-->
+</style>
+
+
+</head>
+
+<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF"
vlink="#800080" alink="#FF0000">
+
+<a name="Top"></a>
+<a name="SEC_Top"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="settitle"><acronym>GNU</acronym> tar: an archiver tool</h1>
+
+
+<p>This manual is for <acronym>GNU</acronym> <code>tar</code> (version
+1.15.92, 26 June 2006), which creates and extracts files
+from archives.
+</p>
+<p>Copyright © 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
+2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+</p>
+<blockquote><p>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".
+</p>
+<p>(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.”
+</p></blockquote>
+
+<a name="IDX1"></a>
+<a name="IDX2"></a>
+
+<p>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.
+</p>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC1">1.
Introduction</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC8">2. Tutorial Introduction to
<code>tar</code></a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC32">3. Invoking
<acronym>GNU</acronym> <code>tar</code></a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC48">4. <acronym>GNU</acronym>
<code>tar</code> Operations</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC86">5. Performing Backups and
Restoring Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC97">6. Choosing Files and Names
for <code>tar</code></a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC113">7. Date input
formats</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC124">8. Controlling the Archive
Format</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC143">9. Tapes and Other Archive
Media</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Appendices
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC160">A.
Changes</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC161">B. Configuring Help
Summary</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC162">C. Tar
Internals</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC171">D.
Genfile</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC175">E. Free Software Needs
Free Documentation</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC176">F. Copying This
Manual</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC179">G. Index of Command Line
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC180">H.
Index</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+ --- The Detailed Node Listing ---
+
+Introduction
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC2">1.1 What
this Book Contains</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC3">1.2 Some
Definitions</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC4">1.3 What <code>tar</code>
Does</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC5">1.4 How <code>tar</code>
Archives are Named</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC6">1.5 <acronym>GNU</acronym>
<code>tar</code> Authors</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC7">1.6 Reporting bugs or
suggestions</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Tutorial Introduction to <code>tar</code>
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC9">2.1
Assumptions this Tutorial Makes</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC10">2.2 Stylistic
Conventions</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC11">2.3 Basic <code>tar</code>
Operations and Options</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC12">2.4 The Three Most
Frequently Used Operations</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC13">2.5 Two Frequently Used
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC17">2.6 How to Create
Archives</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC23">2.7 How to List
Archives</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC25">2.8 How to Extract Members
from an Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC31">2.9 Going Further Ahead in
this Manual</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Two Frequently Used Options
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC14">The
‘<samp>--file</samp>’ Option</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC15">The
‘<samp>--verbose</samp>’ Option</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC16">Getting Help: Using the
‘<samp>--help</samp>’ Option</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+How to Create Archives
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC18">2.6.1
Preparing a Practice Directory for Examples</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC19">2.6.2 Creating the
Archive</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC20">2.6.3 Running
‘<samp>--create</samp>’ with
‘<samp>--verbose</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC21">2.6.4 Short Forms with
‘<samp>create</samp>’</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC22">2.6.5 Archiving
Directories</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+How to List Archives
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC24">Listing the
Contents of a Stored Directory</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+How to Extract Members from an Archive
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC26">2.8.1
Extracting an Entire Archive</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC27">2.8.2 Extracting Specific
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC28">2.8.3 Extracting Files that
are Directories</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC29">2.8.4 Extracting Archives
from Untrusted Sources</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC30">2.8.5 Commands That Will
Fail</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Invoking <acronym>GNU</acronym> <code>tar</code>
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC33">3.1 General
Synopsis of <code>tar</code></a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC34">3.2 Using <code>tar</code>
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC35">3.3 The Three Option
Styles</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC40">3.4 All <code>tar</code>
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC44">3.5 <acronym>GNU</acronym>
<code>tar</code> documentation</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC45">3.6 Obtaining
<acronym>GNU</acronym> <code>tar</code> default
values</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC46">3.7 Checking
<code>tar</code> progress</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC47">3.8 Asking for Confirmation
During Operations</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+The Three Option Styles
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC36">3.3.1 Long
Option Style</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC37">3.3.2 Short Option
Style</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC38">3.3.3 Old Option
Style</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC39">3.3.4 Mixing Option
Styles</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+All <code>tar</code> Options
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC41">3.4.1
Operations</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC42">3.4.2 <code>tar</code>
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC43">3.4.3 Short Options Cross
Reference</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+<acronym>GNU</acronym> <code>tar</code> Operations
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC49">4.1 Basic
<acronym>GNU</acronym> <code>tar</code>
Operations</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC50">4.2 Advanced
<acronym>GNU</acronym> <code>tar</code>
Operations</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC60">4.3 Options Used by
‘<samp>--create</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC63">4.4 Options Used by
‘<samp>--extract</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC83">4.5 Backup
options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC84">4.6 Notable
<code>tar</code> Usages</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC85">4.7 Looking Ahead: The Rest
of this Manual</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Advanced <acronym>GNU</acronym> <code>tar</code> Operations
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC51">4.2.1 The
Five Advanced <code>tar</code> Operations</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC52">4.2.2 How to Add Files to
Existing Archives:
‘<samp>--append</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC55">4.2.3 Updating an
Archive</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC57">4.2.4 Combining Archives
with ‘<samp>--concatenate</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC58">4.2.5 Removing Archive
Members Using
‘<samp>--delete</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC59">4.2.6 Comparing Archive
Members with the File System</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+How to Add Files to Existing Archives: ‘<samp>--append</samp>’
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC53">4.2.2.1
Appending Files to an Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC54">4.2.2.2 Multiple Members
with the Same Name</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Updating an Archive
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC56">4.2.3.1 How
to Update an Archive Using
‘<samp>--update</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Options Used by ‘<samp>--create</samp>’
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC61">4.3.1
Overriding File Metadata</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC62">4.3.2 Ignore Fail
Read</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Options Used by ‘<samp>--extract</samp>’
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC64">4.4.1
Options to Help Read Archives</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC67">4.4.2 Changing How
<code>tar</code> Writes Files</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC80">4.4.3 Coping with Scarce
Resources</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Options to Help Read Archives
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC65">Reading
Full Records</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC66">Ignoring Blocks of
Zeros</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Changing How <code>tar</code> Writes Files
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC68">Options
Controlling the Overwriting of Existing Files</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC69">Overwrite Old
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC70">Keep Old
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC71">Keep Newer
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC72">Unlink
First</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC73">Recursive
Unlink</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC74">Setting Data Modification
Times</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC75">Setting Access
Permissions</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC76">Directory Modification
Times and Permissions</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC77">Writing to Standard
Output</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC78">Writing to an External
Program</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC79">Removing
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Coping with Scarce Resources
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC81">Starting
File</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC82">Same
Order</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Performing Backups and Restoring Files
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC87">5.1 Using
<code>tar</code> to Perform Full Dumps</a></td><td> </td><td
align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC88">5.2 Using <code>tar</code>
to Perform Incremental Dumps</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC89">5.3 Levels of
Backups</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC90">5.4 Setting Parameters for
Backups and Restoration</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC95">5.5 Using the Backup
Scripts</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC96">5.6 Using the Restore
Script</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Setting Parameters for Backups and Restoration
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC91">5.4.1
General-Purpose Variables</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC92">5.4.2 Magnetic Tape
Control</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC93">5.4.3 User
Hooks</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC94">5.4.4 An Example Text of
‘<tt>Backup-specs</tt>’</a></td><td> </td><td
align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Choosing Files and Names for <code>tar</code>
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC98">6.1
Choosing and Naming Archive Files</a></td><td> </td><td align="left"
valign="top"> Choosing the Archive's Name
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC99">6.2 Selecting Archive
Members</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC100">6.3 Reading Names from a
File</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC102">6.4 Excluding Some
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC104">6.5 Wildcards Patterns and
Matching</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC106">6.6 Quoting Member
Names</a></td><td> </td><td align="left" valign="top">
Ways of Quoting Special Characters in Names
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC107">6.7 Modifying File and
Member Names</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC108">6.8 Operating Only on New
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC109">6.9 Descending into
Directories</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC110">6.10 Crossing File System
Boundaries</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Reading Names from a File
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC101">6.3.1
<code>NUL</code> Terminated File Names</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Excluding Some Files
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC103">Problems
with Using the <code>exclude</code> Options</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Wildcards Patterns and Matching
+
+</pre></th></tr><tr><td align="left" valign="top"><a
href="#SEC105">Controlling Pattern-Matching</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Crossing File System Boundaries
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC111">6.10.1
Changing the Working Directory</a></td><td> </td><td align="left"
valign="top"> Changing Directory
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC112">6.10.2 Absolute File
Names</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Date input formats
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC114">7.1
General date syntax</a></td><td> </td><td align="left" valign="top">
Common rules.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC115">7.2 Calendar date
items</a></td><td> </td><td align="left" valign="top"> 19
Dec 1994.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC116">7.3 Time of day
items</a></td><td> </td><td align="left" valign="top">
9:20pm.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC117">7.4 Time zone
items</a></td><td> </td><td align="left" valign="top">
<small>EST</small>, <small>PDT</small>, <small>GMT</small>.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC118">7.5 Day of week
items</a></td><td> </td><td align="left" valign="top">
Monday and others.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC119">7.6 Relative items in date
strings</a></td><td> </td><td align="left" valign="top"> next
tuesday, 2 years ago.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC120">7.7 Pure numbers in date
strings</a></td><td> </td><td align="left" valign="top"> 19931219,
1440.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC121">7.8 Seconds since the
Epoch</a></td><td> </td><td align="left" valign="top">
@1078100502.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC122">7.9 Specifying time zone
rules</a></td><td> </td><td align="left" valign="top">
TZ="America/New_York", TZ="UTC0".
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td><td> </td><td align="left"
valign="top"> Bellovin, Eggert, Salz, Berets, et al.
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Controlling the Archive Format
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC129">8.3 Making
<code>tar</code> Archives More Portable</a></td><td> </td><td
align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC125">8.1 Using Less Space
through Compression</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC128">8.2 Handling File
Attributes</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC142">8.4 Comparison of
<code>tar</code> and <code>cpio</code></a></td><td> </td><td
align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Making <code>tar</code> Archives More Portable
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC130">8.3.1
Portable Names</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC131">8.3.2 Symbolic
Links</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC132">8.3.3 Old V7
Archives</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC133">8.3.4 Ustar Archive
Format</a></td><td> </td><td align="left" valign="top">
Ustar Archives
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC134">8.3.5
<acronym>GNU</acronym> and old <acronym>GNU</acronym> <code>tar</code>
format</a></td><td> </td><td align="left" valign="top">
GNU and old GNU format archives.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC135">8.3.6
<acronym>GNU</acronym> <code>tar</code> and <acronym>POSIX</acronym>
<code>tar</code></a></td><td> </td><td align="left" valign="top">
<acronym>POSIX</acronym> archives
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC137">8.3.7 Checksumming
Problems</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC138">8.3.8 Large or Negative
Values</a></td><td> </td><td align="left" valign="top"> Large
files, negative time stamps, etc.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC139">8.3.9 How to Extract
GNU-Specific Data Using Other <code>tar</code>
Implementations</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+<acronym>GNU</acronym> <code>tar</code> and <acronym>POSIX</acronym>
<code>tar</code>
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC136">8.3.6.1
Controlling Extended Header Keywords</a></td><td> </td><td
align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+How to Extract GNU-Specific Data Using Other <code>tar</code> Implementations
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC140">8.3.9.1
Extracting Members Split Between Volumes</a></td><td> </td><td
align="left" valign="top"> Members Split Between Volumes
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC141">8.3.9.2 Extracting Sparse
Members</a></td><td> </td><td align="left" valign="top"> Sparse
Members
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Using Less Space through Compression
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC126">8.1.1
Creating and Reading Compressed Archives</a></td><td> </td><td
align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC127">8.1.2 Archiving Sparse
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Tapes and Other Archive Media
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC144">9.1 Device
Selection and Switching</a></td><td> </td><td align="left"
valign="top"> Device selection and switching
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC145">9.2 The Remote Tape
Server</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC146">9.3 Some Common Problems
and their Solutions</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC147">9.4
Blocking</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC150">9.5 Many Archives on One
Tape</a></td><td> </td><td align="left" valign="top">
Many archives on one tape
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC153">9.6 Using Multiple
Tapes</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC157">9.7 Including a Label in
the Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC158">9.8 Verifying Data as It
is Stored</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC159">9.9 Write
Protection</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Blocking
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC148">9.4.1
Format Variations</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC149">9.4.2 The Blocking Factor
of an Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Many Archives on One Tape
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC151">9.5.1 Tape
Positions and Tape Marks</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC152">9.5.2 The <code>mt</code>
Utility</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Using Multiple Tapes
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC154">9.6.1
Archives Longer than One Tape or Disk</a></td><td> </td><td
align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC155">9.6.2 Tape
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC156">9.6.3 Concatenate Volumes
into a Single Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+
+Tar Internals
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC163">Basic Tar
Format</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC164"><acronym>GNU</acronym>
Extensions to the Archive Format</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC165">Storing Sparse
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC169">Format of the Incremental
Snapshot Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a
href="#SEC170">Dumpdir</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Storing Sparse Files
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC166">C.0.1 Old
GNU Format</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC167">C.0.2 PAX Format, Versions
0.0 and 0.1</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC168">C.0.3 PAX Format, Version
1.0</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Genfile
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC172">D.1
Generate Mode</a></td><td> </td><td align="left" valign="top">
File Generation Mode.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC173">D.2 Status
Mode</a></td><td> </td><td align="left" valign="top"> File
Status Mode.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC174">D.3 Exec
Mode</a></td><td> </td><td align="left" valign="top">
Synchronous Execution mode.
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Copying This Manual
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC177">F.1 GNU
Free Documentation License</a></td><td> </td><td align="left"
valign="top"> License for copying this manual
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+</pre></th></tr></table>
+
+<hr size="1">
+<a name="Introduction"></a>
+<a name="SEC1"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC2" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[ << ]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 1. Introduction </h1>
+
+<p><acronym>GNU</acronym> <code>tar</code> creates
+and manipulates <em>archives</em> 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.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC2">1.1 What this Book
Contains</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC3">1.2 Some
Definitions</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC4">1.3 What <code>tar</code>
Does</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC5">1.4 How <code>tar</code>
Archives are Named</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC6">1.5 <acronym>GNU</acronym>
<code>tar</code> Authors</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC7">1.6 Reporting bugs or
suggestions</a></td><td> </td><td align="left"
valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Book-Contents"></a>
+<a name="SEC2"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC1" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC3" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 1.1 What this Book Contains </h2>
+
+<p>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</acronym> <code>tar</code>
+and its documentation, and where you should send bug reports
+or comments.
+</p>
+<p>The second chapter is a tutorial (see section <a href="#SEC8">Tutorial
Introduction to <code>tar</code></a>) which provides a
+gentle introduction for people who are new to using <code>tar</code>. 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.
+</p>
+<p>Although the tutorial is paced and structured to allow beginners to
+learn how to use <code>tar</code>, it is not intended solely for beginners.
+The tutorial explains how to use the three most frequently used
+operations (‘<samp>create</samp>’,
‘<samp>list</samp>’, and ‘<samp>extract</samp>’) as
well as
+two frequently used options (‘<samp>file</samp>’ and
‘<samp>verbose</samp>’). 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; see section <a
href="#SEC8">Tutorial Introduction to <code>tar</code></a>.)
+</p>
+<p>The third chapter presents the remaining five operations, and
+information about using <code>tar</code> options and option syntax.
+</p>
+
+
+<p> The other chapters are meant to be used as a
+reference. Each chapter presents everything that needs to be said
+about a specific topic.
+</p>
+<p>One of the chapters (see section <a href="#SEC113">Date input formats</a>)
exists in its
+entirety in other <acronym>GNU</acronym> manuals, and is mostly self-contained.
+In addition, one section of this manual (see section <a href="#SEC163">Basic
Tar Format</a>) contains a
+big quote which is taken directly from <code>tar</code> sources.
+</p>
+<p>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.)
+</p>
+<hr size="6">
+<a name="Definitions"></a>
+<a name="SEC3"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC2" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC4" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 1.2 Some Definitions </h2>
+
+<p>The <code>tar</code> program is used to create and manipulate
<code>tar</code>
+archives. An <em>archive</em> 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 <code>tar</code>
+to <em>create</em> a new archive in a specified directory.
+</p>
+<a name="IDX3"></a>
+<a name="IDX4"></a>
+<a name="IDX5"></a>
+<a name="IDX6"></a>
+<p>The files inside an archive are called <em>members</em>. Within this
+manual, we use the term <em>file</em> to refer only to files accessible in
+the normal ways (by <code>ls</code>, <code>cat</code>, and so forth), and the
term
+<em>member</em> to refer only to the members of an archive. Similarly, a
+<em>file name</em> is the name of a file, as it resides in the file system,
+and a <em>member name</em> is the name of an archive member within the
+archive.
+</p>
+<a name="IDX7"></a>
+<a name="IDX8"></a>
+<p>The term <em>extraction</em> 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 <em>extracting the
+archive</em>. The term <em>unpack</em> 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 <em>list</em> the members in a given archive
+(this is often thought of as “printing” them to the standard
output,
+or the command line), or <em>append</em> members to a pre-existing archive.
+All of these operations can be performed using <code>tar</code>.
+</p>
+<hr size="6">
+<a name="What-tar-Does"></a>
+<a name="SEC4"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC3" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC5" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 1.3 What <code>tar</code> Does </h2>
+
+<p>The <code>tar</code> program provides the ability to create <code>tar</code>
+archives, as well as various other kinds of manipulation. For example,
+you can use <code>tar</code> on previously created archives to extract files,
+to store additional files, or to update or list files which were already
+stored.
+</p>
+<p>Initially, <code>tar</code> archives were used to store files conveniently
on
+magnetic tape. The name <code>tar</code> comes from this use; it stands for
+<code>t</code>ape <code>ar</code>chiver. Despite the utility's name,
<code>tar</code> can
+direct its output to available devices, files, or other programs (using
+pipes). <code>tar</code> may even access remote devices or files (as
archives).
+</p>
+<p>You can use <code>tar</code> archives in many ways. We want to stress a few
+of them: storage, backup, and transportation.
+</p>
+
+
+
+<dl compact="compact">
+<dt> Storage</dt>
+<dd><p>Often, <code>tar</code> archives are used to store related files for
+convenient file transfer over a network. For example, the
+<acronym>GNU</acronym> Project distributes its software bundled into
+<code>tar</code> archives, so that all the files relating to a particular
+program (or set of related programs) can be transferred as a single
+unit.
+</p>
+<p>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 <code>tar</code> 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 <code>tar</code>
+archives useful.
+</p>
+<p>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 <code>tar</code> can be used to move archives in
+all dimensions, even time!)
+</p>
+</dd>
+<dt> Backup</dt>
+<dd><p>Because the archive created by <code>tar</code> is capable of preserving
+file information and directory structure, <code>tar</code> 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.
+<acronym>GNU</acronym> <code>tar</code> has special features that allow it to
be
+used to make incremental and full dumps of all the files in a
+file system.
+</p>
+</dd>
+<dt> Transportation</dt>
+<dd><p>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.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Naming-tar-Archives"></a>
+<a name="SEC5"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC4" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC6" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 1.4 How <code>tar</code> Archives are Named </h2>
+
+<p>Conventionally, <code>tar</code> archives are given names ending with
+‘<samp>.tar</samp>’. This is not necessary for <code>tar</code>
to operate properly,
+but this manual follows that convention in order to accustom readers to
+it and to make examples more clear.
+</p>
+<a name="IDX9"></a>
+<a name="IDX10"></a>
+<a name="IDX11"></a>
+<p>Often, people refer to <code>tar</code> archives as “<code>tar</code>
files,” and
+archive members as “files” or “entries”. For people
familiar with
+the operation of <code>tar</code>, this causes no difficulty. However, in
+this manual, we consistently refer to “archives” and “archive
+members” to make learning to use <code>tar</code> easier for novice
users.
+</p>
+<hr size="6">
+<a name="Authors"></a>
+<a name="SEC6"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC5" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC7" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 1.5 <acronym>GNU</acronym> <code>tar</code> Authors </h2>
+
+<p><acronym>GNU</acronym> <code>tar</code> was originally written by John
Gilmore,
+and modified by many people. The <acronym>GNU</acronym> enhancements were
+written by Jay Fenlason, then Joy Kendall, and the whole package has
+been further maintained by Thomas Bushnell, n/BSG, François
+Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
+numerous and kind users.
+</p>
+<p>We wish to stress that <code>tar</code> 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
‘<tt>THANKS</tt>’
+file from the <acronym>GNU</acronym> <code>tar</code> distribution.
+</p>
+
+
+
+
+
+
+
+
+<p>Jay Fenlason put together a draft of a <acronym>GNU</acronym>
<code>tar</code>
+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</acronym>
<code>tar</code>.
+Franç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.
+</p>
+<p>For version 1.12, Daniel Hagerty contributed a great deal of technical
+consulting. In particular, he is the primary author of <a
href="#SEC86">Performing Backups and Restoring Files</a>.
+</p>
+<p>In July, 2003 <acronym>GNU</acronym> <code>tar</code> was put on CVS at
savannah.gnu.org
+(see <a
href="http://savannah.gnu.org/projects/tar";>http://savannah.gnu.org/projects/tar</a>),
and
+active development and maintenance work has started
+again. Currently <acronym>GNU</acronym> <code>tar</code> is being maintained
by Paul Eggert, Sergey
+Poznyakoff and Jeff Bailey.
+</p>
+<p>Support for <acronym>POSIX</acronym> archives was added by Sergey
Poznyakoff.
+</p>
+<hr size="6">
+<a name="Reports"></a>
+<a name="SEC7"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC6" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 1.6 Reporting bugs or suggestions </h2>
+
+<p>If you find problems or have suggestions about this program or manual,
+please report them to ‘<tt>address@hidden</tt>’.
+</p>
+<p>When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it.
+
+.
+</p>
+<hr size="6">
+<a name="Tutorial"></a>
+<a name="SEC8"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC7" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC9" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 2. Tutorial Introduction to <code>tar</code> </h1>
+
+<p>This chapter guides you through some basic examples of three
<code>tar</code>
+operations: ‘<samp>--create</samp>’,
‘<samp>--list</samp>’, and ‘<samp>--extract</samp>’. If
+you already know how to use some other version of <code>tar</code>, then you
+may not need to read this chapter. This chapter omits most complicated
+details about how <code>tar</code> works.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC9">2.1 Assumptions this
Tutorial Makes</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC10">2.2 Stylistic
Conventions</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC11">2.3 Basic <code>tar</code>
Operations and Options</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC12">2.4 The Three Most
Frequently Used Operations</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC13">2.5 Two Frequently Used
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC17">2.6 How to Create
Archives</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC23">2.7 How to List
Archives</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC25">2.8 How to Extract Members
from an Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC31">2.9 Going Further Ahead in
this Manual</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="assumptions"></a>
+<a name="SEC9"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC8" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC10" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.1 Assumptions this Tutorial Makes </h2>
+
+<p>This chapter is paced to allow beginners to learn about <code>tar</code>
+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:
+</p>
+<ul>
+<li>
+Before you start to work through this tutorial, you should understand
+what the terms “archive” and “archive member” mean
+(see section <a href="#SEC3">Some Definitions</a>). 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.
+
+
+
+</li><li>
+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 <code>tar</code> 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
‘<tt>/home/fsf/melissa</tt>’. All of
+my examples are in a subdirectory of the directory named by that path
+name; the subdirectory is called ‘<tt>practice</tt>’.
+
+</li><li>
+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. See section <a href="#SEC143">Tapes and Other Archive
Media</a>, for complete information on using
+<code>tar</code> archives with tape drives.
+
+
+
+
+</li></ul>
+
+<hr size="6">
+<a name="stylistic-conventions"></a>
+<a name="SEC10"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC9" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC11" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.2 Stylistic Conventions </h2>
+
+<p>In the examples, ‘<samp>$</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</kbd>, as opposed to lines which represent the
+computer's response; those lines are shown in <code>this font</code>, or
+sometimes ‘<samp>like this</samp>’.
+</p>
+
+<hr size="6">
+<a name="basic-tar-options"></a>
+<a name="SEC11"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC10" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC12" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.3 Basic <code>tar</code> Operations and Options </h2>
+
+<p><code>tar</code> 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 <code>tar</code> fall into one of two classes:
+operations, and options.
+</p>
+<p>Some arguments fall into a class called <em>operations</em>; exactly one of
+these is both allowed and required for any instance of using <code>tar</code>;
+you may <em>not</em> specify more than one. People sometimes speak of
+<em>operating modes</em>. 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.
+</p>
+<p>The other arguments fall into the class known as <em>options</em>. 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 <code>tar</code> 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.
+</p>
+<p>You can write most of the <code>tar</code> 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.
+
+We will indicate those abbreviations appropriately to get
+you used to seeing them. (Note that the “old style” option forms
+exist in <acronym>GNU</acronym> <code>tar</code> for compatibility with Unix
+<code>tar</code>. In this book we present a full discussion of this way
+of writing options and operations (see section <a href="#SEC38">Old Option
Style</a>), and we discuss
+the other two styles of writing options (See section <a href="#SEC36">Long
Option Style</a>, and
+see section <a href="#SEC37">Short Option Style</a>).
+</p>
+<p>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 <code>tar</code> commands easier.
+For example, instead of typing
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar --create
--verbose --file=afiles.tar apple angst aspic</kbd>
+</pre></td></tr></table>
+
+<p>you can type
+</p><table><tr><td> </td><td><pre class="smallexample"><kbd>tar -c -v -f
afiles.tar apple angst aspic</kbd>
+</pre></td></tr></table>
+
+<p>or even
+</p><table><tr><td> </td><td><pre class="smallexample"><kbd>tar -cvf
afiles.tar apple angst aspic</kbd>
+</pre></td></tr></table>
+
+<p>For more information on option syntax, see <a href="#SEC50">Advanced
<acronym>GNU</acronym> <code>tar</code> Operations</a>. In
+discussions in the text, when we name an option by its long form, we
+also give the corresponding short option in parentheses.
+</p>
+<p>The term, “option”, can be confusing at times, since
“operations”
+are often lumped in with the actual, <em>optional</em> “options”
in certain
+general class statements. For example, we just talked about “short and
+long forms of options and operations”. However, experienced
<code>tar</code>
+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.
+</p>
+<p>Similarly, the term “command” can be confusing, as it is often
used in
+two different ways. People sometimes refer to <code>tar</code>
“commands”.
+A <code>tar</code> <em>command</em> is the entire command line of user input
+which tells <code>tar</code> 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 <code>tar</code>
command”. When
+the word “command” is used specifically like this, a person is
usually
+referring to the <code>tar</code> <em>operation</em>, not the whole line.
+Again, use context to figure out which of the meanings the speaker
+intends.
+</p>
+<hr size="6">
+<a name="frequent-operations"></a>
+<a name="SEC12"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC11" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC13" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.4 The Three Most Frequently Used Operations </h2>
+
+<p>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.
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--create</samp>’</dt>
+<dt> ‘<samp>-c</samp>’</dt>
+<dd><p>Create a new <code>tar</code> archive.
+</p></dd>
+<dt> ‘<samp>--list</samp>’</dt>
+<dt> ‘<samp>-t</samp>’</dt>
+<dd><p>List the contents of an archive.
+</p></dd>
+<dt> ‘<samp>--extract</samp>’</dt>
+<dt> ‘<samp>-x</samp>’</dt>
+<dd><p>Extract one or more members from an archive.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Two-Frequent-Options"></a>
+<a name="SEC13"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC12" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC14" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.5 Two Frequently Used Options </h2>
+
+<p>To understand how to run <code>tar</code> in the three operating modes
listed
+previously, you also need to understand how to use two of the options to
+<code>tar</code>: ‘<samp>--file</samp>’ (which takes an archive
file as an argument)
+and ‘<samp>--verbose</samp>’. (You are usually not
<em>required</em> to specify
+either of these options when you run <code>tar</code>, but they can be very
+useful in making things more clear and helping you avoid errors.)
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC14">The
‘<samp>--file</samp>’ Option</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC15">The
‘<samp>--verbose</samp>’ Option</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC16">Getting Help: Using the
‘<samp>--help</samp>’ Option</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="file-tutorial"></a>
+<a name="SEC14"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC13" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC15" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC13" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="unnumberedsubsec"> The ‘<samp>--file</samp>’ Option
</h3>
+
+<dl compact="compact">
+<dd><a name="IDX12"></a>
+</dd>
+<dt> ‘<samp>--file=<var>archive-name</var></samp>’</dt>
+<dt> ‘<samp>-f <var>archive-name</var></samp>’</dt>
+<dd><p>Specify the name of an archive file.
+</p></dd>
+</dl>
+
+<p>You can specify an argument for the
‘<samp>--file=<var>archive-name</var></samp>’ (‘<samp>-f
<var>archive-name</var></samp>’) option whenever you
+use <code>tar</code>; this option determines the name of the archive file
+that <code>tar</code> will work on.
+</p>
+<a name="IDX13"></a>
+<p>If you don't specify this argument, then <code>tar</code> will examine
+the environment variable <code>TAPE</code>. If it is set, its value will be
+used as the archive name. Otherwise, <code>tar</code> 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</kbd>, see section <a href="#SEC45">Obtaining
<acronym>GNU</acronym> <code>tar</code> default values</a>). If there is no
tape drive
+attached, or the default is not meaningful, then <code>tar</code> will
+print an error message. The error message might look roughly like one
+of the following:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar: can't open
/dev/rmt8 : No such device or address
+tar: can't open /dev/rsmt0 : I/O error
+</pre></td></tr></table>
+
+<p>To avoid confusion, we recommend that you always specify an archive file
+name by using ‘<samp>--file=<var>archive-name</var></samp>’
(‘<samp>-f <var>archive-name</var></samp>’) when writing your
<code>tar</code> commands.
+For more information on using the
‘<samp>--file=<var>archive-name</var></samp>’ (‘<samp>-f
<var>archive-name</var></samp>’) option, see
+<a href="#SEC98">Choosing and Naming Archive Files</a>.
+</p>
+<hr size="6">
+<a name="verbose-tutorial"></a>
+<a name="SEC15"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC14" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC16" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC13" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="unnumberedsubsec"> The ‘<samp>--verbose</samp>’ Option
</h3>
+
+<dl compact="compact">
+<dd><a name="IDX14"></a>
+</dd>
+<dt> ‘<samp>--verbose</samp>’</dt>
+<dt> ‘<samp>-v</samp>’</dt>
+<dd><p>Show the files being worked on as <code>tar</code> is running.
+</p></dd>
+</dl>
+
+<p>‘<samp>--verbose</samp>’ (‘<samp>-v</samp>’) shows
details about the results of running
+<code>tar</code>. This can be especially useful when the results might not be
+obvious. For example, if you want to see the progress of <code>tar</code> as
+it writes files into the archive, you can use the
‘<samp>--verbose</samp>’
+option. In the beginning, you may find it useful to use
+‘<samp>--verbose</samp>’ at all times; when you are more
accustomed to
+<code>tar</code>, you will likely want to use it at certain times but not at
+others. We will use ‘<samp>--verbose</samp>’ at times to help
make something
+clear, and we will give many examples both using and not using
+‘<samp>--verbose</samp>’ to show the differences.
+</p>
+<p>Each instance of ‘<samp>--verbose</samp>’ on the command line
increases the
+verbosity level by one, so if you need more details on the output,
+specify it twice.
+</p>
+<p>When reading archives (‘<samp>--list</samp>’,
‘<samp>--extract</samp>’,
+‘<samp>--diff</samp>’), <code>tar</code> by default prints only
the names of
+the members being extracted. Using ‘<samp>--verbose</samp>’ will
show a full,
+<code>ls</code> style member listing.
+</p>
+<p>In contrast, when writing archives (‘<samp>--create</samp>’,
‘<samp>--append</samp>’,
+‘<samp>--update</samp>’), <code>tar</code> does not print file
names by
+default. So, a single ‘<samp>--verbose</samp>’ option shows the
file names
+being added to the archive, while two ‘<samp>--verbose</samp>’
options
+enable the full listing.
+</p>
+<p>For example, to create an archive in verbose mode:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cvf
afiles.tar apple angst aspic</kbd>
+apple
+angst
+aspic
+</pre></td></tr></table>
+
+<p>Creating the same archive with the verbosity level 2 could give:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cvvf
afiles.tar apple angst aspic</kbd>
+-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
+</pre></td></tr></table>
+
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--verbose --verbose …</kbd>
+</pre></td></tr></table>
+
+<p>Note that you must double the hyphens properly each time.
+</p>
+<p>Later in the tutorial, we will give examples using ‘<samp>--verbose
+--verbose</samp>’.
+</p>
+<p><a name="verbose-member-listing"></a>
+The full output consists of six fields:
+</p>
+<ul>
+<li> File type and permissions in symbolic form.
+These are displayed in the same format as the first column of
+<code>ls -l</code> output (see <a
href="fileutils.html#What-information-is-listed">format=verbose:
(fileutils)What information is listed</a> section `Verbose listing' in
<cite>GNU file utilities</cite>).
+
+</li><li> Owner name and group separated by a slash character.
+If these data are not available (for example, when listing a
‘<samp>v7</samp>’ format
+archive), numeric ID values are printed instead.
+
+</li><li> Size of the file, in bytes.
+
+</li><li> File modification date in ISO 8601 format.
+
+</li><li> File modification time.
+
+</li><li> File name.
+If the name contains any special characters (white space, newlines,
+etc.) these are displayed in an unambiguous form using so called
+<em>quoting style</em>. For the detailed discussion of available styles
+and on how to use them, see <a href="#SEC106">Quoting Member Names</a>.
+
+<p>Depending on the file type, the name can be followed by some
+additional information, described in the following table:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>-> <var>link-name</var></samp>’</dt>
+<dd><p>The file or archive member is a <em>symbolic link</em> and
+<var>link-name</var> is the name of file it links to.
+</p>
+</dd>
+<dt> ‘<samp>link to <var>link-name</var></samp>’</dt>
+<dd><p>The file or archive member is a <em>hard link</em> and
<var>link-name</var> is
+the name of file it links to.
+</p>
+</dd>
+<dt> ‘<samp>--Long Link--</samp>’</dt>
+<dd><p>The archive member is an old GNU format long link. You will normally
+not encounter this.
+</p>
+</dd>
+<dt> ‘<samp>--Long Name--</samp>’</dt>
+<dd><p>The archive member is an old GNU format long name. You will normally
+not encounter this.
+</p>
+</dd>
+<dt> ‘<samp>--Volume Header--</samp>’</dt>
+<dd><p>The archive member is a GNU <em>volume header</em> (see section <a
href="#SEC155">Tape Files</a>).
+</p>
+</dd>
+<dt> ‘<samp>--Continued at byte <var>n</var>--</samp>’</dt>
+<dd><p>Encountered only at the beginning of a multy-volume archive
+(see section <a href="#SEC153">Using Multiple Tapes</a>). This archive member
is a continuation
+from the previous volume. The number <var>n</var> gives the offset where
+the original file was split.
+</p>
+</dd>
+<dt> ‘<samp>--Mangled file names--</samp>’</dt>
+<dd><p>This archive member contains <em>mangled file names</em> declarations,
+a special member type that was used by early versions of
<acronym>GNU</acronym> <code>tar</code>.
+You probably will never encounter this, unless you are reading a very
+old archive.
+</p>
+</dd>
+<dt> ‘<samp>unknown file type <var>c</var></samp>’</dt>
+<dd><p>An archive member of unknown type. <var>c</var> 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</acronym>
<code>tar</code> is not
+able to handle, or the archive is corrupted.
+</p></dd>
+</dl>
+
+</li></ul>
+
+<p>For example, here is an archive listing containing most of the special
+suffixes explained above:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">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
+</pre></td></tr></table>
+
+
+<hr size="6">
+<a name="help-tutorial"></a>
+<a name="SEC16"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC15" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC17" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC13" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="unnumberedsubsec"> Getting Help: Using the
‘<samp>--help</samp>’ Option </h3>
+
+<dl compact="compact">
+<dd><a name="IDX15"></a>
+</dd>
+<dt> ‘<samp>--help</samp>’</dt>
+<dd>
+<p>The ‘<samp>--help</samp>’ option to <code>tar</code> prints out
a very brief list of
+all operations and option available for the current version of
+<code>tar</code> available on your system.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="create"></a>
+<a name="SEC17"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC16" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC18" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.6 How to Create Archives </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX16"></a>
+<a name="IDX17"></a>
+<p>One of the basic operations of <code>tar</code> is
‘<samp>--create</samp>’ (‘<samp>-c</samp>’), which
+you use to create a <code>tar</code> archive. We will explain
+‘<samp>--create</samp>’ first because, in order to learn about the
other
+operations, you will find it useful to have an archive available to
+practice on.
+</p>
+<p>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
+<em>archive</em> (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.
+</p>
+<p>The three files you will archive in this example are called
+‘<tt>blues</tt>’, ‘<tt>folk</tt>’, and
‘<tt>jazz</tt>’. The archive is called
+‘<tt>collection.tar</tt>’.
+</p>
+<p>This section will proceed slowly, detailing how to use
‘<samp>--create</samp>’
+in <code>verbose</code> 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
+<code>tar</code> works.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC18">2.6.1 Preparing a Practice
Directory for Examples</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC19">2.6.2 Creating the
Archive</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC20">2.6.3 Running
‘<samp>--create</samp>’ with
‘<samp>--verbose</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC21">2.6.4 Short Forms with
‘<samp>create</samp>’</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC22">2.6.5 Archiving
Directories</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="prepare-for-examples"></a>
+<a name="SEC18"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC17" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC19" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC17" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.6.1 Preparing a Practice Directory for Examples </h3>
+
+<p>To follow along with this and future examples, create a new directory
+called ‘<tt>practice</tt>’ containing files called
‘<tt>blues</tt>’, ‘<tt>folk</tt>’
+and ‘<tt>jazz</tt>’. 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
‘<tt>practice</tt>’
+is a subdirectory of your home directory.
+</p>
+<p>Now <code>cd</code> to the directory named ‘<tt>practice</tt>’;
‘<tt>practice</tt>’
+is now your <em>working directory</em>. (<em>Please note</em>: Although
+the full path name of this directory is
+‘<tt>/<var>homedir</var>/practice</tt>’, in our examples we will
refer to
+this directory as ‘<tt>practice</tt>’; the <var>homedir</var> is
presumed.
+</p>
+<p>In general, you should check that the files to be archived exist where
+you think they do (in the working directory) by running <code>ls</code>.
+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.
+</p>
+<p>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,
+‘<samp>collection.tar</samp>’), or that you don't care about its
contents.
+Whenever you use ‘<samp>create</samp>’, <code>tar</code> will
erase the current
+contents of the file named by
‘<samp>--file=<var>archive-name</var></samp>’ (‘<samp>-f
<var>archive-name</var></samp>’) if it exists. <code>tar</code>
+will not tell you if you are about to overwrite an archive unless you
+specify an option which does this (see section <a href="#SEC83">Backup
options</a>, for the
+information on how to do so). To add files to an existing archive,
+you need to use a different option, such as
‘<samp>--append</samp>’ (‘<samp>-r</samp>’); see
+<a href="#SEC52">How to Add Files to Existing Archives:
‘<samp>--append</samp>’</a> for information on how to do this.
+</p>
+<hr size="6">
+<a name="Creating-the-archive"></a>
+<a name="SEC19"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC18" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC20" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC17" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.6.2 Creating the Archive </h3>
+
+<p>To place the files ‘<tt>blues</tt>’,
‘<tt>folk</tt>’, and ‘<tt>jazz</tt>’ into an
+archive named ‘<tt>collection.tar</tt>’, use the following command:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--file=collection.tar blues folk jazz</kbd>
+</pre></td></tr></table>
+
+<p>The order of the arguments is not very important, <em>when using long
+option forms</em>. You could also say:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar blues
--create folk --file=collection.tar jazz</kbd>
+</pre></td></tr></table>
+
+<p>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
+<code>tar</code>, to avoid errors).
+</p>
+<p>Note that the sequence
+‘<samp>--file=collection.tar</samp>’ is considered to be
<em>one</em> argument.
+If you substituted any other string of characters for
+<kbd>collection.tar</kbd>, then that string would become the name of the
+archive file you create.
+</p>
+<p>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.
+See section <a href="#SEC21">Short Forms with
‘<samp>create</samp>’</a>, for more information on this.
+</p>
+<p>In this example, you type the command as shown above:
‘<samp>--create</samp>’
+is the operation which creates the new archive
+(‘<tt>collection.tar</tt>’), and ‘<samp>--file</samp>’
is the option which lets
+you give it the name you chose. The files, ‘<tt>blues</tt>’,
‘<tt>folk</tt>’,
+and ‘<tt>jazz</tt>’, are now members of the archive,
‘<tt>collection.tar</tt>’
+(they are <em>file name arguments</em> to the
‘<samp>--create</samp>’ operation.
+See section <a href="#SEC97">Choosing Files and Names for
<code>tar</code></a>, for the detailed discussion on these.) Now that they are
+in the archive, they are called <em>archive members</em>, not files.
+(see section <a href="#SEC3">members</a>).
+</p>
+<p>When you create an archive, you <em>must</em> specify which files you
+want placed in the archive. If you do not specify any archive
+members, <acronym>GNU</acronym> <code>tar</code> will complain.
+</p>
+<p>If you now list the contents of the working directory (<code>ls</code>),
you will
+find the archive file listed as well as the files you saw previously:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">blues folk jazz
collection.tar
+</pre></td></tr></table>
+
+<p>Creating the archive ‘<samp>collection.tar</samp>’ did not
destroy the copies of
+the files in the directory.
+</p>
+<p>Keep in mind that if you don't indicate an operation, <code>tar</code> will
not
+run and will prompt you for one. If you don't name any files, <code>tar</code>
+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.
+</p>
+<p><em>Caution</em>: Do not attempt to use ‘<samp>--create</samp>’
(‘<samp>-c</samp>’) to add files to
+an existing archive; it will delete the archive and write a new one.
+Use ‘<samp>--append</samp>’ (‘<samp>-r</samp>’)
instead. See section <a href="#SEC52">How to Add Files to Existing Archives:
‘<samp>--append</samp>’</a>.
+</p>
+<hr size="6">
+<a name="create-verbose"></a>
+<a name="SEC20"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC19" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC21" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC17" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.6.3 Running ‘<samp>--create</samp>’ with
‘<samp>--verbose</samp>’ </h3>
+
+<p>If you include the ‘<samp>--verbose</samp>’
(‘<samp>-v</samp>’) option on the command line,
+<code>tar</code> will list the files it is acting on as it is working. In
+verbose mode, the <code>create</code> example above would appear as:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--verbose --file=collection.tar blues folk jazz</kbd>
+blues
+folk
+jazz
+</pre></td></tr></table>
+
+<p>This example is just like the example we showed which did not use
+‘<samp>--verbose</samp>’, except that <code>tar</code> generated
the remaining lines
+</p>
+<p>In the rest of the examples in this chapter, we will frequently use
+<code>verbose</code> mode so we can show actions or <code>tar</code> responses
that
+you would otherwise not see, and which are important for you to
+understand.
+</p>
+<hr size="6">
+<a name="short-create"></a>
+<a name="SEC21"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC20" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC22" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC17" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.6.4 Short Forms with
‘<samp>create</samp>’ </h3>
+
+<p>As we said before, the ‘<samp>--create</samp>’
(‘<samp>-c</samp>’) operation is one of the most
+basic uses of <code>tar</code>, 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 <a href="#SEC35">The Three Option Styles</a>; for
now, here is what the
+previous example (including the ‘<samp>--verbose</samp>’
(‘<samp>-v</samp>’) option) looks like
+using short option forms:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cvf
collection.tar blues folk jazz</kbd>
+blues
+folk
+jazz
+</pre></td></tr></table>
+
+<p>As you can see, the system responds the same no matter whether you use
+long or short option forms.
+</p>
+
+
+<p> 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cfv
collection.tar blues folk jazz</kbd>
+</pre></td></tr></table>
+
+<p>In this case, <code>tar</code> will make an archive file called
‘<tt>v</tt>’,
+containing the files ‘<tt>blues</tt>’,
‘<tt>folk</tt>’, and ‘<tt>jazz</tt>’, because
+the ‘<samp>v</samp>’ is the closest “file name” to the
‘<samp>-f</samp>’ option, and
+is thus taken to be the chosen archive file name. <code>tar</code> will try
+to add a file called ‘<tt>collection.tar</tt>’ to the
‘<tt>v</tt>’ archive file;
+if the file ‘<tt>collection.tar</tt>’ did not already exist,
<code>tar</code> will
+report an error indicating that this file does not exist. If the file
+‘<tt>collection.tar</tt>’ does already exist (e.g., from a
previous command
+you may have run), then <code>tar</code> will add this file to the archive.
+Because the ‘<samp>-v</samp>’ option did not get registered,
<code>tar</code> will not
+run under ‘<samp>verbose</samp>’ mode, and will not report its
progress.
+</p>
+<p>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.
+</p>
+<p>This example,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar blues
--create folk --file=collection.tar jazz</kbd>
+</pre></td></tr></table>
+
+<p>is confusing as it is. When shown using short forms, however, it
+becomes much more so:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar blues -c
folk -f collection.tar jazz</kbd>
+</pre></td></tr></table>
+
+<p>It would be very easy to put the wrong string of characters
+immediately following the ‘<samp>-f</samp>’, but doing that could
sacrifice
+valuable data.
+</p>
+<p>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.
+</p>
+<hr size="6">
+<a name="create-dir"></a>
+<a name="SEC22"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC21" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC23" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC17" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.6.5 Archiving Directories </h3>
+
+<p>You can archive a directory by specifying its directory name as a
+file name argument to <code>tar</code>. 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.
+</p>
+<p>To archive a directory, first move to its superior directory. If you
+have followed the previous instructions in this tutorial, you should
+type:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>cd ..</kbd>
+$
+</pre></td></tr></table>
+
+<p>This will put you into the directory which contains
‘<tt>practice</tt>’,
+i.e., your home directory. Once in the superior directory, you can
+specify the subdirectory, ‘<tt>practice</tt>’, as a file name
argument. To
+store ‘<tt>practice</tt>’ in the new archive file
‘<tt>music.tar</tt>’, type:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--verbose --file=music.tar practice</kbd>
+</pre></td></tr></table>
+
+<p><code>tar</code> should output:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">practice/
+practice/blues
+practice/folk
+practice/jazz
+practice/collection.tar
+</pre></td></tr></table>
+
+<p>Note that the archive thus created is not in the subdirectory
+‘<tt>practice</tt>’, but rather in the current working
directory—the
+directory from which <code>tar</code> 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 <code>tar</code>. For example, you will probably
+not be able to store your home directory in an archive by invoking
+<code>tar</code> from the root directory; See section <a
href="#SEC112">Absolute File Names</a>. (Note
+also that ‘<tt>collection.tar</tt>’, the original archive file,
has itself
+been archived. <code>tar</code> will accept any file as a file to be
+archived, regardless of its content. When ‘<tt>music.tar</tt>’ is
+extracted, the archive file ‘<tt>collection.tar</tt>’ will be
re-written
+into the file system).
+</p>
+<p>If you give <code>tar</code> a command such as
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--file=foo.tar .</kbd>
+</pre></td></tr></table>
+
+<p><code>tar</code> will report ‘<samp>tar: ./foo.tar is the archive; not
+dumped</samp>’. This happens because <code>tar</code> creates the
archive
+‘<tt>foo.tar</tt>’ in the current directory before putting any
files into
+it. Then, when <code>tar</code> attempts to add all the files in the
+directory ‘<tt>.</tt>’ to the archive, it notices that the file
+‘<tt>./foo.tar</tt>’ is the same as the archive
‘<tt>foo.tar</tt>’, and skips
+it. (It makes no sense to put an archive into itself.)
<acronym>GNU</acronym> <code>tar</code>
+will continue in this case, and create the archive
+normally, except for the exclusion of that one file. (<em>Please
+note:</em> Other implementations of <code>tar</code> 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
+<acronym>GNU</acronym> <code>tar</code>. In general, it is wise to always
place the archive outside
+of the directory being dumped.
+</p>
+<hr size="6">
+<a name="list"></a>
+<a name="SEC23"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC22" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC24" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.7 How to List Archives </h2>
+
+<p>Frequently, you will find yourself wanting to determine exactly what a
+particular archive contains. You can use the ‘<samp>--list</samp>’
+(‘<samp>-t</samp>’) 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
+‘<tt>collection.tar</tt>’ that you created in the last section
with the
+command,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --list
--file=collection.tar</kbd>
+</pre></td></tr></table>
+
+<p>The output of <code>tar</code> would then be:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">blues
+folk
+jazz
+</pre></td></tr></table>
+
+<p>The archive ‘<tt>bfiles.tar</tt>’ would list as follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">./birds
+baboon
+./box
+</pre></td></tr></table>
+
+<p>Be sure to use a ‘<samp>--file=<var>archive-name</var></samp>’
(‘<samp>-f
+<var>archive-name</var></samp>’) option just as with
‘<samp>--create</samp>’
+(‘<samp>-c</samp>’) to specify the name of the archive.
+</p>
+<a name="IDX18"></a>
+<a name="IDX19"></a>
+<p>If you use the ‘<samp>--verbose</samp>’
(‘<samp>-v</samp>’) option with
+‘<samp>--list</samp>’, then <code>tar</code> will print out a
listing
+reminiscent of ‘<samp>ls -l</samp>’, showing owner, file size, and
so
+forth. This output is described in detail in <a
href="#verbose-member-listing">verbose member listing</a>.
+</p>
+<p>If you had used ‘<samp>--verbose</samp>’
(‘<samp>-v</samp>’) mode, the example
+above would look like:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --list
--verbose --file=collection.tar folk</kbd>
+-rw-r--r-- myself user 62 1990-05-23 10:55 folk
+</pre></td></tr></table>
+
+<a name="IDX20"></a>
+<p><a name="listing-member-and-file-names"></a>
+It is important to notice that the output of <kbd>tar --list
+--verbose</kbd> does not necessarily match that produced by <kbd>tar
+--create --verbose</kbd> while creating the archive. It is because
+<acronym>GNU</acronym> <code>tar</code>, unless told explicitly not to do so,
removes some directory
+prefixes from file names before storing them in the archive
+(See section <a href="#SEC112">Absolute File Names</a>, for more information).
In other
+words, in verbose mode <acronym>GNU</acronym> <code>tar</code> shows <em>file
names</em> when creating
+an archive and <em>member names</em> when listing it. Consider this
+example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cfv archive
/etc/mail</kbd>
+tar: Removing leading `/' from member names
+/etc/mail/
+/etc/mail/sendmail.cf
+/etc/mail/aliases
+$ <kbd>tar tf archive</kbd>
+etc/mail/
+etc/mail/sendmail.cf
+etc/mail/aliases
+</pre></td></tr></table>
+
+<a name="IDX21"></a>
+<p> This default behavior can sometimes be inconvenient. You can force
+<acronym>GNU</acronym> <code>tar</code> show member names when creating
archive by supplying
+‘<samp>--show-stored-names</samp>’ option.
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--show-stored-names</samp>’</dt>
+<dd><p>Print member (as opposed to <em>file</em>) names when creating the
archive.
+</p></dd>
+</dl>
+
+<a name="IDX22"></a>
+<a name="IDX23"></a>
+<p>You can specify one or more individual member names as arguments when
+using ‘<samp>list</samp>’. In this case, <code>tar</code> will
only list the
+names of members you identify. For example, <kbd>tar --list
+--file=afiles.tar apple</kbd> would only print ‘<tt>apple</tt>’.
+</p>
+<p>Because <code>tar</code> 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 <code>tar</code> that you give the exact member names.
+For example, <kbd>tar --list --file=bfiles.tar birds</kbd> would produce an
+error message something like ‘<samp>tar: birds: Not found in
archive</samp>’,
+because there is no member named ‘<tt>birds</tt>’, only one named
+‘<tt>./birds</tt>’. While the names ‘<tt>birds</tt>’
and ‘<tt>./birds</tt>’ name
+the same file, <em>member</em> names by default are compared verbatim.
+</p>
+<p>However, <kbd>tar --list --file=bfiles.tar baboon</kbd> would respond
+with ‘<tt>baboon</tt>’, because this exact member name is in the
archive file
+‘<tt>bfiles.tar</tt>’. If you are not sure of the exact file name,
+use <em>globbing patterns</em>, for example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --list
--file=bfiles.tar --wildcards '*b*'</kbd>
+</pre></td></tr></table>
+
+<p>will list all members whose name contains ‘<samp>b</samp>’.
See section <a href="#SEC104">Wildcards Patterns and Matching</a>,
+for a detailed discussion of globbing patterns and related
+<code>tar</code> command line options.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC24">Listing the Contents of a
Stored Directory</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="list-dir"></a>
+<a name="SEC24"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC23" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC25" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC23" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="unnumberedsubsec"> Listing the Contents of a Stored Directory </h3>
+
+<p>To get information about the contents of an archived directory,
+use the directory name as a file name argument in conjunction with
+‘<samp>--list</samp>’ (‘<samp>-t</samp>’). To find
out file attributes, include the
+‘<samp>--verbose</samp>’ (‘<samp>-v</samp>’) option.
+</p>
+<p>For example, to find out about files in the directory
‘<tt>practice</tt>’, in
+the archive file ‘<tt>music.tar</tt>’, type:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --list
--verbose --file=music.tar practice</kbd>
+</pre></td></tr></table>
+
+<p><code>tar</code> responds:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">drwxrwxrwx myself user
0 1990-05-31 21:49 practice/
+-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
+-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
+-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
+-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
+</pre></td></tr></table>
+
+<p>When you use a directory name as a file name argument, <code>tar</code>
acts on
+all the files (including sub-directories) in that directory.
+</p>
+<hr size="6">
+<a name="extract"></a>
+<a name="SEC25"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC24" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC26" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.8 How to Extract Members from an Archive </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+<a name="IDX24"></a>
+<a name="IDX25"></a>
+<a name="IDX26"></a>
+
+<a name="IDX27"></a>
+<p>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 <em>extraction</em>. To extract files
+from an archive, use the ‘<samp>--extract</samp>’
(‘<samp>--get</samp>’ or
+‘<samp>-x</samp>’) operation. As with
‘<samp>--create</samp>’, specify the name
+of the archive with ‘<samp>--file</samp>’
(‘<samp>-f</samp>’) option. Extracting
+an archive does not modify the archive in any way; you can extract it
+multiple times if you want or need to.
+</p>
+<p>Using ‘<samp>--extract</samp>’, you can extract an entire
archive, or specific
+files. The files can be directories containing other files, or not. As
+with ‘<samp>--create</samp>’ (‘<samp>-c</samp>’) and
‘<samp>--list</samp>’ (‘<samp>-t</samp>’), you may use
the short or the
+long form of the operation without affecting the performance.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC26">2.8.1 Extracting an Entire
Archive</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC27">2.8.2 Extracting Specific
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC28">2.8.3 Extracting Files that
are Directories</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC29">2.8.4 Extracting Archives
from Untrusted Sources</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC30">2.8.5 Commands That Will
Fail</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="extracting-archives"></a>
+<a name="SEC26"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC25" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC27" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC25" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.8.1 Extracting an Entire Archive </h3>
+
+<p>To extract an entire archive, specify the archive file name only, with
+no individual file names as arguments. For example,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -xvf
collection.tar</kbd>
+</pre></td></tr></table>
+
+<p>produces this:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">-rw-r--r-- me user
28 1996-10-18 16:31 jazz
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+-rw-r--r-- me user 20 1996-09-23 16:44 folk
+</pre></td></tr></table>
+
+<hr size="6">
+<a name="extracting-files"></a>
+<a name="SEC27"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC26" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC28" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC25" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.8.2 Extracting Specific Files </h3>
+
+<p>To extract specific archive members, give their exact member names as
+arguments, as printed by ‘<samp>--list</samp>’
(‘<samp>-t</samp>’). If you had
+mistakenly deleted one of the files you had placed in the archive
+‘<tt>collection.tar</tt>’ earlier (say,
‘<tt>blues</tt>’), you can extract it
+from the archive without changing the archive's structure. Its
+contents will be identical to the original file ‘<tt>blues</tt>’
that you
+deleted.
+</p>
+<p>First, make sure you are in the ‘<tt>practice</tt>’ directory,
and list the
+files in the directory. Now, delete the file,
‘<samp>blues</samp>’, and list
+the files in the directory again.
+</p>
+<p>You can now extract the member ‘<tt>blues</tt>’ from the
archive file
+‘<tt>collection.tar</tt>’ like this:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --extract
--file=collection.tar blues</kbd>
+</pre></td></tr></table>
+
+<p>If you list the files in the directory again, you will see that the file
+‘<tt>blues</tt>’ has been restored, with its original permissions,
data
+modification times, and owner.<a name="DOCF1" href="#FOOT1">(1)</a> (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 <em>not</em> have been made to the archive member.) The
+archive file, ‘<samp>collection.tar</samp>’, is the same as it was
before you
+extracted ‘<samp>blues</samp>’. You can confirm this by running
<code>tar</code> with
+‘<samp>--list</samp>’ (‘<samp>-t</samp>’).
+</p>
+<p>Remember that as with other operations, specifying the exact member
+name is important. <kbd>tar --extract --file=bfiles.tar birds</kbd>
+will fail, because there is no member named ‘<tt>birds</tt>’. To
extract
+the member named ‘<tt>./birds</tt>’, you must specify <kbd>tar
+--extract --file=bfiles.tar ./birds</kbd>. If you don't remember the
+exact member names, use ‘<samp>--list</samp>’
(‘<samp>-t</samp>’) option
+(see section <a href="#SEC23">How to List Archives</a>). You can also extract
those members that match a
+specific <em>globbing pattern</em>. For example, to extract from
+‘<tt>bfiles.tar</tt>’ all files that begin with
‘<samp>b</samp>’, no matter their
+directory prefix, you could type:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -x -f
bfiles.tar --wildcards --no-anchored 'b*'</kbd>
+</pre></td></tr></table>
+
+<p>Here, ‘<samp>--wildcards</samp>’ instructs <code>tar</code> to
treat
+command line arguments as globbing patterns and
‘<samp>--no-anchored</samp>’
+informs it that the patterns apply to member names after any
‘<samp>/</samp>’
+delimiter. The use of globbing patterns is discussed in detail in
+See section <a href="#SEC104">Wildcards Patterns and Matching</a>.
+</p>
+<p>You can extract a file to standard output by combining the above options
+with the ‘<samp>--to-stdout</samp>’
(‘<samp>-O</samp>’) option (see section <a href="#SEC77">Writing to
Standard Output</a>).
+</p>
+<p>If you give the ‘<samp>--verbose</samp>’ option, then
‘<samp>--extract</samp>’
+will print the names of the archive members as it extracts them.
+</p>
+<hr size="6">
+<a name="extract-dir"></a>
+<a name="SEC28"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC27" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC29" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC25" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.8.3 Extracting Files that are Directories </h3>
+
+<p>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
+see section <a href="#SEC67">Changing How <code>tar</code> Writes Files</a>).
+</p>
+<p>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, <code>tar</code> will create the directory.
+</p>
+<p>We can demonstrate how to use ‘<samp>--extract</samp>’ to
extract a directory
+file with an example. Change to the ‘<tt>practice</tt>’ directory
if you
+weren't there, and remove the files ‘<tt>folk</tt>’ and
‘<tt>jazz</tt>’. Then,
+go back to the parent directory and extract the archive
+‘<tt>music.tar</tt>’. 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
+‘<tt>music.tar</tt>’. To extract only the files you deleted, use
the
+following command:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -xvf
music.tar practice/folk practice/jazz</kbd>
+practice/folk
+practice/jazz
+</pre></td></tr></table>
+
+<p>If you were to specify two ‘<samp>--verbose</samp>’
(‘<samp>-v</samp>’) options, <code>tar</code>
+would have displayed more detail about the extracted files, as shown
+in the example below:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -xvvf
music.tar practice/folk practice/jazz</kbd>
+-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
+</pre></td></tr></table>
+
+<p>Because you created the directory with ‘<tt>practice</tt>’ as
part of the
+file names of each of the files by archiving the
‘<tt>practice</tt>’
+directory as ‘<tt>practice</tt>’, you must give
‘<tt>practice</tt>’ as part
+of the file names when you extract those files from the archive.
+</p>
+<hr size="6">
+<a name="extracting-untrusted-archives"></a>
+<a name="SEC29"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC28" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC30" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC25" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.8.4 Extracting Archives from Untrusted Sources </h3>
+
+<p>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 ‘<tt>untrusted.tar</tt>’ came from somewhere else
on the
+Internet, and you don't necessarily trust its contents, you can
+extract it as follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>mkdir
newdir</kbd>
+$ <kbd>cd newdir</kbd>
+$ <kbd>tar -xvf ../untrusted.tar</kbd>
+</pre></td></tr></table>
+
+<p>It is also a good practice to examine contents of the archive
+before extracting it, using ‘<samp>--list</samp>’
(‘<samp>-t</samp>’) option, possibly combined
+with ‘<samp>--verbose</samp>’ (‘<samp>-v</samp>’).
+</p>
+<hr size="6">
+<a name="failing-commands"></a>
+<a name="SEC30"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC29" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC31" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC25" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 2.8.5 Commands That Will Fail </h3>
+
+<p>Here are some sample commands you might try which will not work, and why
+they won't work.
+</p>
+<p>If you try to use this command,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -xvf
music.tar folk jazz</kbd>
+</pre></td></tr></table>
+
+<p>you will get the following response:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar: folk: Not found
in archive
+tar: jazz: Not found in archive
+$
+</pre></td></tr></table>
+
+<p>This is because these files were not originally <em>in</em> the parent
+directory ‘<tt>..</tt>’, where the archive is located; they were
in the
+‘<tt>practice</tt>’ directory, and their file names reflect this:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -tvf
music.tar</kbd>
+practice/folk
+practice/jazz
+practice/rock
+</pre></td></tr></table>
+
+
+
+
+
+<p>Likewise, if you try to use this command,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -tvf
music.tar folk jazz</kbd>
+</pre></td></tr></table>
+
+<p>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.
+</p>
+<p>If you have forgotten the correct names of the files in the archive,
+use <kbd>tar --list --verbose</kbd> to list them correctly.
+</p>
+
+
+
+
+<hr size="6">
+<a name="going-further"></a>
+<a name="SEC31"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC30" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 2.9 Going Further Ahead in this Manual </h2>
+
+
+
+
+
+<hr size="6">
+<a name="tar-invocation"></a>
+<a name="SEC32"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC31" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC33" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 3. Invoking <acronym>GNU</acronym> <code>tar</code> </h1>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>This chapter is about how one invokes the <acronym>GNU</acronym>
<code>tar</code>
+command, from the command synopsis (see section <a href="#SEC33">General
Synopsis of <code>tar</code></a>). There are
+numerous options, and many styles for writing them. One mandatory
+option specifies the operation <code>tar</code> should perform
+(see section <a href="#SEC41">Operations</a>), other options are meant to
detail how
+this operation should be performed (see section <a
href="#SEC42"><code>tar</code> Options</a>).
+Non-option arguments are not always interpreted the same way,
+depending on what the operation is.
+</p>
+<p>You will find in this chapter everything about option styles and rules for
+writing them (see section <a href="#SEC35">The Three Option Styles</a>). 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 <code>tar</code> manual.
+</p>
+<p>Some options are so special they are fully described right in this
+chapter. They have the effect of inhibiting the normal operation of
+<code>tar</code> or else, they globally alter the amount of feedback the user
+receives about what is going on. These are the
‘<samp>--help</samp>’ and
+‘<samp>--version</samp>’ (see section <a
href="#SEC44"><acronym>GNU</acronym> <code>tar</code> documentation</a>),
‘<samp>--verbose</samp>’ (see section <a href="#SEC46">Checking
<code>tar</code> progress</a>)
+and ‘<samp>--interactive</samp>’ options (see section <a
href="#SEC47">Asking for Confirmation During Operations</a>).
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC33">3.1 General Synopsis of
<code>tar</code></a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC34">3.2 Using <code>tar</code>
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC35">3.3 The Three Option
Styles</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC40">3.4 All <code>tar</code>
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC44">3.5 <acronym>GNU</acronym>
<code>tar</code> documentation</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC45">3.6 Obtaining
<acronym>GNU</acronym> <code>tar</code> default
values</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC46">3.7 Checking
<code>tar</code> progress</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC47">3.8 Asking for Confirmation
During Operations</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Synopsis"></a>
+<a name="SEC33"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC32" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC34" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 3.1 General Synopsis of <code>tar</code> </h2>
+
+<p>The <acronym>GNU</acronym> <code>tar</code> program is invoked as either
one of:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar
<var>option</var>… [<var>name</var>]…</kbd>
+<kbd>tar <var>letter</var>… [<var>argument</var>]…
[<var>option</var>]… [<var>name</var>]…</kbd>
+</pre></td></tr></table>
+
+<p>The second form is for when old options are being used.
+</p>
+<p>You can use <code>tar</code> to store files in an archive, to extract them
from
+an archive, and to do other types of archive manipulation. The primary
+argument to <code>tar</code>, which is called the <em>operation</em>, specifies
+which action to take. The other arguments to <code>tar</code> are either
+<em>options</em>, which change the way <code>tar</code> performs an operation,
+or file names or archive members, which specify the files or members
+<code>tar</code> is to act on.
+</p>
+<p>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 <code>tar</code> main command) is usually given first.
+</p>
+<p>Each <var>name</var> in the synopsis above is interpreted as an archive
member
+name when the main command is one of ‘<samp>--compare</samp>’
+(‘<samp>--diff</samp>’, ‘<samp>-d</samp>’),
‘<samp>--delete</samp>’, ‘<samp>--extract</samp>’
+(‘<samp>--get</samp>’, ‘<samp>-x</samp>’),
‘<samp>--list</samp>’ (‘<samp>-t</samp>’) or
+‘<samp>--update</samp>’ (‘<samp>-u</samp>’). When
naming archive members, you
+must give the exact name of the member in the archive, as it is
+printed by ‘<samp>--list</samp>’. For
‘<samp>--append</samp>’ (‘<samp>-r</samp>’) and
+‘<samp>--create</samp>’ (‘<samp>-c</samp>’), these
<var>name</var> 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 <code>tar</code> command.
+</p>
+<p><code>tar</code> interprets relative file names as being relative to the
+working directory. <code>tar</code> will make all file names relative
+(by removing leading slashes when archiving or restoring files),
+unless you specify otherwise (using the
‘<samp>--absolute-names</samp>’
+option). See section <a href="#SEC112">Absolute File Names</a>, for more
information about
+‘<samp>--absolute-names</samp>’.
+</p>
+<p>If you give the name of a directory as either a file name or a member
+name, then <code>tar</code> acts recursively on all the files and directories
+beneath that directory. For example, the name ‘<tt>/</tt>’
identifies all
+the files in the file system to <code>tar</code>.
+</p>
+<p>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. See section <a href="#SEC104">Wildcards Patterns and
Matching</a>, for more information about globbing.
+The problem is that shells may only glob using existing files in the
+file system. Only <code>tar</code> itself may glob on archive members, so when
+needed, you must ensure that wildcard characters reach <code>tar</code> without
+being interpreted by the shell first. Using a backslash before
‘<samp>*</samp>’
+or ‘<samp>?</samp>’, or putting the whole argument between quotes,
is usually
+sufficient for this.
+</p>
+<p>Even if <var>name</var>s are often specified on the command line, they
+can also be read from a text file in the file system, using the
+‘<samp>--files-from=<var>file-of-names</var></samp>’
(‘<samp>-T <var>file-of-names</var></samp>’) option.
+</p>
+<p>If you don't use any file name arguments,
‘<samp>--append</samp>’ (‘<samp>-r</samp>’),
+‘<samp>--delete</samp>’ and
‘<samp>--concatenate</samp>’ (‘<samp>--catenate</samp>’,
+‘<samp>-A</samp>’) will do nothing, while
‘<samp>--create</samp>’ (‘<samp>-c</samp>’)
+will usually yield a diagnostic and inhibit <code>tar</code> execution.
+The other operations of <code>tar</code> (‘<samp>--list</samp>’,
+‘<samp>--extract</samp>’, ‘<samp>--compare</samp>’,
and ‘<samp>--update</samp>’)
+will act on the entire contents of the archive.
+</p>
+<a name="IDX28"></a>
+<a name="IDX29"></a>
+<p>Besides successful exits, <acronym>GNU</acronym> <code>tar</code> may fail
for
+many reasons. Some reasons correspond to bad usage, that is, when the
+<code>tar</code> 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 <code>tar</code> has completed all its work. Some
+errors are such that it would not meaningful, or at least risky, to
+continue processing: <code>tar</code> then aborts processing immediately.
+All abnormal exits, whether immediate or delayed, should always be
+clearly diagnosed on <code>stderr</code>, after a line stating the nature of
+the error.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> returns only a few exit statuses.
I'm really
+aiming simplicity in that area, for now. If you are not using the
+‘<samp>--compare</samp>’ ‘<samp>--diff</samp>’,
‘<samp>-d</samp>’) 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.
+</p>
+<hr size="6">
+<a name="using-tar-options"></a>
+<a name="SEC34"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC33" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC35" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 3.2 Using <code>tar</code> Options </h2>
+
+<p><acronym>GNU</acronym> <code>tar</code> 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 <code>tar</code> program by
+specifying one, and only one operation as an argument to the
+<code>tar</code> command (two lists of four operations each may be found
+at <a href="#SEC12">The Three Most Frequently Used Operations</a> and <a
href="#SEC51">The Five Advanced <code>tar</code> Operations</a>). 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.
+</p>
+<p>You can customize and control <code>tar</code>'s performance by running
+<code>tar</code> with one or more options (such as
‘<samp>--verbose</samp>’
+(‘<samp>-v</samp>’), which we used in the tutorial). As we said
in the
+tutorial, <em>options</em> are arguments to <code>tar</code> 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 see section <a
href="#SEC40">All <code>tar</code> Options</a>.)
+</p>
+<a name="IDX30"></a>
+<p><a name="TAR_005fOPTIONS"></a>
+The <code>TAR_OPTIONS</code> environment variable specifies default options to
+be placed in front of any explicit options. For example, if
+<code>TAR_OPTIONS</code> is ‘<samp>-v --unlink-first</samp>’,
<code>tar</code> behaves as
+if the two options ‘<samp>-v</samp>’ and
‘<samp>--unlink-first</samp>’ 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.
+</p>
+<p>Note that <code>tar</code> options are case sensitive. For example, the
+options ‘<samp>-T</samp>’ and ‘<samp>-t</samp>’ are
different; the first requires an
+argument for stating the name of a file providing a list of <var>name</var>s,
+while the second does not require an argument and is another way to
+write ‘<samp>--list</samp>’ (‘<samp>-t</samp>’).
+</p>
+<p>In addition to the eight operations, there are many options to
+<code>tar</code>, 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.
+</p>
+
+
+
+
+<hr size="6">
+<a name="Styles"></a>
+<a name="SEC35"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC34" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC36" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 3.3 The Three Option Styles </h2>
+
+<p>There are three styles for writing operations and options to the command
+line invoking <code>tar</code>. The different styles were developed at
+different times during the history of <code>tar</code>. These styles will be
+presented below, from the most recent to the oldest.
+</p>
+<p>Some options must take an argument. (For example,
‘<samp>--file</samp>’
+(‘<samp>-f</samp>’)) takes the name of an archive file as an
argument. If
+you do not supply an archive file name, <code>tar</code> will use a
+default, but this can be confusing; thus, we recommend that you always
+supply a specific archive file name.) Where you <em>place</em> 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.
+</p>
+<p>Some options <em>may</em> 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.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC36">3.3.1 Long Option
Style</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC37">3.3.2 Short Option
Style</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC38">3.3.3 Old Option
Style</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC39">3.3.4 Mixing Option
Styles</a></td><td> </td><td align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Long-Options"></a>
+<a name="SEC36"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC35" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC37" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC35" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 3.3.1 Long Option Style </h3>
+
+<p>Each option has at least one <em>long</em> (or <em>mnemonic</em>) name
starting with two
+dashes in a row, e.g., ‘<samp>--list</samp>’. 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 ‘<samp>--compare</samp>’ and
‘<samp>--diff</samp>’. In addition,
+long option names can be given unique abbreviations. For example,
+‘<samp>--cre</samp>’ can be used in place of
‘<samp>--create</samp>’ because there is no
+other long option which begins with ‘<samp>cre</samp>’. (One way
to find
+this out is by trying it and seeing what happens; if a particular
+abbreviation could represent more than one option, <code>tar</code> 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</samp>’
+to see a list of options. Be aware that if you run <code>tar</code> with a
+unique abbreviation for the long name of an option you didn't want to
+use, you are stuck; <code>tar</code> will perform the command as ordered.)
+</p>
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--verbose --blocking-factor=20 --file=/dev/rmt0</kbd>
+</pre></td></tr></table>
+
+<p>gives a fairly good set of hints about what the command does, even
+for those not fully acquainted with <code>tar</code>.
+</p>
+<p>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 ‘<samp>--file</samp>’
option (which
+tells the name of the <code>tar</code> archive) is given a file such as
+‘<tt>archive.tar</tt>’ as argument by using any of the following
notations:
+‘<samp>--file=archive.tar</samp>’ or ‘<samp>--file
archive.tar</samp>’.
+</p>
+<p>In contrast, optional arguments must always be introduced using
+an equal sign. For example, the ‘<samp>--backup</samp>’ option
takes
+an optional argument specifying backup type. It must be used
+as ‘<samp>--backup=<var>backup-type</var></samp>’.
+</p>
+<hr size="6">
+<a name="Short-Options"></a>
+<a name="SEC37"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC36" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC38" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC35" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 3.3.2 Short Option Style </h3>
+
+<p>Most options also have a <em>short option</em> name. Short options start
with
+a single dash, and are followed by a single character, e.g.,
‘<samp>-t</samp>’
+(which is equivalent to ‘<samp>--list</samp>’). The forms are
absolutely
+identical in function; they are interchangeable.
+</p>
+<p>The short option names are faster to type than long option names.
+</p>
+<p>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 ‘<samp>-f
+archive.tar</samp>’ or ‘<samp>-farchive.tar</samp>’ instead
of using
+‘<samp>--file=archive.tar</samp>’. Both
‘<samp>--file=<var>archive-name</var></samp>’ and
+‘<samp>-f <var>archive-name</var></samp>’ denote the option which
indicates a
+specific archive, here named ‘<tt>archive.tar</tt>’.
+</p>
+<p>Short options which take optional arguments take their arguments
+immediately following the option letter, <em>without any intervening
+white space characters</em>.
+</p>
+<p>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., ‘<samp><code>tar</code> -cvf</samp>’. Only the last
option in
+such a set is allowed to have an argument<a name="DOCF2" href="#FOOT2">(2)</a>.
+</p>
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -v -b 20
-f /dev/rmt0</kbd>
+</pre></td></tr></table>
+
+<p>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.
+</p>
+<hr size="6">
+<a name="Old-Options"></a>
+<a name="SEC38"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC37" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC39" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC35" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 3.3.3 Old Option Style </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>Like short options, <em>old options</em> are single letters. However, old
options
+must be written together as a single clumped set, without spaces separating
+them or dashes preceding them<a name="DOCF3" href="#FOOT3">(3)</a>. This set
+of letters must be the first to appear on the command line, after the
+<code>tar</code> 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</samp>’ is
+the same as the short option ‘<samp>-t</samp>’, and consequently,
the same as the
+long option ‘<samp>--list</samp>’. So for example, the command
‘<samp>tar
+cv</samp>’ specifies the option ‘<samp>-v</samp>’ in
addition to the operation ‘<samp>-c</samp>’.
+</p>
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cvbf 20
/dev/rmt0</kbd>
+</pre></td></tr></table>
+
+<p>Here, ‘<samp>20</samp>’ is the argument of
‘<samp>-b</samp>’ and ‘<samp>/dev/rmt0</samp>’ is
+the argument of ‘<samp>-f</samp>’.
+</p>
+<p>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 ‘<samp>tar cvbf 20 /dev/rmt0</samp>’,
for example,
+‘<samp>20</samp>’ is the argument for
‘<samp>-b</samp>’, ‘<samp>/dev/rmt0</samp>’ is the
+argument for ‘<samp>-f</samp>’, and ‘<samp>-v</samp>’
does not have a corresponding
+argument. Even using short options like in ‘<samp>tar -c -v -b 20 -f
+/dev/rmt0</samp>’ is clearer, putting all arguments next to the option
they
+pertain to.
+</p>
+<p>If you want to reorder the letters in the old option argument, be
+sure to reorder any corresponding argument appropriately.
+</p>
+<p>This old way of writing <code>tar</code> options can surprise even
experienced
+users. For example, the two commands:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar cfz
archive.tar.gz file</kbd>
+<kbd>tar -cfz archive.tar.gz file</kbd>
+</pre></td></tr></table>
+
+<p>are quite different. The first example uses
‘<tt>archive.tar.gz</tt>’ as
+the value for option ‘<samp>f</samp>’ and recognizes the option
‘<samp>z</samp>’. The
+second example, however, uses ‘<tt>z</tt>’ as the value for option
+‘<samp>f</samp>’ — probably not what was intended.
+</p>
+<p>Old options are kept for compatibility with old versions of
<code>tar</code>.
+</p>
+<p>This second example could be corrected in many ways, among which the
+following are equivalent:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar -czf
archive.tar.gz file</kbd>
+<kbd>tar -cf archive.tar.gz -z file</kbd>
+<kbd>tar cf archive.tar.gz -z file</kbd>
+</pre></td></tr></table>
+
+<a name="IDX31"></a>
+<p>As far as we know, all <code>tar</code> programs, <acronym>GNU</acronym> and
+non-<acronym>GNU</acronym>, support old options. <acronym>GNU</acronym>
<code>tar</code>
+supports them not only for historical reasons, but also because many
+people are used to them. For compatibility with Unix <code>tar</code>,
+the first argument is always treated as containing command and option
+letters even if it doesn't start with ‘<samp>-</samp>’. Thus,
‘<samp>tar c</samp>’ is
+equivalent to ‘<samp>tar -c</samp>’: both of them specify the
+‘<samp>--create</samp>’ (‘<samp>-c</samp>’) command to
create an archive.
+</p>
+<hr size="6">
+<a name="Mixing"></a>
+<a name="SEC39"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC38" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC40" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC35" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 3.3.4 Mixing Option Styles </h3>
+
+<p>All three styles may be intermixed in a single <code>tar</code> command,
+so long as the rules for each style are fully
+respected<a name="DOCF4" href="#FOOT4">(4)</a>. Old style options and either
of the modern styles of
+options may be mixed within a single <code>tar</code> 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 <code>tar</code> 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.
+</p>
+<p>For example, all the following commands are wholly equivalent, and
+illustrate the many combinations and orderings of option styles.
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar --create
--file=archive.tar</kbd>
+<kbd>tar --create -f archive.tar</kbd>
+<kbd>tar --create -farchive.tar</kbd>
+<kbd>tar --file=archive.tar --create</kbd>
+<kbd>tar --file=archive.tar -c</kbd>
+<kbd>tar -c --file=archive.tar</kbd>
+<kbd>tar -c -f archive.tar</kbd>
+<kbd>tar -c -farchive.tar</kbd>
+<kbd>tar -cf archive.tar</kbd>
+<kbd>tar -cfarchive.tar</kbd>
+<kbd>tar -f archive.tar --create</kbd>
+<kbd>tar -f archive.tar -c</kbd>
+<kbd>tar -farchive.tar --create</kbd>
+<kbd>tar -farchive.tar -c</kbd>
+<kbd>tar c --file=archive.tar</kbd>
+<kbd>tar c -f archive.tar</kbd>
+<kbd>tar c -farchive.tar</kbd>
+<kbd>tar cf archive.tar</kbd>
+<kbd>tar f archive.tar --create</kbd>
+<kbd>tar f archive.tar -c</kbd>
+<kbd>tar fc archive.tar</kbd>
+</pre></td></tr></table>
+
+<p>On the other hand, the following commands are <em>not</em> equivalent to
+the previous set:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar -f -c
archive.tar</kbd>
+<kbd>tar -fc archive.tar</kbd>
+<kbd>tar -fcarchive.tar</kbd>
+<kbd>tar -farchive.tarc</kbd>
+<kbd>tar cfarchive.tar</kbd>
+</pre></td></tr></table>
+
+<p>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 <code>tar</code> archive would be a file named
+‘<samp>-c</samp>’, ‘<samp>c</samp>’,
‘<samp>carchive.tar</samp>’ or
‘<samp>archive.tarc</samp>’,
+respectively. The first two examples also specify a single non-option,
+<var>name</var> argument having the value
‘<samp>archive.tar</samp>’. The last
+example contains only old style option letters (repeating option
+‘<samp>c</samp>’ twice), not all of which are meaningful (eg.,
‘<samp>.</samp>’,
+‘<samp>h</samp>’, or ‘<samp>i</samp>’), with no
argument value.
+
+</p>
+
+<hr size="6">
+<a name="All-Options"></a>
+<a name="SEC40"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC39" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC41" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 3.4 All <code>tar</code> Options </h2>
+
+<p>The coming manual sections contain an alphabetical listing of all
+<code>tar</code> 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 <code>tar</code> commands in scripts.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC41">3.4.1
Operations</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC42">3.4.2 <code>tar</code>
Options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC43">3.4.3 Short Options Cross
Reference</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Operation-Summary"></a>
+<a name="SEC41"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC40" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC42" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC40" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 3.4.1 Operations </h3>
+
+<dl compact="compact">
+<dd>
+<p><a name="g_t_002d_002dappend"></a>
+<a name="IDX32"></a>
+</p></dd>
+<dt> ‘<samp>--append</samp>’</dt>
+<dt> ‘<samp>-r</samp>’</dt>
+<dd>
+<p>Appends files to the end of the archive. See section <a href="#SEC52">How
to Add Files to Existing Archives: ‘<samp>--append</samp>’</a>.
+</p>
+<p><a name="g_t_002d_002dcatenate"></a>
+<a name="IDX33"></a>
+</p></dd>
+<dt> ‘<samp>--catenate</samp>’</dt>
+<dt> ‘<samp>-A</samp>’</dt>
+<dd>
+<p>Same as ‘<samp>--concatenate</samp>’. See section <a
href="#SEC57">Combining Archives with
‘<samp>--concatenate</samp>’</a>.
+</p>
+<p><a name="g_t_002d_002dcompare"></a>
+<a name="IDX34"></a>
+</p></dd>
+<dt> ‘<samp>--compare</samp>’</dt>
+<dt> ‘<samp>-d</samp>’</dt>
+<dd>
+<p>Compares archive members with their counterparts in the file
+system, and reports differences in file size, mode, owner,
+modification date and contents. See section <a href="#SEC59">Comparing
Archive Members with the File System</a>.
+</p>
+<p><a name="g_t_002d_002dconcatenate"></a>
+<a name="IDX35"></a>
+</p></dd>
+<dt> ‘<samp>--concatenate</samp>’</dt>
+<dt> ‘<samp>-A</samp>’</dt>
+<dd>
+<p>Appends other <code>tar</code> archives to the end of the archive.
+See section <a href="#SEC57">Combining Archives with
‘<samp>--concatenate</samp>’</a>.
+</p>
+<p><a name="g_t_002d_002dcreate"></a>
+<a name="IDX36"></a>
+</p></dd>
+<dt> ‘<samp>--create</samp>’</dt>
+<dt> ‘<samp>-c</samp>’</dt>
+<dd>
+<p>Creates a new <code>tar</code> archive. See section <a href="#SEC17">How
to Create Archives</a>.
+</p>
+<p><a name="g_t_002d_002ddelete"></a>
+<a name="IDX37"></a>
+</p></dd>
+<dt> ‘<samp>--delete</samp>’</dt>
+<dd>
+<p>Deletes members from the archive. Don't try this on a archive on a
+tape! See section <a href="#SEC58">Removing Archive Members Using
‘<samp>--delete</samp>’</a>.
+</p>
+<p><a name="g_t_002d_002ddiff"></a>
+<a name="IDX38"></a>
+</p></dd>
+<dt> ‘<samp>--diff</samp>’</dt>
+<dt> ‘<samp>-d</samp>’</dt>
+<dd>
+<p>Same ‘<samp>--compare</samp>’. See section <a
href="#SEC59">Comparing Archive Members with the File System</a>.
+</p>
+<p><a name="g_t_002d_002dextract"></a>
+<a name="IDX39"></a>
+</p></dd>
+<dt> ‘<samp>--extract</samp>’</dt>
+<dt> ‘<samp>-x</samp>’</dt>
+<dd>
+<p>Extracts members from the archive into the file system. See section <a
href="#SEC25">How to Extract Members from an Archive</a>.
+</p>
+<p><a name="g_t_002d_002dget"></a>
+<a name="IDX40"></a>
+</p></dd>
+<dt> ‘<samp>--get</samp>’</dt>
+<dt> ‘<samp>-x</samp>’</dt>
+<dd>
+<p>Same as ‘<samp>--extract</samp>’. See section <a
href="#SEC25">How to Extract Members from an Archive</a>.
+</p>
+<p><a name="g_t_002d_002dlist"></a>
+<a name="IDX41"></a>
+</p></dd>
+<dt> ‘<samp>--list</samp>’</dt>
+<dt> ‘<samp>-t</samp>’</dt>
+<dd>
+<p>Lists the members in an archive. See section <a href="#SEC23">How to List
Archives</a>.
+</p>
+<p><a name="g_t_002d_002dupdate"></a>
+<a name="IDX42"></a>
+</p></dd>
+<dt> ‘<samp>--update</samp>’</dt>
+<dt> ‘<samp>-u</samp>’</dt>
+<dd>
+<p>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. See section <a href="#SEC55">Updating an Archive</a>.
+</p>
+</dd>
+</dl>
+
+<hr size="6">
+<a name="Option-Summary"></a>
+<a name="SEC42"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC41" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC43" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC40" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 3.4.2 <code>tar</code> Options </h3>
+
+<dl compact="compact">
+<dd>
+<p><a name="g_t_002d_002dabsolute_002dnames"></a>
+<a name="IDX43"></a>
+</p></dd>
+<dt> ‘<samp>--absolute-names</samp>’</dt>
+<dt> ‘<samp>-P</samp>’</dt>
+<dd>
+<p>Normally when creating an archive, <code>tar</code> strips an initial
+‘<samp>/</samp>’ from member names. This option disables that
behavior.
+See section <a href="#SEC112">Absolute File Names</a>.
+</p>
+<p><a name="g_t_002d_002dafter_002ddate"></a>
+<a name="IDX44"></a>
+</p></dd>
+<dt> ‘<samp>--after-date</samp>’</dt>
+<dd>
+<p>(See ‘<samp>--newer</samp>’, see section <a
href="#SEC108">Operating Only on New Files</a>)
+</p>
+<p><a name="g_t_002d_002danchored"></a>
+<a name="IDX45"></a>
+</p></dd>
+<dt> ‘<samp>--anchored</samp>’</dt>
+<dd><p>A pattern must match an initial subsequence of the name's components.
+See section <a href="#SEC105">Controlling Pattern-Matching</a>.
+</p>
+<p><a name="g_t_002d_002datime_002dpreserve"></a>
+<a name="IDX46"></a>
+</p></dd>
+<dt> ‘<samp>--atime-preserve</samp>’</dt>
+<dt> ‘<samp>--atime-preserve=replace</samp>’</dt>
+<dt> ‘<samp>--atime-preserve=system</samp>’</dt>
+<dd>
+<p>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.
+</p>
+<p>‘<samp>--atime-preserve=replace</samp>’ 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 <code>tar</code> 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.
+</p>
+<p>‘<samp>--atime-preserve=system</samp>’ 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</code> 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
+<code>tar</code> knows that it does not work, and if you use
+‘<samp>--atime-preserve=system</samp>’ then <code>tar</code>
complains and
+exits right away. But other times <code>tar</code> might think that the
+option works when it actually does not.
+</p>
+<p>Currently ‘<samp>--atime-preserve</samp>’ with no operand
defaults to
+‘<samp>--atime-preserve=replace</samp>’, but this may change in
the future
+as support for ‘<samp>--atime-preserve=system</samp>’ improves.
+</p>
+<p>If your operating system does not support
+‘<samp>--atime-preserve=system</samp>’, you might be able to
preserve access
+times reliably by by using the <code>mount</code> 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</samp>’
mount option
+available on some systems. However, mounting typically requires
+superuser privileges and can be a pain to manage.
+</p>
+<p><a name="g_t_002d_002dbackup"></a>
+<a name="IDX47"></a>
+</p></dd>
+<dt> ‘<samp>--backup=<var>backup-type</var></samp>’</dt>
+<dd>
+<p>Rather than deleting files from the file system, <code>tar</code> will
+back them up using simple or numbered backups, depending upon
+<var>backup-type</var>. See section <a href="#SEC83">Backup options</a>.
+</p>
+<p><a name="g_t_002d_002dblock_002dnumber"></a>
+<a name="IDX48"></a>
+</p></dd>
+<dt> ‘<samp>--block-number</samp>’</dt>
+<dt> ‘<samp>-R</samp>’</dt>
+<dd>
+<p>With this option present, <code>tar</code> prints error messages for read
errors
+with the block number in the archive file. See <a
href="#block_002dnumber">block-number</a>.
+</p>
+<p><a name="g_t_002d_002dblocking_002dfactor"></a>
+<a name="IDX49"></a>
+</p></dd>
+<dt> ‘<samp>--blocking-factor=<var>blocking</var></samp>’</dt>
+<dt> ‘<samp>-b <var>blocking</var></samp>’</dt>
+<dd>
+<p>Sets the blocking factor <code>tar</code> uses to <var>blocking</var> x 512
bytes per
+record. See section <a href="#SEC149">The Blocking Factor of an Archive</a>.
+</p>
+<p><a name="g_t_002d_002dbzip2"></a>
+<a name="IDX50"></a>
+</p></dd>
+<dt> ‘<samp>--bzip2</samp>’</dt>
+<dt> ‘<samp>-j</samp>’</dt>
+<dd>
+<p>This option tells <code>tar</code> to read or write archives through
+<code>bzip2</code>. See section <a href="#SEC126">Creating and Reading
Compressed Archives</a>.
+</p>
+<p><a name="g_t_002d_002dcheckpoint"></a>
+<a name="IDX51"></a>
+</p></dd>
+<dt> ‘<samp>--checkpoint[=<var>number</var>]</samp>’</dt>
+<dd>
+<p>This option directs <code>tar</code> to print periodic checkpoint
+messages as it reads through the archive. It is intended for when you
+want a visual indication that <code>tar</code> is still running, but
+don't want to see ‘<samp>--verbose</samp>’ output. For a detailed
+description, see <a href="#Progress-information">Progress information</a>.
+</p>
+<p><a name="g_t_002d_002dcheck_002dlinks"></a>
+<a name="IDX52"></a>
+</p></dd>
+<dt> ‘<samp>--check-links</samp>’</dt>
+<dt> ‘<samp>-l</samp>’</dt>
+<dd><p>If this option was given, <code>tar</code> 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 <a name="DOCF5" href="#FOOT5">(5)</a>.
+</p>
+<p><a name="g_t_002d_002dcompress"></a>
+<a name="IDX53"></a>
+<a name="g_t_002d_002duncompress"></a>
+<a name="IDX54"></a>
+</p></dd>
+<dt> ‘<samp>--compress</samp>’</dt>
+<dt> ‘<samp>--uncompress</samp>’</dt>
+<dt> ‘<samp>-Z</samp>’</dt>
+<dd>
+<p><code>tar</code> will use the <code>compress</code> program when reading or
+writing the archive. This allows you to directly act on archives
+while saving space. See section <a href="#SEC126">Creating and Reading
Compressed Archives</a>.
+</p>
+<p><a name="g_t_002d_002dconfirmation"></a>
+<a name="IDX55"></a>
+</p></dd>
+<dt> ‘<samp>--confirmation</samp>’</dt>
+<dd>
+<p>(See ‘<samp>--interactive</samp>’.) See section <a
href="#SEC47">Asking for Confirmation During Operations</a>.
+</p>
+<p><a name="g_t_002d_002ddelay_002ddirectory_002drestore"></a>
+<a name="IDX56"></a>
+</p></dd>
+<dt> ‘<samp>--delay-directory-restore</samp>’</dt>
+<dd>
+<p>Delay setting modification times and permissions of extracted
+directories until the end of extraction. See section <a
href="#SEC76">Directory Modification Times and Permissions</a>.
+</p>
+<p><a name="g_t_002d_002ddereference"></a>
+<a name="IDX57"></a>
+</p></dd>
+<dt> ‘<samp>--dereference</samp>’</dt>
+<dt> ‘<samp>-h</samp>’</dt>
+<dd>
+<p>When creating a <code>tar</code> archive, <code>tar</code> will archive the
+file that a symbolic link points to, rather than archiving the
+symlink. See section <a href="#SEC131">Symbolic Links</a>.
+</p>
+<p><a name="g_t_002d_002ddirectory"></a>
+<a name="IDX58"></a>
+</p></dd>
+<dt> ‘<samp>--directory=<var>dir</var></samp>’</dt>
+<dt> ‘<samp>-C <var>dir</var></samp>’</dt>
+<dd>
+<p>When this option is specified, <code>tar</code> will change its current
directory
+to <var>dir</var> before performing any operations. When this option is used
+during archive creation, it is order sensitive. See section <a
href="#SEC111">Changing the Working Directory</a>.
+</p>
+<p><a name="g_t_002d_002dexclude"></a>
+<a name="IDX59"></a>
+</p></dd>
+<dt> ‘<samp>--exclude=<var>pattern</var></samp>’</dt>
+<dd>
+<p>When performing operations, <code>tar</code> will skip files that match
+<var>pattern</var>. See section <a href="#SEC102">Excluding Some Files</a>.
+</p>
+<p><a name="g_t_002d_002dexclude_002dfrom"></a>
+<a name="IDX60"></a>
+</p></dd>
+<dt> ‘<samp>--exclude-from=<var>file</var></samp>’</dt>
+<dt> ‘<samp>-X <var>file</var></samp>’</dt>
+<dd>
+<p>Similar to ‘<samp>--exclude</samp>’, except <code>tar</code>
will use the list of
+patterns in the file <var>file</var>. See section <a href="#SEC102">Excluding
Some Files</a>.
+</p>
+<p><a name="g_t_002d_002dexclude_002dcaches"></a>
+<a name="IDX61"></a>
+</p></dd>
+<dt> ‘<samp>--exclude-caches</samp>’</dt>
+<dd>
+<p>Automatically excludes all directories
+containing a cache directory tag. See section <a href="#SEC102">Excluding
Some Files</a>.
+</p>
+<p><a name="g_t_002d_002dfile"></a>
+<a name="IDX62"></a>
+</p></dd>
+<dt> ‘<samp>--file=<var>archive</var></samp>’</dt>
+<dt> ‘<samp>-f <var>archive</var></samp>’</dt>
+<dd>
+<p><code>tar</code> will use the file <var>archive</var> as the
<code>tar</code> archive it
+performs operations on, rather than <code>tar</code>'s compilation dependent
+default. See section <a href="#SEC14">The ‘<samp>--file</samp>’
Option</a>.
+</p>
+<p><a name="g_t_002d_002dfiles_002dfrom"></a>
+<a name="IDX63"></a>
+</p></dd>
+<dt> ‘<samp>--files-from=<var>file</var></samp>’</dt>
+<dt> ‘<samp>-T <var>file</var></samp>’</dt>
+<dd>
+<p><code>tar</code> will use the contents of <var>file</var> as a list of
archive members
+or files to operate on, in addition to those specified on the
+command-line. See section <a href="#SEC100">Reading Names from a File</a>.
+</p>
+<p><a name="g_t_002d_002dforce_002dlocal"></a>
+<a name="IDX64"></a>
+</p></dd>
+<dt> ‘<samp>--force-local</samp>’</dt>
+<dd>
+<p>Forces <code>tar</code> to interpret the filename given to
‘<samp>--file</samp>’
+as a local file, even if it looks like a remote tape drive name.
+See <a href="#local-and-remote-archives">local and remote archives</a>.
+</p>
+<p><a name="g_t_002d_002dformat"></a>
+<a name="IDX65"></a>
+</p></dd>
+<dt> ‘<samp>--format=<var>format</var></samp>’</dt>
+<dt> ‘<samp>-H <var>format</var></samp>’</dt>
+<dd>
+<p>Selects output archive format. <var>Format</var> may be one of the
+following:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>v7</samp>’</dt>
+<dd><p>Creates an archive that is compatible with Unix V7 <code>tar</code>.
+</p>
+</dd>
+<dt> ‘<samp>oldgnu</samp>’</dt>
+<dd><p>Creates an archive that is compatible with GNU <code>tar</code> version
+1.12 or earlier.
+</p>
+</dd>
+<dt> ‘<samp>gnu</samp>’</dt>
+<dd><p>Creates archive in GNU tar 1.13 format. Basically it is the same as
+‘<samp>oldgnu</samp>’ with the only difference in the way it
handles long
+numeric fields.
+</p>
+</dd>
+<dt> ‘<samp>ustar</samp>’</dt>
+<dd><p>Creates a <acronym>POSIX.1-1988</acronym> compatible archive.
+</p>
+</dd>
+<dt> ‘<samp>posix</samp>’</dt>
+<dd><p>Creates a <acronym>POSIX.1-2001 archive</acronym>.
+</p>
+</dd>
+</dl>
+
+<p>See section <a href="#SEC124">Controlling the Archive Format</a>, for a
detailed discussion of these formats.
+</p>
+<p><a name="g_t_002d_002dgroup"></a>
+<a name="IDX66"></a>
+</p></dd>
+<dt> ‘<samp>--group=<var>group</var></samp>’</dt>
+<dd>
+<p>Files added to the <code>tar</code> archive will have a group id of
<var>group</var>,
+rather than the group from the source file. <var>group</var> is first decoded
+as a group symbolic name, but if this interpretation fails, it has to be
+a decimal numeric group ID. See section <a href="#SEC61">Overriding File
Metadata</a>.
+</p>
+<p>Also see the comments for the
‘<samp>--owner=<var>user</var></samp>’ option.
+</p>
+<p><a name="g_t_002d_002dgzip"></a>
+<a name="IDX67"></a>
+<a name="g_t_002d_002dgunzip"></a>
+<a name="IDX68"></a>
+<a name="g_t_002d_002dungzip"></a>
+<a name="IDX69"></a>
+</p></dd>
+<dt> ‘<samp>--gzip</samp>’</dt>
+<dt> ‘<samp>--gunzip</samp>’</dt>
+<dt> ‘<samp>--ungzip</samp>’</dt>
+<dt> ‘<samp>-z</samp>’</dt>
+<dd>
+<p>This option tells <code>tar</code> to read or write archives through
+<code>gzip</code>, allowing <code>tar</code> to directly operate on several
+kinds of compressed archives transparently. See section <a
href="#SEC126">Creating and Reading Compressed Archives</a>.
+</p>
+<p><a name="g_t_002d_002dhelp"></a>
+<a name="IDX70"></a>
+</p></dd>
+<dt> ‘<samp>--help</samp>’</dt>
+<dt> ‘<samp>-?</samp>’</dt>
+<dd>
+<p><code>tar</code> will print out a short message summarizing the operations
and
+options to <code>tar</code> and exit. See section <a
href="#SEC44"><acronym>GNU</acronym> <code>tar</code> documentation</a>.
+</p>
+<p><a name="g_t_002d_002dignore_002dcase"></a>
+<a name="IDX71"></a>
+</p></dd>
+<dt> ‘<samp>--ignore-case</samp>’</dt>
+<dd><p>Ignore case when matching member or file names with
+patterns. See section <a href="#SEC105">Controlling Pattern-Matching</a>.
+</p>
+<p><a name="g_t_002d_002dignore_002dcommand_002derror"></a>
+<a name="IDX72"></a>
+</p></dd>
+<dt> ‘<samp>--ignore-command-error</samp>’</dt>
+<dd><p>Ignore exit codes of subprocesses. See section <a href="#SEC78">Writing
to an External Program</a>.
+</p>
+<p><a name="g_t_002d_002dignore_002dfailed_002dread"></a>
+<a name="IDX73"></a>
+</p></dd>
+<dt> ‘<samp>--ignore-failed-read</samp>’</dt>
+<dd>
+<p>Do not exit unsuccessfully merely because an unreadable file was
encountered.
+See section <a href="#SEC64">Options to Help Read Archives</a>.
+</p>
+<p><a name="g_t_002d_002dignore_002dzeros"></a>
+<a name="IDX74"></a>
+</p></dd>
+<dt> ‘<samp>--ignore-zeros</samp>’</dt>
+<dt> ‘<samp>-i</samp>’</dt>
+<dd>
+<p>With this option, <code>tar</code> will ignore zeroed blocks in the
+archive, which normally signals EOF. See section <a href="#SEC64">Options to
Help Read Archives</a>.
+</p>
+<p><a name="g_t_002d_002dincremental"></a>
+<a name="IDX75"></a>
+</p></dd>
+<dt> ‘<samp>--incremental</samp>’</dt>
+<dt> ‘<samp>-G</samp>’</dt>
+<dd>
+<p>Used to inform <code>tar</code> that it is working with an old
+<acronym>GNU</acronym>-format incremental backup archive. It is intended
+primarily for backwards compatibility only. See section <a
href="#SEC88">Using <code>tar</code> to Perform Incremental Dumps</a>,
+for a detailed discussion of incremental archives.
+</p>
+<p><a name="g_t_002d_002dindex_002dfile"></a>
+<a name="IDX76"></a>
+</p></dd>
+<dt> ‘<samp>--index-file=<var>file</var></samp>’</dt>
+<dd>
+<p>Send verbose output to <var>file</var> instead of to standard output.
+</p>
+<p><a name="g_t_002d_002dinfo_002dscript"></a>
+<a name="IDX77"></a>
+<a name="g_t_002d_002dnew_002dvolume_002dscript"></a>
+<a name="IDX78"></a>
+</p></dd>
+<dt> ‘<samp>--info-script=<var>script-file</var></samp>’</dt>
+<dt> ‘<samp>--new-volume-script=<var>script-file</var></samp>’</dt>
+<dt> ‘<samp>-F <var>script-file</var></samp>’</dt>
+<dd>
+<p>When <code>tar</code> is performing multi-tape backups,
<var>script-file</var> is run
+at the end of each tape. If <var>script-file</var> exits with nonzero status,
+<code>tar</code> fails immediately. See <a
href="#info_002dscript">info-script</a>, for a detailed
+discussion of <var>script-file</var>.
+</p>
+<p><a name="g_t_002d_002dinteractive"></a>
+<a name="IDX79"></a>
+</p></dd>
+<dt> ‘<samp>--interactive</samp>’</dt>
+<dt> ‘<samp>--confirmation</samp>’</dt>
+<dt> ‘<samp>-w</samp>’</dt>
+<dd>
+<p>Specifies that <code>tar</code> should ask the user for confirmation before
+performing potentially destructive options, such as overwriting files.
+See section <a href="#SEC47">Asking for Confirmation During Operations</a>.
+</p>
+<p><a name="g_t_002d_002dkeep_002dnewer_002dfiles"></a>
+<a name="IDX80"></a>
+</p></dd>
+<dt> ‘<samp>--keep-newer-files</samp>’</dt>
+<dd>
+<p>Do not replace existing files that are newer than their archive copies
+when extracting files from an archive.
+</p>
+<p><a name="g_t_002d_002dkeep_002dold_002dfiles"></a>
+<a name="IDX81"></a>
+</p></dd>
+<dt> ‘<samp>--keep-old-files</samp>’</dt>
+<dt> ‘<samp>-k</samp>’</dt>
+<dd>
+<p>Do not overwrite existing files when extracting files from an archive.
+See section <a href="#SEC70">Keep Old Files</a>.
+</p>
+<p><a name="g_t_002d_002dlabel"></a>
+<a name="IDX82"></a>
+</p></dd>
+<dt> ‘<samp>--label=<var>name</var></samp>’</dt>
+<dt> ‘<samp>-V <var>name</var></samp>’</dt>
+<dd>
+<p>When creating an archive, instructs <code>tar</code> to write
<var>name</var>
+as a name record in the archive. When extracting or listing archives,
+<code>tar</code> will only operate on archives that have a label matching
+the pattern specified in <var>name</var>. See section <a href="#SEC155">Tape
Files</a>.
+</p>
+<p><a name="g_t_002d_002dlisted_002dincremental"></a>
+<a name="IDX83"></a>
+</p></dd>
+<dt>
‘<samp>--listed-incremental=<var>snapshot-file</var></samp>’</dt>
+<dt> ‘<samp>-g <var>snapshot-file</var></samp>’</dt>
+<dd>
+<p>During a ‘<samp>--create</samp>’ operation, specifies that the
archive that
+<code>tar</code> creates is a new <acronym>GNU</acronym>-format incremental
+backup, using <var>snapshot-file</var> to determine which files to backup.
+With other operations, informs <code>tar</code> that the archive is in
+incremental format. See section <a href="#SEC88">Using <code>tar</code> to
Perform Incremental Dumps</a>.
+</p>
+<p><a name="g_t_002d_002dmode"></a>
+<a name="IDX84"></a>
+</p></dd>
+<dt> ‘<samp>--mode=<var>permissions</var></samp>’</dt>
+<dd>
+<p>When adding files to an archive, <code>tar</code> will use
+<var>permissions</var> for the archive members, rather than the permissions
+from the files. <var>permissions</var> can be specified either as an octal
+number or as symbolic permissions, like with
+<code>chmod</code>. See section <a href="#SEC61">Overriding File Metadata</a>.
+</p>
+<p><a name="g_t_002d_002dmtime"></a>
+<a name="IDX85"></a>
+</p></dd>
+<dt> ‘<samp>--mtime=<var>date</var></samp>’</dt>
+<dd>
+<p>When adding files to an archive, <code>tar</code> will use <var>date</var>
as
+the modification time of members when creating archives, instead of
+their actual modification times. The value of <var>date</var> can be
+either a textual date representation (see section <a href="#SEC113">Date input
formats</a>) or a
+name of the existing file, starting with ‘<samp>/</samp>’ or
‘<samp>.</samp>’. In the
+latter case, the modification time of that file is used. See section <a
href="#SEC61">Overriding File Metadata</a>.
+</p>
+<p><a name="g_t_002d_002dmulti_002dvolume"></a>
+<a name="IDX86"></a>
+</p></dd>
+<dt> ‘<samp>--multi-volume</samp>’</dt>
+<dt> ‘<samp>-M</samp>’</dt>
+<dd>
+<p>Informs <code>tar</code> that it should create or otherwise operate on a
+multi-volume <code>tar</code> archive. See section <a href="#SEC153">Using
Multiple Tapes</a>.
+</p>
+<a name="IDX87"></a>
+</dd>
+<dt> ‘<samp>--new-volume-script</samp>’</dt>
+<dd>
+<p>(see –info-script)
+</p>
+<p><a name="g_t_002d_002dseek"></a>
+<a name="IDX88"></a>
+</p></dd>
+<dt> ‘<samp>--seek</samp>’</dt>
+<dt> ‘<samp>-n</samp>’</dt>
+<dd>
+<p>Assume that the archive media supports seeks to arbitrary
+locations. Usually <code>tar</code> determines automatically whether
+the archive can be seeked or not. This option is intended for use
+in cases when such recognition fails.
+</p>
+<p><a name="g_t_002d_002dnewer"></a>
+<a name="IDX89"></a>
+</p></dd>
+<dt> ‘<samp>--newer=<var>date</var></samp>’</dt>
+<dt> ‘<samp>--after-date=<var>date</var></samp>’</dt>
+<dt> ‘<samp>-N</samp>’</dt>
+<dd>
+<p>When creating an archive, <code>tar</code> will only add files that have
changed
+since <var>date</var>. If <var>date</var> begins with
‘<samp>/</samp>’ or ‘<samp>.</samp>’, it
+is taken to be the name of a file whose data modification time specifies
+the date. See section <a href="#SEC108">Operating Only on New Files</a>.
+</p>
+<p><a name="g_t_002d_002dnewer_002dmtime"></a>
+<a name="IDX90"></a>
+</p></dd>
+<dt> ‘<samp>--newer-mtime=<var>date</var></samp>’</dt>
+<dd>
+<p>Like ‘<samp>--newer</samp>’, but add only files whose
+contents have changed (as opposed to just ‘<samp>--newer</samp>’,
which will
+also back up files for which any status information has
+changed). See section <a href="#SEC108">Operating Only on New Files</a>.
+</p>
+<p><a name="g_t_002d_002dno_002danchored"></a>
+<a name="IDX91"></a>
+</p></dd>
+<dt> ‘<samp>--no-anchored</samp>’</dt>
+<dd><p>An exclude pattern can match any subsequence of the name's components.
+See section <a href="#SEC105">Controlling Pattern-Matching</a>.
+</p>
+<p><a name="g_t_002d_002dno_002ddelay_002ddirectory_002drestore"></a>
+<a name="IDX92"></a>
+</p></dd>
+<dt> ‘<samp>--no-delay-directory-restore</samp>’</dt>
+<dd>
+<p>Setting modification times and permissions of extracted
+directories when all files from this directory has been
+extracted. This is the default. See section <a href="#SEC76">Directory
Modification Times and Permissions</a>.
+</p>
+<p><a name="g_t_002d_002dno_002dignore_002dcase"></a>
+<a name="IDX93"></a>
+</p></dd>
+<dt> ‘<samp>--no-ignore-case</samp>’</dt>
+<dd><p>Use case-sensitive matching.
+See section <a href="#SEC105">Controlling Pattern-Matching</a>.
+</p>
+<p><a name="g_t_002d_002dno_002dignore_002dcommand_002derror"></a>
+<a name="IDX94"></a>
+</p></dd>
+<dt> ‘<samp>--no-ignore-command-error</samp>’</dt>
+<dd><p>Print warnings about subprocesses terminated with a non-zero exit
+code. See section <a href="#SEC78">Writing to an External Program</a>.
+</p>
+<p><a name="g_t_002d_002dno_002doverwrite_002ddir"></a>
+<a name="IDX95"></a>
+</p></dd>
+<dt> ‘<samp>--no-overwrite-dir</samp>’</dt>
+<dd>
+<p>Preserve metadata of existing directories when extracting files
+from an archive. See section <a href="#SEC69">Overwrite Old Files</a>.
+</p>
+<p><a name="g_t_002d_002dno_002dquote_002dchars"></a>
+<a name="IDX96"></a>
+</p></dd>
+<dt> ‘<samp>--no-quote-chars=<var>string</var></samp>’</dt>
+<dd><p>Remove characters listed in <var>string</var> from the list of quoted
+characters set by the previous ‘<samp>--quote-chars</samp>’ option
+(see section <a href="#SEC106">Quoting Member Names</a>).
+</p>
+<p><a name="g_t_002d_002dno_002drecursion"></a>
+<a name="IDX97"></a>
+</p></dd>
+<dt> ‘<samp>--no-recursion</samp>’</dt>
+<dd>
+<p>With this option, <code>tar</code> will not recurse into directories.
+See section <a href="#SEC109">Descending into Directories</a>.
+</p>
+<p><a name="g_t_002d_002dno_002dsame_002downer"></a>
+<a name="IDX98"></a>
+</p></dd>
+<dt> ‘<samp>--no-same-owner</samp>’</dt>
+<dt> ‘<samp>-o</samp>’</dt>
+<dd>
+<p>When extracting an archive, do not attempt to preserve the owner
+specified in the <code>tar</code> archive. This the default behavior
+for ordinary users.
+</p>
+<p><a name="g_t_002d_002dno_002dsame_002dpermissions"></a>
+<a name="IDX99"></a>
+</p></dd>
+<dt> ‘<samp>--no-same-permissions</samp>’</dt>
+<dd>
+<p>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.
+</p>
+<p><a name="g_t_002d_002dno_002dunquote"></a>
+<a name="IDX100"></a>
+</p></dd>
+<dt> ‘<samp>--no-unquote</samp>’</dt>
+<dd><p>Treat all input file or member names literally, do not interpret
+escape sequences. See <a href="#input-name-quoting">input name quoting</a>.
+</p>
+<p><a name="g_t_002d_002dno_002dwildcards"></a>
+<a name="IDX101"></a>
+</p></dd>
+<dt> ‘<samp>--no-wildcards</samp>’</dt>
+<dd><p>Do not use wildcards.
+See section <a href="#SEC105">Controlling Pattern-Matching</a>.
+</p>
+<p><a name="g_t_002d_002dno_002dwildcards_002dmatch_002dslash"></a>
+<a name="IDX102"></a>
+</p></dd>
+<dt> ‘<samp>--no-wildcards-match-slash</samp>’</dt>
+<dd><p>Wildcards do not match ‘<samp>/</samp>’.
+See section <a href="#SEC105">Controlling Pattern-Matching</a>.
+</p>
+<p><a name="g_t_002d_002dnull"></a>
+<a name="IDX103"></a>
+</p></dd>
+<dt> ‘<samp>--null</samp>’</dt>
+<dd>
+<p>When <code>tar</code> is using the ‘<samp>--files-from</samp>’
option, this option
+instructs <code>tar</code> to expect filenames terminated with
‘<samp>NUL</samp>’, so
+<code>tar</code> can correctly work with file names that contain newlines.
+See section <a href="#SEC101"><code>NUL</code> Terminated File Names</a>.
+</p>
+<p><a name="g_t_002d_002dnumeric_002downer"></a>
+<a name="IDX104"></a>
+</p></dd>
+<dt> ‘<samp>--numeric-owner</samp>’</dt>
+<dd>
+<p>This option will notify <code>tar</code> that it should use numeric user
+and group IDs when creating a <code>tar</code> file, rather than names.
+See section <a href="#SEC128">Handling File Attributes</a>.
+</p>
+</dd>
+<dt> ‘<samp>-o</samp>’</dt>
+<dd><p>The function of this option depends on the action <code>tar</code> is
+performing. When extracting files, ‘<samp>-o</samp>’ is a synonym
for
+‘<samp>--no-same-owner</samp>’, i.e. it prevents <code>tar</code>
from
+restoring ownership of files being extracted.
+</p>
+<p>When creating an archive, it is a synonym for
+‘<samp>--old-archive</samp>’. This behavior is for compatibility
+with previous versions of <acronym>GNU</acronym> <code>tar</code>, and will be
+removed in the future releases.
+</p>
+<p>See section <a href="#SEC160">Changes</a>, for more information.
+</p>
+<p><a name="g_t_002d_002doccurrence"></a>
+<a name="IDX105"></a>
+</p></dd>
+<dt> ‘<samp>--occurrence[=<var>number</var>]</samp>’</dt>
+<dd>
+<p>This option can be used in conjunction with one of the subcommands
+‘<samp>--delete</samp>’, ‘<samp>--diff</samp>’,
‘<samp>--extract</samp>’ or
+‘<samp>--list</samp>’ when a list of files is given either on the
command
+line or via ‘<samp>-T</samp>’ option.
+</p>
+<p>This option instructs <code>tar</code> to process only the
<var>number</var>th
+occurrence of each named file. <var>Number</var> defaults to 1, so
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar -x -f archive.tar
--occurrence filename
+</pre></td></tr></table>
+
+<p>will extract the first occurrence of the member
‘<tt>filename</tt>’ from ‘<tt>archive.tar</tt>’
+and will terminate without scanning to the end of the archive.
+</p>
+<p><a name="g_t_002d_002dold_002darchive"></a>
+<a name="IDX106"></a>
+</p></dd>
+<dt> ‘<samp>--old-archive</samp>’</dt>
+<dd><p>Synonym for ‘<samp>--format=v7</samp>’.
+</p>
+<p><a name="g_t_002d_002done_002dfile_002dsystem"></a>
+<a name="IDX107"></a>
+</p></dd>
+<dt> ‘<samp>--one-file-system</samp>’</dt>
+<dd><p>Used when creating an archive. Prevents <code>tar</code> from
recursing into
+directories that are on different file systems from the current
+directory <a name="DOCF6" href="#FOOT6">(6)</a>.
+</p>
+<p><a name="g_t_002d_002doverwrite"></a>
+<a name="IDX108"></a>
+</p></dd>
+<dt> ‘<samp>--overwrite</samp>’</dt>
+<dd>
+<p>Overwrite existing files and directory metadata when extracting files
+from an archive. See section <a href="#SEC69">Overwrite Old Files</a>.
+</p>
+<p><a name="g_t_002d_002doverwrite_002ddir"></a>
+<a name="IDX109"></a>
+</p></dd>
+<dt> ‘<samp>--overwrite-dir</samp>’</dt>
+<dd>
+<p>Overwrite the metadata of existing directories when extracting files
+from an archive. See section <a href="#SEC69">Overwrite Old Files</a>.
+</p>
+<p><a name="g_t_002d_002downer"></a>
+<a name="IDX110"></a>
+</p></dd>
+<dt> ‘<samp>--owner=<var>user</var></samp>’</dt>
+<dd>
+<p>Specifies that <code>tar</code> should use <var>user</var> as the owner of
members
+when creating archives, instead of the user associated with the source
+file. <var>user</var> is first decoded as a user symbolic name, but if
+this interpretation fails, it has to be a decimal numeric user ID.
+See section <a href="#SEC61">Overriding File Metadata</a>.
+</p>
+<p>This option does not affect extraction from archives.
+</p>
+<p><a name="g_t_002d_002dtransform"></a>
+<a name="IDX111"></a>
+</p></dd>
+<dt> ‘<samp>--transform=<var>sed-expr</var></samp>’</dt>
+<dd>
+<p>Transform file or member names using <code>sed</code> replacement expression
+<var>sed-expr</var>. For example,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cf
archive.tar --transform 's,^\./,usr/,' .</kbd>
+</pre></td></tr></table>
+
+<p>will add to ‘<tt>archive</tt>’ files from the current working
directory,
+replacing initial ‘<samp>./</samp>’ prefix with
‘<samp>usr/</samp>’. For the detailed
+discussion, See section <a href="#SEC107">Modifying File and Member Names</a>.
+</p>
+<p>To see transformed member names in verbose listings, use
+‘<samp>--show-transformed-names</samp>’ option
+(see <a href="#show_002dtransformed_002dnames">show-transformed-names</a>).
+</p>
+<p><a name="g_t_002d_002dquote_002dchars"></a>
+<a name="IDX112"></a>
+</p></dd>
+<dt> ‘<samp>--quote-chars=<var>string</var></samp>’</dt>
+<dd><p>Always quote characters from <var>string</var>, even if the selected
+quoting style would not quote them (see section <a href="#SEC106">Quoting
Member Names</a>).
+</p>
+<p><a name="g_t_002d_002dquoting_002dstyle"></a>
+<a name="IDX113"></a>
+</p></dd>
+<dt> ‘<samp>--quoting-style=<var>style</var></samp>’</dt>
+<dd><p>Set quoting style to use when printing member and file names
+(see section <a href="#SEC106">Quoting Member Names</a>). Valid
<var>style</var> values are:
+<code>literal</code>, <code>shell</code>, <code>shell-always</code>,
<code>c</code>,
+<code>escape</code>, <code>locale</code>, and <code>clocale</code>. Default
quoting
+style is <code>escape</code>, unless overridden while configuring the
+package.
+</p>
+<p><a name="g_t_002d_002dpax_002doption"></a>
+<a name="IDX114"></a>
+</p></dd>
+<dt> ‘<samp>--pax-option=<var>keyword-list</var></samp>’</dt>
+<dd><p>This option is meaningful only with <acronym>POSIX.1-2001</acronym>
archives
+(see section <a href="#SEC135"><acronym>GNU</acronym> <code>tar</code> and
<acronym>POSIX</acronym> <code>tar</code></a>). It modifies the way
<code>tar</code> handles the
+extended header keywords. <var>Keyword-list</var> is a comma-separated
+list of keyword options. See section <a href="#SEC136">Controlling Extended
Header Keywords</a>, for a detailed
+discussion.
+</p>
+<p><a name="g_t_002d_002dportability"></a>
+<a name="IDX115"></a>
+</p></dd>
+<dt> ‘<samp>--portability</samp>’</dt>
+<dt> ‘<samp>--old-archive</samp>’</dt>
+<dd><p>Synonym for ‘<samp>--format=v7</samp>’.
+</p>
+<p><a name="g_t_002d_002dposix"></a>
+<a name="IDX116"></a>
+</p></dd>
+<dt> ‘<samp>--posix</samp>’</dt>
+<dd><p>Same as ‘<samp>--format=posix</samp>’.
+</p>
+<p><a name="g_t_002d_002dpreserve"></a>
+<a name="IDX117"></a>
+</p></dd>
+<dt> ‘<samp>--preserve</samp>’</dt>
+<dd>
+<p>Synonymous with specifying both
‘<samp>--preserve-permissions</samp>’ and
+‘<samp>--same-order</samp>’. See section <a href="#SEC75">Setting
Access Permissions</a>.
+</p>
+<p><a name="g_t_002d_002dpreserve_002dorder"></a>
+<a name="IDX118"></a>
+</p></dd>
+<dt> ‘<samp>--preserve-order</samp>’</dt>
+<dd>
+<p>(See ‘<samp>--same-order</samp>’; see section <a
href="#SEC64">Options to Help Read Archives</a>.)
+</p>
+<p><a name="g_t_002d_002dpreserve_002dpermissions"></a>
+<a name="IDX119"></a>
+<a name="g_t_002d_002dsame_002dpermissions"></a>
+<a name="IDX120"></a>
+</p></dd>
+<dt> ‘<samp>--preserve-permissions</samp>’</dt>
+<dt> ‘<samp>--same-permissions</samp>’</dt>
+<dt> ‘<samp>-p</samp>’</dt>
+<dd>
+<p>When <code>tar</code> 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 <code>tar</code> that it should use the
+permissions directly from the archive. See section <a href="#SEC75">Setting
Access Permissions</a>.
+</p>
+<p><a name="g_t_002d_002dread_002dfull_002drecords"></a>
+<a name="IDX121"></a>
+</p></dd>
+<dt> ‘<samp>--read-full-records</samp>’</dt>
+<dt> ‘<samp>-B</samp>’</dt>
+<dd>
+<p>Specifies that <code>tar</code> should reblock its input, for reading
+from pipes on systems with buggy implementations. See section <a
href="#SEC64">Options to Help Read Archives</a>.
+</p>
+<p><a name="g_t_002d_002drecord_002dsize"></a>
+<a name="IDX122"></a>
+</p></dd>
+<dt> ‘<samp>--record-size=<var>size</var></samp>’</dt>
+<dd>
+<p>Instructs <code>tar</code> to use <var>size</var> bytes per record when
accessing the
+archive. See section <a href="#SEC149">The Blocking Factor of an Archive</a>.
+</p>
+<p><a name="g_t_002d_002drecursion"></a>
+<a name="IDX123"></a>
+</p></dd>
+<dt> ‘<samp>--recursion</samp>’</dt>
+<dd>
+<p>With this option, <code>tar</code> recurses into directories.
+See section <a href="#SEC109">Descending into Directories</a>.
+</p>
+<p><a name="g_t_002d_002drecursive_002dunlink"></a>
+<a name="IDX124"></a>
+</p></dd>
+<dt> ‘<samp>--recursive-unlink</samp>’</dt>
+<dd>
+<p>Remove existing
+directory hierarchies before extracting directories of the same name
+from the archive. See section <a href="#SEC73">Recursive Unlink</a>.
+</p>
+<p><a name="g_t_002d_002dremove_002dfiles"></a>
+<a name="IDX125"></a>
+</p></dd>
+<dt> ‘<samp>--remove-files</samp>’</dt>
+<dd>
+<p>Directs <code>tar</code> to remove the source file from the file system
after
+appending it to an archive. See section <a href="#SEC79">Removing Files</a>.
+</p>
+<p><a name="g_t_002d_002drestrict"></a>
+<a name="IDX126"></a>
+</p></dd>
+<dt> ‘<samp>--restrict</samp>’</dt>
+<dd>
+<p>Disable use of some potentially harmful <code>tar</code> options.
+Currently this option disables shell invocaton from multi-volume menu
+(see section <a href="#SEC153">Using Multiple Tapes</a>).
+</p>
+<p><a name="g_t_002d_002drmt_002dcommand"></a>
+<a name="IDX127"></a>
+</p></dd>
+<dt> ‘<samp>--rmt-command=<var>cmd</var></samp>’</dt>
+<dd>
+<p>Notifies <code>tar</code> that it should use <var>cmd</var> instead of
+the default ‘<tt>/usr/libexec/rmt</tt>’ (see section <a
href="#SEC145">The Remote Tape Server</a>).
+</p>
+<p><a name="g_t_002d_002drsh_002dcommand"></a>
+<a name="IDX128"></a>
+</p></dd>
+<dt> ‘<samp>--rsh-command=<var>cmd</var></samp>’</dt>
+<dd>
+<p>Notifies <code>tar</code> that is should use <var>cmd</var> to communicate
with remote
+devices. See section <a href="#SEC144">Device Selection and Switching</a>.
+</p>
+<p><a name="g_t_002d_002dsame_002dorder"></a>
+<a name="IDX129"></a>
+</p></dd>
+<dt> ‘<samp>--same-order</samp>’</dt>
+<dt> ‘<samp>--preserve-order</samp>’</dt>
+<dt> ‘<samp>-s</samp>’</dt>
+<dd>
+<p>This option is an optimization for <code>tar</code> when running on
machines with
+small amounts of memory. It informs <code>tar</code> that the list of file
+arguments has already been sorted to match the order of files in the
+archive. See section <a href="#SEC64">Options to Help Read Archives</a>.
+</p>
+<p><a name="g_t_002d_002dsame_002downer"></a>
+<a name="IDX130"></a>
+</p></dd>
+<dt> ‘<samp>--same-owner</samp>’</dt>
+<dd>
+<p>When extracting an archive, <code>tar</code> will attempt to preserve the
owner
+specified in the <code>tar</code> archive with this option present.
+This is the default behavior for the superuser; this option has an
+effect only for ordinary users. See section <a href="#SEC128">Handling File
Attributes</a>.
+</p>
+<a name="IDX131"></a>
+</dd>
+<dt> ‘<samp>--same-permissions</samp>’</dt>
+<dd>
+<p>(See ‘<samp>--preserve-permissions</samp>’; see section <a
href="#SEC75">Setting Access Permissions</a>.)
+</p>
+<p><a name="g_t_002d_002dshow_002ddefaults"></a>
+<a name="IDX132"></a>
+</p></dd>
+<dt> ‘<samp>--show-defaults</samp>’</dt>
+<dd>
+<p>Displays the default options used by <code>tar</code> and exits
+successfully. This option is intended for use in shell scripts.
+Here is an example of what you can see using this option:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ tar --show-defaults
+--format=gnu -f- -b20 --quoting-style=escape \
+--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
+</pre></td></tr></table>
+
+<p><a name="g_t_002d_002dshow_002domitted_002ddirs"></a>
+<a name="IDX133"></a>
+</p></dd>
+<dt> ‘<samp>--show-omitted-dirs</samp>’</dt>
+<dd>
+<p>Instructs <code>tar</code> to mention directories its skipping over when
+operating on a <code>tar</code> archive. See <a
href="#show_002domitted_002ddirs">show-omitted-dirs</a>.
+</p>
+<p><a name="g_t_002d_002dshow_002dtransformed_002dnames"></a>
+<a name="IDX134"></a>
+<a name="g_t_002d_002dshow_002dstored_002dnames"></a>
+<a name="IDX135"></a>
+</p></dd>
+<dt> ‘<samp>--show-transformed-names</samp>’</dt>
+<dt> ‘<samp>--show-stored-names</samp>’</dt>
+<dd>
+<p>Display file or member names after applying any transformations
+(see section <a href="#SEC107">Modifying File and Member Names</a>). 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. See <a href="#listing-member-and-file-names">listing member and file
names</a>.
+</p>
+<p><a name="g_t_002d_002dsparse"></a>
+<a name="IDX136"></a>
+</p></dd>
+<dt> ‘<samp>--sparse</samp>’</dt>
+<dt> ‘<samp>-S</samp>’</dt>
+<dd>
+<p>Invokes a <acronym>GNU</acronym> extension when adding files to an archive
that handles
+sparse files efficiently. See section <a href="#SEC127">Archiving Sparse
Files</a>.
+</p>
+<p><a name="g_t_002d_002dsparse_002dversion"></a>
+<a name="IDX137"></a>
+</p></dd>
+<dt> ‘<samp>--sparse-version=<var>version</var></samp>’</dt>
+<dd>
+<p>Specified the <em>format version</em> to use when archiving sparse
+files. Implies ‘<samp>--sparse</samp>’. See section <a
href="#SEC127">Archiving Sparse Files</a>. For the description
+of the supported sparse formats, See section <a href="#SEC165">Storing Sparse
Files</a>.
+</p>
+<p><a name="g_t_002d_002dstarting_002dfile"></a>
+<a name="IDX138"></a>
+</p></dd>
+<dt> ‘<samp>--starting-file=<var>name</var></samp>’</dt>
+<dt> ‘<samp>-K <var>name</var></samp>’</dt>
+<dd>
+<p>This option affects extraction only; <code>tar</code> will skip extracting
+files in the archive until it finds one that matches <var>name</var>.
+See section <a href="#SEC80">Coping with Scarce Resources</a>.
+</p>
+<p><a name="g_t_002d_002dstrip_002dcomponents"></a>
+<a name="IDX139"></a>
+</p></dd>
+<dt> ‘<samp>--strip-components=<var>number</var></samp>’</dt>
+<dd><p>Strip given <var>number</var> of leading components from file names
before
+extraction.<a name="DOCF7" href="#FOOT7">(7)</a> For example, if archive
‘<tt>archive.tar</tt>’ contained
+‘<tt>/some/file/name</tt>’, then running
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar --extract --file
archive.tar --strip-components=2
+</pre></td></tr></table>
+
+<p>would extract this file to file ‘<tt>name</tt>’.
+</p>
+<p><a name="g_t_002d_002dsuffix"></a>
+<a name="IDX140"></a>
+</p></dd>
+<dt> ‘<samp>--suffix=<var>suffix</var></samp>’</dt>
+<dd>
+<p>Alters the suffix <code>tar</code> uses when backing up files from the
default
+‘<samp>~</samp>’. See section <a href="#SEC83">Backup options</a>.
+</p>
+<p><a name="g_t_002d_002dtape_002dlength"></a>
+<a name="IDX141"></a>
+</p></dd>
+<dt> ‘<samp>--tape-length=<var>num</var></samp>’</dt>
+<dt> ‘<samp>-L <var>num</var></samp>’</dt>
+<dd>
+<p>Specifies the length of tapes that <code>tar</code> is writing as being
+<var>num</var> x 1024 bytes long. See section <a href="#SEC153">Using
Multiple Tapes</a>.
+</p>
+<p><a name="g_t_002d_002dtest_002dlabel"></a>
+<a name="IDX142"></a>
+</p></dd>
+<dt> ‘<samp>--test-label</samp>’</dt>
+<dd>
+<p>Reads the volume label. If an argument is specified, test whether it
+matches the volume label. See <a
href="#g_t_002d_002dtest_002dlabel-option">–test-label option</a>.
+</p>
+<p><a name="g_t_002d_002dto_002dcommand"></a>
+<a name="IDX143"></a>
+</p></dd>
+<dt> ‘<samp>--to-command=<var>command</var></samp>’</dt>
+<dd>
+<p>During extraction <code>tar</code> will pipe extracted files to the
+standard input of <var>command</var>. See section <a href="#SEC78">Writing to
an External Program</a>.
+</p>
+<p><a name="g_t_002d_002dto_002dstdout"></a>
+<a name="IDX144"></a>
+</p></dd>
+<dt> ‘<samp>--to-stdout</samp>’</dt>
+<dt> ‘<samp>-O</samp>’</dt>
+<dd>
+<p>During extraction, <code>tar</code> will extract files to stdout rather
+than to the file system. See section <a href="#SEC77">Writing to Standard
Output</a>.
+</p>
+<p><a name="g_t_002d_002dtotals"></a>
+<a name="IDX145"></a>
+</p></dd>
+<dt> ‘<samp>--totals[=<var>signo</var>]</samp>’</dt>
+<dd>
+<p>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</var> is delivered to <code>tar</code>.
+See <a href="#totals">totals</a>.
+</p>
+<p><a name="g_t_002d_002dtouch"></a>
+<a name="IDX146"></a>
+</p></dd>
+<dt> ‘<samp>--touch</samp>’</dt>
+<dt> ‘<samp>-m</samp>’</dt>
+<dd>
+<p>Sets the data modification time of extracted files to the extraction time,
+rather than the data modification time stored in the archive.
+See section <a href="#SEC74">Setting Data Modification Times</a>.
+</p>
+<a name="IDX147"></a>
+</dd>
+<dt> ‘<samp>--uncompress</samp>’</dt>
+<dd>
+<p>(See ‘<samp>--compress</samp>’. see section <a
href="#SEC126">Creating and Reading Compressed Archives</a>)
+</p>
+<a name="IDX148"></a>
+</dd>
+<dt> ‘<samp>--ungzip</samp>’</dt>
+<dd>
+<p>(See ‘<samp>--gzip</samp>’. see section <a
href="#SEC126">Creating and Reading Compressed Archives</a>)
+</p>
+<p><a name="g_t_002d_002dunlink_002dfirst"></a>
+<a name="IDX149"></a>
+</p></dd>
+<dt> ‘<samp>--unlink-first</samp>’</dt>
+<dt> ‘<samp>-U</samp>’</dt>
+<dd>
+<p>Directs <code>tar</code> to remove the corresponding file from the file
+system before extracting it from the archive. See section <a
href="#SEC72">Unlink First</a>.
+</p>
+<p><a name="g_t_002d_002dunquote"></a>
+<a name="IDX150"></a>
+</p></dd>
+<dt> ‘<samp>--unquote</samp>’</dt>
+<dd><p>Enable unquoting input file or member names (default). See <a
href="#input-name-quoting">input name quoting</a>.
+</p>
+<p><a name="g_t_002d_002duse_002dcompress_002dprogram"></a>
+<a name="IDX151"></a>
+</p></dd>
+<dt> ‘<samp>--use-compress-program=<var>prog</var></samp>’</dt>
+<dd>
+<p>Instructs <code>tar</code> to access the archive through <var>prog</var>,
which is
+presumed to be a compression program of some sort. See section <a
href="#SEC126">Creating and Reading Compressed Archives</a>.
+</p>
+<p><a name="g_t_002d_002dutc"></a>
+<a name="IDX152"></a>
+</p></dd>
+<dt> ‘<samp>--utc</samp>’</dt>
+<dd>
+<p>Display file modification dates in <acronym>UTC</acronym>. This option
implies
+‘<samp>--verbose</samp>’.
+</p>
+<p><a name="g_t_002d_002dverbose"></a>
+<a name="IDX153"></a>
+</p></dd>
+<dt> ‘<samp>--verbose</samp>’</dt>
+<dt> ‘<samp>-v</samp>’</dt>
+<dd>
+<p>Specifies that <code>tar</code> 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.
+See section <a href="#SEC46">Checking <code>tar</code> progress</a>.
+</p>
+<p><a name="g_t_002d_002dverify"></a>
+<a name="IDX154"></a>
+</p></dd>
+<dt> ‘<samp>--verify</samp>’</dt>
+<dt> ‘<samp>-W</samp>’</dt>
+<dd>
+<p>Verifies that the archive was correctly written when creating an
+archive. See section <a href="#SEC158">Verifying Data as It is Stored</a>.
+</p>
+<p><a name="g_t_002d_002dversion"></a>
+<a name="IDX155"></a>
+</p></dd>
+<dt> ‘<samp>--version</samp>’</dt>
+<dd>
+<p>Print information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+See section <a href="#SEC44"><acronym>GNU</acronym> <code>tar</code>
documentation</a>.
+</p>
+<p><a name="g_t_002d_002dvolno_002dfile"></a>
+<a name="IDX156"></a>
+</p></dd>
+<dt> ‘<samp>--volno-file=<var>file</var></samp>’</dt>
+<dd>
+<p>Used in conjunction with ‘<samp>--multi-volume</samp>’.
<code>tar</code> will
+keep track of which volume of a multi-volume archive its working in
+<var>file</var>. See <a href="#volno_002dfile">volno-file</a>.
+</p>
+<p><a name="g_t_002d_002dwildcards"></a>
+<a name="IDX157"></a>
+</p></dd>
+<dt> ‘<samp>--wildcards</samp>’</dt>
+<dd><p>Use wildcards when matching member names with patterns.
+See section <a href="#SEC105">Controlling Pattern-Matching</a>.
+</p>
+<p><a name="g_t_002d_002dwildcards_002dmatch_002dslash"></a>
+<a name="IDX158"></a>
+</p></dd>
+<dt> ‘<samp>--wildcards-match-slash</samp>’</dt>
+<dd><p>Wildcards match ‘<samp>/</samp>’.
+See section <a href="#SEC105">Controlling Pattern-Matching</a>.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Short-Option-Summary"></a>
+<a name="SEC43"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC42" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC44" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC40" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 3.4.3 Short Options Cross Reference </h3>
+
+<p>Here is an alphabetized list of all of the short option forms, matching
+them with the equivalent long option.
+</p>
+<table>
+<thead><tr><th><p> Short Option </p></th><th><p> Reference
+</p>
+</th></tr></thead>
+<tr><td><p> -A </p></td><td><p> <a
href="#g_t_002d_002dconcatenate">–concatenate</a>.
+</p>
+</td></tr>
+<tr><td><p> -B </p></td><td><p> <a
href="#g_t_002d_002dread_002dfull_002drecords">–read-full-records</a>.
+</p>
+</td></tr>
+<tr><td><p> -C </p></td><td><p> <a
href="#g_t_002d_002ddirectory">–directory</a>.
+</p>
+</td></tr>
+<tr><td><p> -F </p></td><td><p> <a
href="#g_t_002d_002dinfo_002dscript">–info-script</a>.
+</p>
+</td></tr>
+<tr><td><p> -G </p></td><td><p> <a
href="#g_t_002d_002dincremental">–incremental</a>.
+</p>
+</td></tr>
+<tr><td><p> -K </p></td><td><p> <a
href="#g_t_002d_002dstarting_002dfile">–starting-file</a>.
+</p>
+</td></tr>
+<tr><td><p> -L </p></td><td><p> <a
href="#g_t_002d_002dtape_002dlength">–tape-length</a>.
+</p>
+</td></tr>
+<tr><td><p> -M </p></td><td><p> <a
href="#g_t_002d_002dmulti_002dvolume">–multi-volume</a>.
+</p>
+</td></tr>
+<tr><td><p> -N </p></td><td><p> <a href="#g_t_002d_002dnewer">–newer</a>.
+</p>
+</td></tr>
+<tr><td><p> -O </p></td><td><p> <a
href="#g_t_002d_002dto_002dstdout">–to-stdout</a>.
+</p>
+</td></tr>
+<tr><td><p> -P </p></td><td><p> <a
href="#g_t_002d_002dabsolute_002dnames">–absolute-names</a>.
+</p>
+</td></tr>
+<tr><td><p> -R </p></td><td><p> <a
href="#g_t_002d_002dblock_002dnumber">–block-number</a>.
+</p>
+</td></tr>
+<tr><td><p> -S </p></td><td><p> <a
href="#g_t_002d_002dsparse">–sparse</a>.
+</p>
+</td></tr>
+<tr><td><p> -T </p></td><td><p> <a
href="#g_t_002d_002dfiles_002dfrom">–files-from</a>.
+</p>
+</td></tr>
+<tr><td><p> -U </p></td><td><p> <a
href="#g_t_002d_002dunlink_002dfirst">–unlink-first</a>.
+</p>
+</td></tr>
+<tr><td><p> -V </p></td><td><p> <a href="#g_t_002d_002dlabel">–label</a>.
+</p>
+</td></tr>
+<tr><td><p> -W </p></td><td><p> <a
href="#g_t_002d_002dverify">–verify</a>.
+</p>
+</td></tr>
+<tr><td><p> -X </p></td><td><p> <a
href="#g_t_002d_002dexclude_002dfrom">–exclude-from</a>.
+</p>
+</td></tr>
+<tr><td><p> -Z </p></td><td><p> <a
href="#g_t_002d_002dcompress">–compress</a>.
+</p>
+</td></tr>
+<tr><td><p> -b </p></td><td><p> <a
href="#g_t_002d_002dblocking_002dfactor">–blocking-factor</a>.
+</p>
+</td></tr>
+<tr><td><p> -c </p></td><td><p> <a
href="#g_t_002d_002dcreate">–create</a>.
+</p>
+</td></tr>
+<tr><td><p> -d </p></td><td><p> <a
href="#g_t_002d_002dcompare">–compare</a>.
+</p>
+</td></tr>
+<tr><td><p> -f </p></td><td><p> <a href="#g_t_002d_002dfile">–file</a>.
+</p>
+</td></tr>
+<tr><td><p> -g </p></td><td><p> <a
href="#g_t_002d_002dlisted_002dincremental">–listed-incremental</a>.
+</p>
+</td></tr>
+<tr><td><p> -h </p></td><td><p> <a
href="#g_t_002d_002ddereference">–dereference</a>.
+</p>
+</td></tr>
+<tr><td><p> -i </p></td><td><p> <a
href="#g_t_002d_002dignore_002dzeros">–ignore-zeros</a>.
+</p>
+</td></tr>
+<tr><td><p> -j </p></td><td><p> <a href="#g_t_002d_002dbzip2">–bzip2</a>.
+</p>
+</td></tr>
+<tr><td><p> -k </p></td><td><p> <a
href="#g_t_002d_002dkeep_002dold_002dfiles">–keep-old-files</a>.
+</p>
+</td></tr>
+<tr><td><p> -l </p></td><td><p> <a
href="#g_t_002d_002dcheck_002dlinks">–check-links</a>.
+</p>
+</td></tr>
+<tr><td><p> -m </p></td><td><p> <a href="#g_t_002d_002dtouch">–touch</a>.
+</p>
+</td></tr>
+<tr><td><p> -o </p></td><td><p> When creating, <a
href="#g_t_002d_002dno_002dsame_002downer">–no-same-owner</a>, when
extracting —
+<a href="#g_t_002d_002dportability">–portability</a>.
+</p>
+<p>The later usage is deprecated. It is retained for compatibility with
+the earlier versions of <acronym>GNU</acronym> <code>tar</code>. In the
future releases
+‘<samp>-o</samp>’ will be equivalent to
‘<samp>--no-same-owner</samp>’ only.
+</p>
+</td></tr>
+<tr><td><p> -p </p></td><td><p> <a
href="#g_t_002d_002dpreserve_002dpermissions">–preserve-permissions</a>.
+</p>
+</td></tr>
+<tr><td><p> -r </p></td><td><p> <a
href="#g_t_002d_002dappend">–append</a>.
+</p>
+</td></tr>
+<tr><td><p> -s </p></td><td><p> <a
href="#g_t_002d_002dsame_002dorder">–same-order</a>.
+</p>
+</td></tr>
+<tr><td><p> -t </p></td><td><p> <a href="#g_t_002d_002dlist">–list</a>.
+</p>
+</td></tr>
+<tr><td><p> -u </p></td><td><p> <a
href="#g_t_002d_002dupdate">–update</a>.
+</p>
+</td></tr>
+<tr><td><p> -v </p></td><td><p> <a
href="#g_t_002d_002dverbose">–verbose</a>.
+</p>
+</td></tr>
+<tr><td><p> -w </p></td><td><p> <a
href="#g_t_002d_002dinteractive">–interactive</a>.
+</p>
+</td></tr>
+<tr><td><p> -x </p></td><td><p> <a
href="#g_t_002d_002dextract">–extract</a>.
+</p>
+</td></tr>
+<tr><td><p> -z </p></td><td><p> <a href="#g_t_002d_002dgzip">–gzip</a>.
+</p>
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="help"></a>
+<a name="SEC44"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC43" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC45" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 3.5 <acronym>GNU</acronym> <code>tar</code> documentation
</h2>
+
+<p>Being careful, the first thing is really checking that you are using
+<acronym>GNU</acronym> <code>tar</code>, indeed. The
‘<samp>--version</samp>’ option
+causes <code>tar</code> to print information about its name, version,
+origin and legal status, all on standard output, and then exit
+successfully. For example, ‘<samp>tar --version</samp>’ might
print:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">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.
+</pre></td></tr></table>
+
+<p>The first occurrence of ‘<samp>tar</samp>’ in the result above
is the program
+name in the package (for example, <code>rmt</code> is another program),
+while the second occurrence of ‘<samp>tar</samp>’ is the name of
the package
+itself, containing possibly many programs. The package is currently
+named ‘<samp>tar</samp>’, after the name of the main program it
+contains<a name="DOCF8" href="#FOOT8">(8)</a>.
+</p>
+<a name="IDX159"></a>
+<a name="IDX160"></a>
+<a name="IDX161"></a>
+<p>Another thing you might want to do is checking the spelling or meaning
+of some particular <code>tar</code> option, without resorting to this
+manual, for once you have carefully read it. <acronym>GNU</acronym>
<code>tar</code>
+has a short help feature, triggerable through the
+‘<samp>--help</samp>’ option. By using this option,
<code>tar</code> 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --help |
less</kbd>
+</pre></td></tr></table>
+
+<p>presuming, here, that you like using <code>less</code> for a pager. Other
+popular pagers are <code>more</code> and <code>pg</code>. If you know about
some
+<var>keyword</var> which interests you and do not want to read all the
+‘<samp>--help</samp>’ output, another common idiom is doing:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar --help | grep
<var>keyword</var>
+</pre></td></tr></table>
+
+<p>for getting only the pertinent lines. Notice, however, that some
+<code>tar</code> options have long description lines and the above
+command will list only the first of them.
+</p>
+<p>The exact look of the option summary displayed by <kbd>tar --help</kbd> is
+configurable. See section <a href="#SEC161">Configuring Help Summary</a>, for
a detailed description.
+</p>
+<a name="IDX162"></a>
+<p>If you only wish to check the spelling of an option, running <kbd>tar
+--usage</kbd> may be a better choice. This will display a terse list of
+<code>tar</code> option without accompanying explanations.
+</p>
+<p>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 <code>tar</code> manual in some
+form. This manual is available in a variety of forms from
+<a
href="http://www.gnu.org/software/tar/manual";>http://www.gnu.org/software/tar/manual</a>.
It may be printed out of the <acronym>GNU</acronym> <code>tar</code>
+distribution, provided you have TeX already installed somewhere,
+and a laser printer around. Just configure the distribution, execute
+the command ‘<samp>make dvi</samp>’, then print
‘<tt>doc/tar.dvi</tt>’ the
+usual way (contact your local guru to know how). If <acronym>GNU</acronym>
<code>tar</code>
+has been conveniently installed at your place, this
+manual is also available in interactive, hypertextual form as an Info
+file. Just call ‘<samp>info tar</samp>’ or, if you do not have the
+<code>info</code> program handy, use the Info reader provided within
+<acronym>GNU</acronym> Emacs, calling ‘<samp>tar</samp>’ from the
main Info menu.
+</p>
+<p>There is currently no <code>man</code> page for <acronym>GNU</acronym>
<code>tar</code>.
+If you observe such a <code>man</code> page on the system you are running,
+either it does not belong to <acronym>GNU</acronym> <code>tar</code>, or it
has not
+been produced by <acronym>GNU</acronym>. Some package maintainers convert
+<kbd>tar --help</kbd> output to a man page, using <code>help2man</code>. In
+any case, please bear in mind that the authoritative source of
+information about <acronym>GNU</acronym> <code>tar</code> is this Texinfo
documentation.
+</p>
+<hr size="6">
+<a name="defaults"></a>
+<a name="SEC45"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC44" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC46" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 3.6 Obtaining <acronym>GNU</acronym> <code>tar</code>
default values </h2>
+
+<p><acronym>GNU</acronym> <code>tar</code> has some predefined defaults that
are used when you do not
+explicitely specify another values. To obtain a list of such
+defaults, use ‘<samp>--show-defaults</samp>’ option. This will
output the
+values in the form of <code>tar</code> command line options:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar
--show-defaults</kbd>
+--format=gnu -f- -b20 --quoting-style=escape
+--rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
+</pre></td></tr></table>
+
+<p>Notice, that this option outputs only one line. The example output above
+has been split to fit page boundaries.
+</p>
+<p>The above output shows that this version of <acronym>GNU</acronym>
<code>tar</code> defaults to
+using ‘<samp>gnu</samp>’ archive format (see section <a
href="#SEC124">Controlling the Archive Format</a>), it uses standard
+output as the archive, if no ‘<samp>--file</samp>’ option has been
given
+(see section <a href="#SEC14">The ‘<samp>--file</samp>’
Option</a>), the default blocking factor is 20
+(see section <a href="#SEC149">The Blocking Factor of an Archive</a>). It
also shows the default locations where
+<code>tar</code> will look for <code>rmt</code> and <code>rsh</code> binaries.
+</p>
+<hr size="6">
+<a name="verbose"></a>
+<a name="SEC46"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC45" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC47" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 3.7 Checking <code>tar</code> progress </h2>
+
+<p>Typically, <code>tar</code> performs most operations without reporting any
+information to the user except error messages. When using <code>tar</code>
+with many options, particularly ones with complicated or
+difficult-to-predict behavior, it is possible to make serious mistakes.
+<code>tar</code> provides several options that make observing <code>tar</code>
+easier. These options cause <code>tar</code> 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.
+</p>
+<a name="IDX163"></a>
+<a name="IDX164"></a>
+<p>Normally, the ‘<samp>--list</samp>’
(‘<samp>-t</samp>’) 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
‘<samp>--verbose</samp>’
+(‘<samp>-v</samp>’) option causes <code>tar</code> to print the
name of each
+file or archive member as it is processed. This and the other options
+which make <code>tar</code> print status information can be useful in
+monitoring <code>tar</code>.
+</p>
+<p>With ‘<samp>--create</samp>’ or
‘<samp>--extract</samp>’, ‘<samp>--verbose</samp>’ used
+once just prints the names of the files or members as they are processed.
+Using it twice causes <code>tar</code> to print a longer listing
+(See <a href="#verbose-member-listing">verbose member listing</a>, for the
description) for each member.
+Since ‘<samp>--list</samp>’ already prints the names of the
members,
+‘<samp>--verbose</samp>’ used once with
‘<samp>--list</samp>’ causes <code>tar</code>
+to print an ‘<samp>ls -l</samp>’ type listing of the files in the
archive.
+The following examples both extract members with long list output:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --extract
--file=archive.tar --verbose --verbose</kbd>
+$ <kbd>tar xvvf archive.tar</kbd>
+</pre></td></tr></table>
+
+<p>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>’ (‘<samp>tar cfv -</samp>’, or
even ‘<samp>tar cv</samp>’—if the
+installer let standard output be the default archive). In that case
+<code>tar</code> writes verbose output to the standard error stream.
+</p>
+<p>If ‘<samp>--index-file=<var>file</var></samp>’ is specified,
<code>tar</code> sends
+verbose output to <var>file</var> rather than to standard output or standard
+error.
+</p>
+<p><a name="totals"></a>
+<a name="IDX165"></a>
+<a name="IDX166"></a>
+The ‘<samp>--totals</samp>’ option causes <code>tar</code> 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.:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
archive.tar --totals /home</kbd>
+Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
+</pre></td></tr></table>
+
+<p>When reading an archive, this option displays the number of bytes
+read:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -x -f
archive.tar --totals</kbd>
+Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
+</pre></td></tr></table>
+
+<p>Finally, when deleting from an archive, the
‘<samp>--totals</samp>’ option
+displays both numbers plus number of bytes removed from the archive:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --delete -f
foo.tar --totals --wildcards '*~'</kbd>
+Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+Total bytes deleted: 1474048
+</pre></td></tr></table>
+
+<p>You can also obtain this information on request. When
+‘<samp>--totals</samp>’ 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:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--totals=<var>signo</var></samp>’</dt>
+<dd><p>Print statistics upon delivery of signal <var>signo</var>. Valid
arguments
+are: <code>SIGHUP</code>, <code>SIGQUIT</code>, <code>SIGINT</code>,
<code>SIGUSR1</code> and
+<code>SIGUSR2</code>. Shortened names without ‘<samp>SIG</samp>’
prefix are also
+accepted.
+</p></dd>
+</dl>
+
+<p>Both forms of ‘<samp>--totals</samp>’ option can be used
simultaneously.
+Thus, <kbd>tar -x --totals --totals=USR1</kbd> instructs <code>tar</code> to
+extract all members from its default archive and print statistics
+after finishing the extraction, as well as when receiving signal
+<code>SIGUSR1</code>.
+</p>
+<p><a name="Progress-information"></a>
+<a name="IDX167"></a>
+<a name="IDX168"></a>
+The ‘<samp>--checkpoint</samp>’ option prints an occasional message
+as <code>tar</code> reads or writes the archive. It is designed for
+those who don't need the more detailed (and voluminous) output of
+‘<samp>--block-number</samp>’ (‘<samp>-R</samp>’), but
do want visual confirmation
+that <code>tar</code> 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c
--checkpoint=1000</kbd> /var
+tar: Write checkpoint 1000
+tar: Write checkpoint 2000
+tar: Write checkpoint 3000
+</pre></td></tr></table>
+
+<p>This example shows the default checkpoint message used by
+<code>tar</code>. If you place a dot immediately after the equal
+sign, it will print a ‘<samp>.</samp>’ at each checkpoint. For
example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c
--checkpoint=.1000</kbd> /var
+...
+</pre></td></tr></table>
+
+<a name="IDX169"></a>
+<p><a name="show_002domitted_002ddirs"></a>
+The ‘<samp>--show-omitted-dirs</samp>’ option, when reading an
archive—with
+‘<samp>--list</samp>’ or ‘<samp>--extract</samp>’, 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
+‘<samp>--exclude=<var>pattern</var></samp>’ option, or some other
reason.
+</p>
+<a name="IDX170"></a>
+<a name="IDX171"></a>
+<p><a name="block_002dnumber"></a>
+If ‘<samp>--block-number</samp>’ (‘<samp>-R</samp>’)
is used, <code>tar</code> 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
+‘<samp>--block-number</samp>’ (‘<samp>-R</samp>’) is
used. Note that <acronym>GNU</acronym> <code>tar</code>
+drains the archive before exiting when reading the
+archive from a pipe.
+</p>
+<a name="IDX172"></a>
+<p>This option is especially useful when reading damaged archives, since
+it helps pinpoint the damaged sections. It can also be used with
+‘<samp>--list</samp>’ (‘<samp>-t</samp>’) 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). See section <a href="#SEC83">Backup options</a>.
+</p>
+<hr size="6">
+<a name="interactive"></a>
+<a name="SEC47"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC46" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 3.8 Asking for Confirmation During Operations </h2>
+
+<p>Typically, <code>tar</code> 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 (see section <a href="#SEC97">Choosing Files and
Names for <code>tar</code></a>), or by performing
+an operation interactively, using the ‘<samp>--interactive</samp>’
(‘<samp>-w</samp>’) option.
+<code>tar</code> also accepts ‘<samp>--confirmation</samp>’ for
this option.
+</p>
+<a name="IDX173"></a>
+<p>When the ‘<samp>--interactive</samp>’
(‘<samp>-w</samp>’) option is specified, before
+reading, writing, or deleting files, <code>tar</code> 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</samp>’. If your input line begins with
anything other
+than ‘<samp>y</samp>’, <code>tar</code> skips that file.
+</p>
+<p>If <code>tar</code> is reading the archive from the standard input,
+<code>tar</code> opens the file ‘<tt>/dev/tty</tt>’ to support the
interactive
+communications.
+</p>
+<p>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
+<code>stderr</code>. 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.
+</p>
+<hr size="6">
+<a name="operations"></a>
+<a name="SEC48"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC47" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC49" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 4. <acronym>GNU</acronym> <code>tar</code> Operations
</h1>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC49">4.1 Basic
<acronym>GNU</acronym> <code>tar</code>
Operations</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC50">4.2 Advanced
<acronym>GNU</acronym> <code>tar</code>
Operations</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC60">4.3 Options Used by
‘<samp>--create</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC63">4.4 Options Used by
‘<samp>--extract</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC83">4.5 Backup
options</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC84">4.6 Notable
<code>tar</code> Usages</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC85">4.7 Looking Ahead: The Rest
of this Manual</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Basic-tar"></a>
+<a name="SEC49"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC48" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC50" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 4.1 Basic <acronym>GNU</acronym> <code>tar</code>
Operations </h2>
+
+<p>The basic <code>tar</code> operations, ‘<samp>--create</samp>’
(‘<samp>-c</samp>’),
+‘<samp>--list</samp>’ (‘<samp>-t</samp>’) and
‘<samp>--extract</samp>’ (‘<samp>--get</samp>’,
+‘<samp>-x</samp>’), are currently presented and described in the
tutorial
+chapter of this manual. This section provides some complementary notes
+for these operations.
+</p>
+<dl compact="compact">
+<dd><a name="IDX174"></a>
+</dd>
+<dt> ‘<samp>--create</samp>’</dt>
+<dt> ‘<samp>-c</samp>’</dt>
+<dd>
+<p>Creating an empty archive would have some kind of elegance. One can
+initialize an empty archive and later use ‘<samp>--append</samp>’
+(‘<samp>-r</samp>’) 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 <code>tar</code> to destroy a magnetic tape with
+an empty archive<a name="DOCF9" href="#FOOT9">(9)</a>. The two most common
errors are:
+</p>
+<ol>
+<li>
+Mistakingly using <code>create</code> instead of <code>extract</code>, when the
+intent was to extract the full contents of an archive. This error
+is likely: keys <kbd>c</kbd> and <kbd>x</kbd> are right next to each other on
+the QWERTY keyboard. Instead of being unpacked, the archive then
+gets wholly destroyed. When users speak about <em>exploding</em> an
+archive, they usually mean something else :-).
+
+</li><li>
+Forgetting the argument to <code>file</code>, 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</kbd> 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.
+</li></ol>
+
+<p>So, recognizing the likelihood and the catastrophical nature of these
+errors, <acronym>GNU</acronym> <code>tar</code> now takes some distance from
elegance, and
+cowardly refuses to create an archive when ‘<samp>--create</samp>’
option is
+given, there are no arguments besides options, and
+‘<samp>--files-from</samp>’ (‘<samp>-T</samp>’) option
is <em>not</em> used. To get
+around the cautiousness of <acronym>GNU</acronym> <code>tar</code> and
nevertheless create an
+archive with nothing in it, one may still use, as the value for the
+‘<samp>--files-from</samp>’ option, a file with no names in it, as
shown in
+the following commands:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar --create
--file=empty-archive.tar --files-from=/dev/null</kbd>
+<kbd>tar cfT empty-archive.tar /dev/null</kbd>
+</pre></td></tr></table>
+
+<a name="IDX175"></a>
+</dd>
+<dt> ‘<samp>--extract</samp>’</dt>
+<dt> ‘<samp>--get</samp>’</dt>
+<dt> ‘<samp>-x</samp>’</dt>
+<dd>
+<p>A socket is stored, within a <acronym>GNU</acronym> <code>tar</code>
archive, as a pipe.
+</p>
+</dd>
+<dt> ‘<samp>‘<samp>--list</samp>’
(‘<samp>-t</samp>’)</samp>’</dt>
+<dd>
+<p><acronym>GNU</acronym> <code>tar</code> now shows dates as
‘<samp>1996-08-30</samp>’,
+while it used to show them as ‘<samp>Aug 30 1996</samp>’.
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.
+</p>
+<p>Look up <a
href="http://www.cl.cam.ac.uk/~mgk25/iso-time.html";>http://www.cl.cam.ac.uk/~mgk25/iso-time.html</a>
if you
+are curious, it contains a detailed explanation of the ISO 8601 standard.
+</p>
+</dd>
+</dl>
+
+<hr size="6">
+<a name="Advanced-tar"></a>
+<a name="SEC50"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC49" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC51" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 4.2 Advanced <acronym>GNU</acronym> <code>tar</code>
Operations </h2>
+
+<p>Now that you have learned the basics of using <acronym>GNU</acronym>
<code>tar</code>, you may want
+to learn about further ways in which <code>tar</code> can help you.
+</p>
+<p>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 <code>tar</code>
+commands. Additionally, this chapter includes options which allow you to
+define the output from <code>tar</code> more carefully, and provide help and
+error correction in special circumstances.
+</p>
+
+
+
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC51">4.2.1 The Five Advanced
<code>tar</code> Operations</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC52">4.2.2 How to Add Files to
Existing Archives:
‘<samp>--append</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC55">4.2.3 Updating an
Archive</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC57">4.2.4 Combining Archives
with ‘<samp>--concatenate</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC58">4.2.5 Removing Archive
Members Using
‘<samp>--delete</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC59">4.2.6 Comparing Archive
Members with the File System</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Operations"></a>
+<a name="SEC51"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC50" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC52" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC50" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.2.1 The Five Advanced <code>tar</code> Operations
</h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>In the last chapter, you learned about the first three operations to
+<code>tar</code>. This chapter presents the remaining five operations to
+<code>tar</code>: ‘<samp>--append</samp>’,
‘<samp>--update</samp>’, ‘<samp>--concatenate</samp>’,
+‘<samp>--delete</samp>’, and ‘<samp>--compare</samp>’.
+</p>
+<p>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
+‘<tt>practice</tt>’, the files are
‘<samp>jazz</samp>’, ‘<samp>blues</samp>’,
‘<samp>folk</samp>’,
+‘<samp>rock</samp>’, and the two archive files you created are
+‘<samp>collection.tar</samp>’ and
‘<samp>music.tar</samp>’.
+</p>
+<p>We will also use the archive files ‘<samp>afiles.tar</samp>’ and
+‘<samp>bfiles.tar</samp>’. The archive
‘<samp>afiles.tar</samp>’ contains the members
‘<samp>apple</samp>’,
+‘<samp>angst</samp>’, and ‘<samp>aspic</samp>’;
‘<samp>bfiles.tar</samp>’ contains the members
+‘<samp>./birds</samp>’, ‘<samp>baboon</samp>’, and
‘<samp>./box</samp>’.
+</p>
+<p>Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the ‘<tt>practice</tt>’
directory that
+you created in the previous chapter; see <a href="#SEC18">Preparing a Practice
Directory for Examples</a>.
+(Below in this section, we will remind you of the state of the examples
+where the last chapter left them.)
+</p>
+<p>The five operations that we will cover in this chapter are:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--append</samp>’</dt>
+<dt> ‘<samp>-r</samp>’</dt>
+<dd><p>Add new entries to an archive that already exists.
+</p></dd>
+<dt> ‘<samp>--update</samp>’</dt>
+<dt> ‘<samp>-r</samp>’</dt>
+<dd><p>Add more recent copies of archive members to the end of an archive, if
+they exist.
+</p></dd>
+<dt> ‘<samp>--concatenate</samp>’</dt>
+<dt> ‘<samp>--catenate</samp>’</dt>
+<dt> ‘<samp>-A</samp>’</dt>
+<dd><p>Add one or more pre-existing archives to the end of another archive.
+</p></dd>
+<dt> ‘<samp>--delete</samp>’</dt>
+<dd><p>Delete items from an archive (does not work on tapes).
+</p></dd>
+<dt> ‘<samp>--compare</samp>’</dt>
+<dt> ‘<samp>--diff</samp>’</dt>
+<dt> ‘<samp>-d</samp>’</dt>
+<dd><p>Compare archive members to their counterparts in the file system.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="append"></a>
+<a name="SEC52"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC51" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC53" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC50" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.2.2 How to Add Files to Existing Archives:
‘<samp>--append</samp>’ </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX176"></a>
+<p>If you want to add files to an existing archive, you don't need to
+create a new archive; you can use ‘<samp>--append</samp>’
(‘<samp>-r</samp>’).
+The archive must already exist in order to use
‘<samp>--append</samp>’. (A
+related operation is the ‘<samp>--update</samp>’ operation; you
can use this
+to add newer versions of archive members to an existing archive. To learn how
to
+do this with ‘<samp>--update</samp>’, see section <a
href="#SEC55">Updating an Archive</a>.)
+</p>
+<p>If you use ‘<samp>--append</samp>’ 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. <code>tar</code> <em>allows</em> 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 ‘<samp>--list</samp>’
(‘<samp>-t</samp>’), you will see all
+of those members listed, with their data modification times, owners, etc.
+</p>
+<p>Other operations don't deal with these members as perfectly as you might
+prefer; if you were to use ‘<samp>--extract</samp>’ 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
+‘<samp>--extract</samp>’ 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 <em>replace</em> a file of
+the same name which existed in the directory already, and <code>tar</code>
+will not prompt you about this<a name="DOCF10" href="#FOOT10">(10)</a>. Thus,
only the most recently archived
+member will end up being extracted, as it will replace the one
+extracted before it, and so on.
+</p>
+<p>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 ‘<samp>--occurrence</samp>’ option. If you run
<code>tar</code> 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
+‘<tt>archive.tar</tt>’ contained three copies of file
‘<tt>myfile</tt>’, then
+the command
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar --extract --file
archive.tar --occurrence=2 myfile
+</pre></td></tr></table>
+
+<p>would extract only the second copy. See section <a
href="#SEC42">—occurrence</a>, for the description of
‘<samp>--occurrence</samp>’
+option.
+</p>
+
+
+
+
+<a name="IDX177"></a>
+<a name="IDX178"></a>
+<p>If you want to replace an archive member, use
‘<samp>--delete</samp>’ to
+delete the member you want to remove from the archive, , and then use
+‘<samp>--append</samp>’ 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 <a
href="#SEC58">Removing Archive Members Using
‘<samp>--delete</samp>’</a>
+and <a href="#SEC143">Tapes and Other Archive Media</a>, for more information.)
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC53">4.2.2.1 Appending Files to
an Archive</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC54">4.2.2.2 Multiple Members
with the Same Name</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="appending-files"></a>
+<a name="SEC53"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC52" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC54" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC52" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="subsubsection"> 4.2.2.1 Appending Files to an Archive </h4>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+<a name="IDX179"></a>
+<a name="IDX180"></a>
+<a name="IDX181"></a>
+
+<p>The simplest way to add a file to an already existing archive is the
+‘<samp>--append</samp>’ (‘<samp>-r</samp>’) operation,
which writes specified
+files into the archive whether or not they are already among the
+archived files.
+</p>
+<p>When you use ‘<samp>--append</samp>’, you <em>must</em> 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 ‘<samp>--verbose</samp>’
(‘<samp>-v</samp>’) option will print
+out the names of the files as they are written into the archive.
+</p>
+<p>‘<samp>--append</samp>’ cannot be performed on some tape
drives, unfortunately,
+due to deficiencies in the formats those tape drives use. The archive
+must be a valid <code>tar</code> archive, or else the results of using this
+operation will be unpredictable. See section <a href="#SEC143">Tapes and
Other Archive Media</a>.
+</p>
+<p>To demonstrate using ‘<samp>--append</samp>’ to add a file to
an archive,
+create a file called ‘<tt>rock</tt>’ in the
‘<tt>practice</tt>’ directory.
+Make sure you are in the ‘<tt>practice</tt>’ directory. Then, run
the
+following <code>tar</code> command to add ‘<tt>rock</tt>’ to
+‘<tt>collection.tar</tt>’:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --append
--file=collection.tar rock</kbd>
+</pre></td></tr></table>
+
+<p>If you now use the ‘<samp>--list</samp>’
(‘<samp>-t</samp>’) operation, you will see that
+‘<tt>rock</tt>’ has been added to the archive:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --list
--file=collection.tar</kbd>
+-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
+</pre></td></tr></table>
+
+<hr size="6">
+<a name="multiple"></a>
+<a name="SEC54"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC53" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC55" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC52" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="subsubsection"> 4.2.2.2 Multiple Members with the Same Name </h4>
+
+<p>You can use ‘<samp>--append</samp>’
(‘<samp>-r</samp>’) 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 <code>tar</code>
+option called ‘<samp>--update</samp>’; See section <a
href="#SEC55">Updating an Archive</a>, for more information.
+We describe this use of ‘<samp>--append</samp>’ 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.
+</p>
+<p>Supposing you change the file ‘<tt>blues</tt>’ and then append
the changed
+version to ‘<tt>collection.tar</tt>’. As you saw above, the
original
+‘<tt>blues</tt>’ is in the archive
‘<tt>collection.tar</tt>’. 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.
+</p>
+<p>You can append the new, changed copy of the file
‘<tt>blues</tt>’ to the
+archive in this way:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --append
--verbose --file=collection.tar blues</kbd>
+blues
+</pre></td></tr></table>
+
+<p>Because you specified the ‘<samp>--verbose</samp>’ option,
<code>tar</code> has
+printed the name of the file being appended as it was acted on. Now
+list the contents of the archive:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --list
--verbose --file=collection.tar</kbd>
+-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
+</pre></td></tr></table>
+
+<p>The newest version of ‘<tt>blues</tt>’ 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 ‘<tt>blues</tt>’ will be
+replaced by the newer version. You can confirm this by extracting
+the archive and running ‘<samp>ls</samp>’ on the directory.
+</p>
+<p>If you wish to extract the first occurrence of the file
‘<tt>blues</tt>’
+from the archive, use ‘<samp>--occurrence</samp>’ option, as shown
in
+the following example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --extract
-vv --occurrence --file=collection.tar blues</kbd>
+-rw-r--r-- me user 21 1996-09-23 16:44 blues
+</pre></td></tr></table>
+
+<p>See section <a href="#SEC67">Changing How <code>tar</code> Writes
Files</a>, for more information on ‘<samp>--extract</samp>’ and
+See section <a href="#SEC42">–occurrence</a>, for the description of
+‘<samp>--occurrence</samp>’ option.
+</p>
+<hr size="6">
+<a name="update"></a>
+<a name="SEC55"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC54" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC56" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC50" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.2.3 Updating an Archive </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+<a name="IDX182"></a>
+
+<a name="IDX183"></a>
+<p>In the previous section, you learned how to use
‘<samp>--append</samp>’ to
+add a file to an existing archive. A related operation is
+‘<samp>--update</samp>’ (‘<samp>-u</samp>’). The
‘<samp>--update</samp>’ operation
+updates a <code>tar</code> 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
+‘<samp>--append</samp>’).
+</p>
+<p>Unfortunately, you cannot use ‘<samp>--update</samp>’ with
magnetic tape drives.
+The operation will fail.
+</p>
+
+
+
+
+<p>Both ‘<samp>--update</samp>’ and
‘<samp>--append</samp>’ 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 ‘<samp>--backup</samp>’ option. See section <a
href="#SEC54">Multiple Members with the Same Name</a>, for a detailed
discussion.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC56">4.2.3.1 How to Update an
Archive Using
‘<samp>--update</samp>’</a></td><td> </td><td
align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="how-to-update"></a>
+<a name="SEC56"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC55" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC57" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC55" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="subsubsection"> 4.2.3.1 How to Update an Archive Using
‘<samp>--update</samp>’ </h4>
+
+<p>You must use file name arguments with the
‘<samp>--update</samp>’
+(‘<samp>-u</samp>’) operation. If you don't specify any files,
+<code>tar</code> won't act on any files and won't tell you that it didn't
+do anything (which may end up confusing you).
+</p>
+
+<p>To see the ‘<samp>--update</samp>’ option at work, create a new
file,
+‘<tt>classical</tt>’, in your practice directory, and some extra
text to the
+file ‘<tt>blues</tt>’, using any text editor. Then invoke
<code>tar</code> with
+the ‘<samp>update</samp>’ operation and the
‘<samp>--verbose</samp>’ (‘<samp>-v</samp>’)
+option specified, using the names of all the files in the practice
+directory as file name arguments:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --update -v
-f collection.tar blues folk rock classical</kbd>
+blues
+classical
+$
+</pre></td></tr></table>
+
+<p>Because we have specified verbose mode, <code>tar</code> 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</samp>’ and look
+at the archive, you will see ‘<tt>blues</tt>’ and
‘<tt>classical</tt>’ at its
+end. There will be a total of two versions of the member
‘<samp>blues</samp>’;
+the one at the end will be newer and larger, since you added text before
+updating it.
+</p>
+<p>(The reason <code>tar</code> 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. See section <a
href="#SEC143">Tapes and Other Archive Media</a>, for more
+information about tapes.
+</p>
+<p>‘<samp>--update</samp>’ (‘<samp>-u</samp>’) 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</acronym>
<code>tar</code>
+options intended specifically for backups are more
+efficient. If you need to run backups, please consult <a
href="#SEC86">Performing Backups and Restoring Files</a>.
+</p>
+<hr size="6">
+<a name="concatenate"></a>
+<a name="SEC57"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC56" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC58" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC50" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.2.4 Combining Archives with
‘<samp>--concatenate</samp>’ </h3>
+
+<p>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
+‘<samp>--concatenate</samp>’
(‘<samp>--catenate</samp>’, ‘<samp>-A</samp>’)
operation.
+</p>
+<p>To use ‘<samp>--concatenate</samp>’, give the first archive with
+‘<samp>--file</samp>’ 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.
+<a name="DOCF11" href="#FOOT11">(11)</a>
+The new, concatenated archive will be called by the same name as the
+one given with the ‘<samp>--file</samp>’ option. As usual, if you
omit
+‘<samp>--file</samp>’, <code>tar</code> will use the value of the
environment
+variable <code>TAPE</code>, or, if this has not been set, the default archive
name.
+</p>
+
+
+
+
+<p>To demonstrate how ‘<samp>--concatenate</samp>’ works, create
two small archives
+called ‘<tt>bluesrock.tar</tt>’ and
‘<tt>folkjazz.tar</tt>’, using the relevant
+files from ‘<tt>practice</tt>’:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cvf
bluesrock.tar blues rock</kbd>
+blues
+rock
+$ <kbd>tar -cvf folkjazz.tar folk jazz</kbd>
+folk
+jazz
+</pre></td></tr></table>
+
+<p>If you like, You can run ‘<samp>tar --list</samp>’ to make sure
the archives
+contain what they are supposed to:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -tvf
bluesrock.tar</kbd>
+-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</kbd>
+-rw-r--r-- melissa user 20 1996-09-23 16:44 folk
+-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
+</pre></td></tr></table>
+
+<p>We can concatenate these two archives with <code>tar</code>:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>cd ..</kbd>
+$ <kbd>tar --concatenate --file=bluesrock.tar jazzfolk.tar</kbd>
+</pre></td></tr></table>
+
+<p>If you now list the contents of the ‘<tt>bluesrock.tar</tt>’,
you will see
+that now it also contains the archive members of
‘<tt>jazzfolk.tar</tt>’:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --list
--file=bluesrock.tar</kbd>
+blues
+rock
+folk
+jazz
+</pre></td></tr></table>
+
+<p>When you use ‘<samp>--concatenate</samp>’, the source and
target archives must
+already exist and must have been created using compatible format
+parameters. Notice, that <code>tar</code> does not check whether the
+archives it concatenates have compatible formats, it does not
+even check if the files are really tar archives.
+</p>
+<p>Like ‘<samp>--append</samp>’ (‘<samp>-r</samp>’),
this operation cannot be performed on some
+tape drives, due to deficiencies in the formats those tape drives use.
+</p>
+<a name="IDX184"></a>
+<a name="IDX185"></a>
+<p>It may seem more intuitive to you to want or try to use <code>cat</code> to
+concatenate two archives instead of using the
‘<samp>--concatenate</samp>’
+operation; after all, <code>cat</code> is the utility for combining files.
+</p>
+<p>However, <code>tar</code> archives incorporate an end-of-file marker which
+must be removed if the concatenated archives are to be read properly as
+one archive. ‘<samp>--concatenate</samp>’ removes the
end-of-archive marker
+from the target archive before each new archive is appended. If you use
+<code>cat</code> to combine the archives, the result will not be a valid
+<code>tar</code> format archive. If you need to retrieve files from an
+archive that was added to using the <code>cat</code> utility, use the
+‘<samp>--ignore-zeros</samp>’ (‘<samp>-i</samp>’)
option. See section <a href="#SEC66">Ignoring Blocks of Zeros</a>, for further
+information on dealing with archives improperly combined using the
+<code>cat</code> shell utility.
+</p>
+<hr size="6">
+<a name="delete"></a>
+<a name="SEC58"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC57" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC59" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC50" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.2.5 Removing Archive Members Using
‘<samp>--delete</samp>’ </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+<a name="IDX186"></a>
+<a name="IDX187"></a>
+
+<a name="IDX188"></a>
+<p>You can remove members from an archive by using the
‘<samp>--delete</samp>’
+option. Specify the name of the archive with ‘<samp>--file</samp>’
+(‘<samp>-f</samp>’) and then specify the names of the members to
be deleted;
+if you list no member names, nothing will be deleted. The
+‘<samp>--verbose</samp>’ option will cause <code>tar</code> to
print the names
+of the members as they are deleted. As with
‘<samp>--extract</samp>’, you
+must give the exact member names when using ‘<samp>tar
--delete</samp>’.
+‘<samp>--delete</samp>’ will remove all versions of the named file
from the
+archive. The ‘<samp>--delete</samp>’ operation can run very
slowly.
+</p>
+<p>Unlike other operations, ‘<samp>--delete</samp>’ has no short
form.
+</p>
+<a name="IDX189"></a>
+<a name="IDX190"></a>
+<p>This operation will rewrite the archive. You can only use
+‘<samp>--delete</samp>’ 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. See section <a href="#SEC143">Tapes and Other
Archive Media</a>.
+</p>
+<p>To delete all versions of the file ‘<tt>blues</tt>’ from the
archive
+‘<tt>collection.tar</tt>’ in the ‘<tt>practice</tt>’
directory, make sure you
+are in that directory, and then,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --list
--file=collection.tar</kbd>
+blues
+folk
+jazz
+rock
+$ <kbd>tar --delete --file=collection.tar blues</kbd>
+$ <kbd>tar --list --file=collection.tar</kbd>
+folk
+jazz
+rock
+$
+</pre></td></tr></table>
+
+
+
+
+
+<p>The ‘<samp>--delete</samp>’ option has been reported to work
properly when
+<code>tar</code> acts as a filter from <code>stdin</code> to
<code>stdout</code>.
+</p>
+<hr size="6">
+<a name="compare"></a>
+<a name="SEC59"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC58" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC60" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC50" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.2.6 Comparing Archive Members with the File System
</h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX191"></a>
+<p>The ‘<samp>--compare</samp>’ (‘<samp>-d</samp>’),
or ‘<samp>--diff</samp>’ 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 <em>only</em> specify archive member names, not file
+names. If you do not name any members, then <code>tar</code> will compare the
+entire archive. If a file is represented in the archive but does not
+exist in the file system, <code>tar</code> reports a difference.
+</p>
+<p>You have to specify the record size of the archive when modifying an
+archive with a non-default record size.
+</p>
+<p><code>tar</code> ignores files in the file system that do not have
+corresponding members in the archive.
+</p>
+<p>The following example compares the archive members
‘<tt>rock</tt>’,
+‘<tt>blues</tt>’ and ‘<tt>funk</tt>’ in the archive
‘<tt>bluesrock.tar</tt>’ with
+files of the same name in the file system. (Note that there is no file,
+‘<tt>funk</tt>’; <code>tar</code> will report an error message.)
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --compare
--file=bluesrock.tar rock blues funk</kbd>
+rock
+blues
+tar: funk not found in archive
+</pre></td></tr></table>
+
+<p>The spirit behind the ‘<samp>--compare</samp>’
(‘<samp>--diff</samp>’,
+‘<samp>-d</samp>’) 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, See section <a
href="#SEC158">Verifying Data as It is Stored</a>.
+</p>
+<hr size="6">
+<a name="create-options"></a>
+<a name="SEC60"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC59" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC61" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 4.3 Options Used by ‘<samp>--create</samp>’
</h2>
+
+<p>The previous chapter described the basics of how to use
+‘<samp>--create</samp>’ (‘<samp>-c</samp>’) to create
an archive from a set of files.
+See section <a href="#SEC17">How to Create Archives</a>. This section
described advanced options to be used with
+‘<samp>--create</samp>’.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC61">4.3.1 Overriding File
Metadata</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC62">4.3.2 Ignore Fail
Read</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="override"></a>
+<a name="SEC61"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC60" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC62" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC60" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.3.1 Overriding File Metadata </h3>
+
+<p>As described above, a <code>tar</code> archive keeps, for each member it
contains,
+its <em>metadata</em>, such as modification time, mode and ownership of
+the file. <acronym>GNU</acronym> <code>tar</code> 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 <a href="#SEC136">Controlling Extended Header Keywords</a>, for
additional ways of controlling
+metadata, stored in the archive.
+</p>
+<dl compact="compact">
+<dd><a name="IDX192"></a>
+</dd>
+<dt> ‘<samp>--mode=<var>permissions</var></samp>’</dt>
+<dd>
+<p>When adding files to an archive, <code>tar</code> will use
+<var>permissions</var> for the archive members, rather than the permissions
+from the files. <var>permissions</var> can be specified either as an octal
+number or as symbolic permissions, like with
+<code>chmod</code> (See <a href="fileutils.html#File-permissions">Permissions:
(fileutils)File permissions</a> section `File permissions' in
<cite><acronym>GNU</acronym> file utilities</cite>. 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</samp>’ adds
read and write
+permissions for everybody, while retaining executable bits on directories
+or on any other file already marked as executable:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
archive.tar --mode='a+rw' .</kbd>
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>--mtime=<var>date</var></samp>’</dt>
+<dd><a name="IDX193"></a>
+
+<p>When adding files to an archive, <code>tar</code> will use <var>date</var>
as
+the modification time of members when creating archives, instead of
+their actual modification times. The argument <var>date</var> can be
+either a textual date representation in almost arbitrary format
+(see section <a href="#SEC113">Date input formats</a>) or a name of the
existing file, starting
+with ‘<samp>/</samp>’ or ‘<samp>.</samp>’. In the
latter case, the modification time
+of that file will be used.
+</p>
+<p>The following example will set the modification date to 00:00:00 UTC,
+January 1, 1970:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
archive.tar --mtime='1970-01-01' .</kbd>
+</pre></td></tr></table>
+
+<p>When used with ‘<samp>--verbose</samp>’ (see section <a
href="#SEC15">The ‘<samp>--verbose</samp>’ Option</a>)
<acronym>GNU</acronym> <code>tar</code>
+will try to convert the specified date back to its textual
+representation and compare it with the one given with
+‘<samp>--mtime</samp>’ options. If the two dates differ,
<code>tar</code> will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date.
+</p>
+<p>For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
archive.tar -v --mtime=yesterday .</kbd>
+tar: Option --mtime: Treating date `yesterday' as 2006-06-20
+13:06:29.152478
+…
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>--owner=<var>user</var></samp>’</dt>
+<dd><a name="IDX194"></a>
+
+<p>Specifies that <code>tar</code> should use <var>user</var> as the owner of
members
+when creating archives, instead of the user associated with the source
+file. The argument <var>user</var> can be either an existing user symbolic
+name, or a decimal numeric user ID.
+</p>
+<p>There is no value indicating a missing number, and
‘<samp>0</samp>’ usually means
+<code>root</code>. Some people like to force ‘<samp>0</samp>’ as
the value to offer in
+their distributions for the owner of files, because the <code>root</code> user
is
+anonymous anyway, so that might as well be the owner of anonymous
+archives. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
archive.tar --owner=0 .</kbd>
+# <span class="roman">Or:</span>
+$ <kbd>tar -c -f archive.tar --owner=root .</kbd>
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>--group=<var>group</var></samp>’</dt>
+<dd><a name="IDX195"></a>
+
+<p>Files added to the <code>tar</code> archive will have a group id of
<var>group</var>,
+rather than the group from the source file. The argument <var>group</var>
+can be either an existing group symbolic name, or a decimal numeric group ID.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Ignore-Failed-Read"></a>
+<a name="SEC62"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC61" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC63" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC60" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.3.2 Ignore Fail Read </h3>
+
+<dl compact="compact">
+<dt> ‘<samp>--ignore-failed-read</samp>’</dt>
+<dd><a name="IDX196"></a>
+<p>Do not exit with nonzero on unreadable files or directories.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="extract-options"></a>
+<a name="SEC63"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC62" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC64" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 4.4 Options Used by ‘<samp>--extract</samp>’
</h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX197"></a>
+<p>The previous chapter showed how to use ‘<samp>--extract</samp>’
to extract
+an archive into the file system. Various options cause <code>tar</code> 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 ‘<samp>--extract</samp>’ when
certain special
+considerations arise. You may review the information presented in
+<a href="#SEC25">How to Extract Members from an Archive</a> for more basic
information about the
+‘<samp>--extract</samp>’ operation.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC64">4.4.1 Options to Help Read
Archives</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC67">4.4.2 Changing How
<code>tar</code> Writes Files</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC80">4.4.3 Coping with Scarce
Resources</a></td><td> </td><td align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Reading"></a>
+<a name="SEC64"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC63" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC65" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC63" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.4.1 Options to Help Read Archives </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX198"></a>
+<a name="IDX199"></a>
+<a name="IDX200"></a>
+<p>Normally, <code>tar</code> will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
+<code>tar</code> 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
‘<samp>--read-full-records</samp>’ (‘<samp>-B</samp>’)
option
+in conjunction with the ‘<samp>--extract</samp>’ or
‘<samp>--list</samp>’ operations.
+See section <a href="#SEC147">Blocking</a>.
+</p>
+<p>The ‘<samp>--read-full-records</samp>’
(‘<samp>-B</samp>’) option is turned on by default when
+<code>tar</code> 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, <code>tar</code>
+would fail as soon as it read an incomplete record from the pipe.
+</p>
+<p>If you're not sure of the blocking factor of an archive, you can
+read the archive by specifying ‘<samp>--read-full-records</samp>’
(‘<samp>-B</samp>’) and
+‘<samp>--blocking-factor=<var>512-size</var></samp>’
(‘<samp>-b
+<var>512-size</var></samp>’), using a blocking factor larger than what
the archive
+uses. This lets you avoid having to determine the blocking factor
+of an archive. See section <a href="#SEC149">The Blocking Factor of an
Archive</a>.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC65">Reading Full
Records</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC66">Ignoring Blocks of
Zeros</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="read-full-records"></a>
+<a name="SEC65"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC64" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC66" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC64" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Reading Full Records </h4>
+
+
+
+
+
+<dl compact="compact">
+<dd><a name="IDX201"></a>
+</dd>
+<dt> ‘<samp>--read-full-records</samp>’</dt>
+<dt> ‘<samp>-B</samp>’</dt>
+<dd><p>Use in conjunction with ‘<samp>--extract</samp>’
(‘<samp>--get</samp>’,
+‘<samp>-x</samp>’) to read an archive which contains incomplete
records, or
+one which has a blocking factor less than the one specified.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Ignore-Zeros"></a>
+<a name="SEC66"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC65" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC64" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Ignoring Blocks of Zeros </h4>
+
+<p>Normally, <code>tar</code> stops reading when it encounters a block of zeros
+between file entries (which usually indicates the end of the archive).
+‘<samp>--ignore-zeros</samp>’ (‘<samp>-i</samp>’)
allows <code>tar</code> 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).
+</p>
+<p>The ‘<samp>--ignore-zeros</samp>’
(‘<samp>-i</samp>’) option is turned off by default because many
+versions of <code>tar</code> write garbage after the end-of-archive entry,
+since that part of the media is never supposed to be read.
<acronym>GNU</acronym> <code>tar</code>
+does not write after the end of an archive, but seeks to
+maintain compatiblity among archiving utilities.
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--ignore-zeros</samp>’</dt>
+<dt> ‘<samp>-i</samp>’</dt>
+<dd><p>To ignore blocks of zeros (i.e., end-of-archive entries) which may be
+encountered while reading an archive. Use in conjunction with
+‘<samp>--extract</samp>’ or ‘<samp>--list</samp>’.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Writing"></a>
+<a name="SEC67"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC66" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC68" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC63" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.4.2 Changing How <code>tar</code> Writes Files </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+
+
+
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC68">Options Controlling the
Overwriting of Existing Files</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC69">Overwrite Old
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC70">Keep Old
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC71">Keep Newer
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC72">Unlink
First</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC73">Recursive
Unlink</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC74">Setting Data Modification
Times</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC75">Setting Access
Permissions</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC76">Directory Modification
Times and Permissions</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC77">Writing to Standard
Output</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC78">Writing to an External
Program</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC79">Removing
Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Dealing-with-Old-Files"></a>
+<a name="SEC68"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC67" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC69" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Options Controlling the Overwriting of
Existing Files </h4>
+
+<p>When extracting files, if <code>tar</code> 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, <code>tar</code> normally overwrites its metadata (ownership,
+permission, etc.). The ‘<samp>--overwrite-dir</samp>’ option
enables this
+default behavior. To be more cautious and preserve the metadata of
+such a directory, use the ‘<samp>--no-overwrite-dir</samp>’ option.
+</p>
+<a name="IDX202"></a>
+<a name="IDX203"></a>
+<p>To be even more cautious and prevent existing files from being replaced, use
+the ‘<samp>--keep-old-files</samp>’
(‘<samp>-k</samp>’) option. It causes <code>tar</code> 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.
+</p>
+<a name="IDX204"></a>
+<p>To be more aggressive about altering existing files, use the
+‘<samp>--overwrite</samp>’ option. It causes <code>tar</code> to
overwrite
+existing files and to follow existing symbolic links when extracting.
+</p>
+<a name="IDX205"></a>
+<p>Some people argue that <acronym>GNU</acronym> <code>tar</code> should not
hesitate
+to overwrite files with other files when extracting. When extracting
+a <code>tar</code> 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 ‘<tt>usr/local</tt>’ is a link to
+‘<tt>usr/local2</tt>’. Since then, maybe the site removed the
link and
+renamed the whole hierarchy from ‘<tt>/usr/local2</tt>’ to
+‘<tt>/usr/local</tt>’. Such things happen all the time. I guess
it would
+not be welcome at all that <acronym>GNU</acronym> <code>tar</code> removes the
+whole hierarchy just to make room for the link to be reinstated
+(unless it <em>also</em> simultaneously restores the full
+‘<tt>/usr/local2</tt>’, of course!) <acronym>GNU</acronym>
<code>tar</code> is indeed
+able to remove a whole hierarchy to reestablish a symbolic link, for
+example, but <em>only if</em> ‘<samp>--recursive-unlink</samp>’ is
specified
+to allow this behavior. In any case, single files are silently
+removed.
+</p>
+<a name="IDX206"></a>
+<p>Finally, the ‘<samp>--unlink-first</samp>’
(‘<samp>-U</samp>’) option can improve performance in
+some cases by causing <code>tar</code> to remove files unconditionally
+before extracting them.
+</p>
+<hr size="6">
+<a name="Overwrite-Old-Files"></a>
+<a name="SEC69"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC68" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC70" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Overwrite Old Files </h4>
+
+<dl compact="compact">
+<dd><a name="IDX207"></a>
+</dd>
+<dt> ‘<samp>--overwrite</samp>’</dt>
+<dd><p>Overwrite existing files and directory metadata when extracting files
+from an archive.
+</p>
+<p>This causes <code>tar</code> 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 <code>tar</code> 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.
+</p>
+<p>Be careful when using the ‘<samp>--overwrite</samp>’ option,
particularly when
+combined with the ‘<samp>--absolute-names</samp>’
(‘<samp>-P</samp>’) 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.
+</p>
+<a name="IDX208"></a>
+</dd>
+<dt> ‘<samp>--overwrite-dir</samp>’</dt>
+<dd><p>Overwrite the metadata of directories when extracting files from an
+archive, but remove other files before extracting.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Keep-Old-Files"></a>
+<a name="SEC70"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC69" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC71" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Keep Old Files </h4>
+
+<dl compact="compact">
+<dd><a name="IDX209"></a>
+</dd>
+<dt> ‘<samp>--keep-old-files</samp>’</dt>
+<dt> ‘<samp>-k</samp>’</dt>
+<dd><p>Do not replace existing files from archive. The
+‘<samp>--keep-old-files</samp>’ (‘<samp>-k</samp>’)
option prevents <code>tar</code>
+from replacing existing files with files with the same name from the
+archive. The ‘<samp>--keep-old-files</samp>’ option is meaningless
with
+‘<samp>--list</samp>’ (‘<samp>-t</samp>’). Prevents
<code>tar</code> from replacing
+files in the file system during extraction.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Keep-Newer-Files"></a>
+<a name="SEC71"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC70" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC72" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Keep Newer Files </h4>
+
+<dl compact="compact">
+<dd><a name="IDX210"></a>
+</dd>
+<dt> ‘<samp>--keep-newer-files</samp>’</dt>
+<dd><p>Do not replace existing files that are newer than their archive
+copies. This option is meaningless with ‘<samp>--list</samp>’
(‘<samp>-t</samp>’).
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Unlink-First"></a>
+<a name="SEC72"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC71" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC73" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Unlink First </h4>
+
+<dl compact="compact">
+<dd><a name="IDX211"></a>
+</dd>
+<dt> ‘<samp>--unlink-first</samp>’</dt>
+<dt> ‘<samp>-U</samp>’</dt>
+<dd><p>Remove files before extracting over them.
+This can make <code>tar</code> run a bit faster if you know in advance
+that the extracted files all need to be removed. Normally this option
+slows <code>tar</code> down slightly, so it is disabled by default.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Recursive-Unlink"></a>
+<a name="SEC73"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC72" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC74" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Recursive Unlink </h4>
+
+<dl compact="compact">
+<dd><a name="IDX212"></a>
+</dd>
+<dt> ‘<samp>--recursive-unlink</samp>’</dt>
+<dd><p>When this option is specified, try removing files and directory
hierarchies
+before extracting over them. <em>This is a dangerous option!</em>
+</p></dd>
+</dl>
+
+<p>If you specify the ‘<samp>--recursive-unlink</samp>’ option,
+<code>tar</code> removes <em>anything</em> 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.
+</p>
+<hr size="6">
+<a name="Data-Modification-Times"></a>
+<a name="SEC74"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC73" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC75" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Setting Data Modification Times </h4>
+
+<p>Normally, <code>tar</code> 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</code>
+setting.
+</p>
+<p>To set the data modification times of extracted files to the time when
+the files were extracted, use the ‘<samp>--touch</samp>’
(‘<samp>-m</samp>’) option in
+conjunction with ‘<samp>--extract</samp>’
(‘<samp>--get</samp>’, ‘<samp>-x</samp>’).
+</p>
+<dl compact="compact">
+<dd><a name="IDX213"></a>
+</dd>
+<dt> ‘<samp>--touch</samp>’</dt>
+<dt> ‘<samp>-m</samp>’</dt>
+<dd><p>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 ‘<samp>--extract</samp>’
(‘<samp>--get</samp>’, ‘<samp>-x</samp>’).
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Setting-Access-Permissions"></a>
+<a name="SEC75"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC74" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC76" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Setting Access Permissions </h4>
+
+<p>To set the modes (access permissions) of extracted files to those
+recorded for those files in the archive, use
‘<samp>--same-permissions</samp>’
+in conjunction with the ‘<samp>--extract</samp>’
(‘<samp>--get</samp>’,
+‘<samp>-x</samp>’) operation.
+</p>
+<dl compact="compact">
+<dd><a name="IDX214"></a>
+<a name="IDX215"></a>
+</dd>
+<dt> ‘<samp>--preserve-permissions</samp>’</dt>
+<dt> ‘<samp>--same-permissions</samp>’</dt>
+<dt> ‘<samp>-p</samp>’</dt>
+<dd><p>Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings. Use in conjunction with
+‘<samp>--extract</samp>’ (‘<samp>--get</samp>’,
‘<samp>-x</samp>’).
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Directory-Modification-Times-and-Permissions"></a>
+<a name="SEC76"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC75" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC77" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Directory Modification Times and Permissions
</h4>
+
+<p>After sucessfully extracting a file member, <acronym>GNU</acronym>
<code>tar</code> normally
+restores its permissions and modification times, as described in the
+previous sections. This cannot be done for directories, because
+after extracting a directory <code>tar</code> 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</acronym> <code>tar</code>
+restores directories using the following approach.
+</p>
+<p>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</acronym>
<code>tar</code> 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 <code>tar</code> archives use the predefined
+order of members: first the directory, then all the files and
+subdirectories in that directory.
+</p>
+<p>However, this is not always true. The most important exception are
+incremental archives (see section <a href="#SEC88">Using <code>tar</code> to
Perform Incremental Dumps</a>). 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</acronym> <code>tar</code> 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</acronym>
<code>tar</code>
+automatically detects archives in incremental format.
+</p>
+<p>There may be cases, when such processing is required for normal archives
+too. Consider the following example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar
--no-recursion -cvf archive \
+ foo foo/file1 bar bar/file foo/file2</kbd>
+foo/
+foo/file1
+bar/
+bar/file
+foo/file2
+</pre></td></tr></table>
+
+<p>During the normal operation, after encountering ‘<tt>bar</tt>’
+<acronym>GNU</acronym> <code>tar</code> will assume that all files from the
directory ‘<tt>foo</tt>’
+were already extracted and will therefore restore its timestamp and
+permission bits. However, after extracting ‘<tt>foo/file2</tt>’
the
+directory timestamp will be offset again.
+</p>
+<p>To correctly restore directory meta-information in such cases, use
+‘<samp>delay-directory-restore</samp>’ command line option:
+</p>
+<dl compact="compact">
+<dd><a name="IDX216"></a>
+</dd>
+<dt> ‘<samp>--delay-directory-restore</samp>’</dt>
+<dd><p>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.
+</p>
+<a name="IDX217"></a>
+</dd>
+<dt> ‘<samp>--no-delay-directory-restore</samp>’</dt>
+<dd><p>Cancel the effect of the previous
‘<samp>--delay-directory-restore</samp>’.
+Use this option if you have used
‘<samp>--delay-directory-restore</samp>’ in
+<code>TAR_OPTIONS</code> variable (see <a
href="#TAR_005fOPTIONS">TAR_OPTIONS</a>) and wish to
+temporarily disable it.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Writing-to-Standard-Output"></a>
+<a name="SEC77"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC76" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC78" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Writing to Standard Output </h4>
+
+<p>To write the extracted files to the standard output, instead of
+creating the files on the file system, use
‘<samp>--to-stdout</samp>’ (‘<samp>-O</samp>’) in
+conjunction with ‘<samp>--extract</samp>’
(‘<samp>--get</samp>’, ‘<samp>-x</samp>’). 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.
+</p>
+<dl compact="compact">
+<dd><a name="IDX218"></a>
+</dd>
+<dt> ‘<samp>--to-stdout</samp>’</dt>
+<dt> ‘<samp>-O</samp>’</dt>
+<dd><p>Writes files to the standard output. Use only in conjunction with
+‘<samp>--extract</samp>’ (‘<samp>--get</samp>’,
‘<samp>-x</samp>’). When this option is
+used, instead of creating the files specified, <code>tar</code> 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
‘<samp>--list</samp>’
+(‘<samp>-t</samp>’).
+</p></dd>
+</dl>
+
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar -xOzf foo.tgz
bigfile | process
+</pre></td></tr></table>
+
+<p>or even like this if you want to process the concatenation of the files:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar -xOzf foo.tgz
bigfile1 bigfile2 | process
+</pre></td></tr></table>
+
+<p>Hovewer, ‘<samp>--to-command</samp>’ may be more convenient for
use with
+multiple files. See the next section.
+</p>
+<hr size="6">
+<a name="Writing-to-an-External-Program"></a>
+<a name="SEC78"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC77" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC79" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Writing to an External Program </h4>
+
+<p>You can instruct <code>tar</code> to send the contents of each extracted
+file to the standard input of an external program:
+</p>
+<dl compact="compact">
+<dd><a name="IDX219"></a>
+</dd>
+<dt> ‘<samp>--to-command=<var>command</var></samp>’</dt>
+<dd><p>Extract files and pipe their contents to the standard input of
+<var>command</var>. When this option is used, instead of creating the
+files specified, <code>tar</code> invokes <var>command</var> and pipes the
+contents of the files to its standard output. <var>Command</var> may
+contain command line arguments. The program is executed via
+<code>sh -c</code>. Notice, that <var>command</var> is executed once for each
regular file
+extracted. Non-regular files (directories, etc.) are ignored when this
+option is used.
+</p></dd>
+</dl>
+
+<p>The command can obtain the information about the file it processes
+from the following environment variables:
+</p>
+<dl compact="compact">
+<dd><a name="IDX220"></a>
+</dd>
+<dt> <var>TAR_FILETYPE</var></dt>
+<dd><p>Type of the file. It is a single letter with the following meaning:
+</p>
+<table>
+<tr><td><p> f </p></td><td><p> Regular file
+</p></td></tr>
+<tr><td><p> d </p></td><td><p> Directory
+</p></td></tr>
+<tr><td><p> l </p></td><td><p> Symbolic link
+</p></td></tr>
+<tr><td><p> h </p></td><td><p> Hard link
+</p></td></tr>
+<tr><td><p> b </p></td><td><p> Block device
+</p></td></tr>
+<tr><td><p> c </p></td><td><p> Character device
+</p></td></tr>
+</table>
+
+<p>Currently only regular files are supported.
+</p>
+<a name="IDX221"></a>
+</dd>
+<dt> <var>TAR_MODE</var></dt>
+<dd><p>File mode, an octal number.
+</p>
+<a name="IDX222"></a>
+</dd>
+<dt> <var>TAR_FILENAME</var></dt>
+<dd><p>The name of the file.
+</p>
+<a name="IDX223"></a>
+</dd>
+<dt> <var>TAR_REALNAME</var></dt>
+<dd><p>Name of the file as stored in the archive.
+</p>
+<a name="IDX224"></a>
+</dd>
+<dt> <var>TAR_UNAME</var></dt>
+<dd><p>Name of the file owner.
+</p>
+<a name="IDX225"></a>
+</dd>
+<dt> <var>TAR_GNAME</var></dt>
+<dd><p>Name of the file owner group.
+</p>
+<a name="IDX226"></a>
+</dd>
+<dt> <var>TAR_ATIME</var></dt>
+<dd><p>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.
+</p>
+<a name="IDX227"></a>
+</dd>
+<dt> <var>TAR_MTIME</var></dt>
+<dd><p>Time of last modification.
+</p>
+<a name="IDX228"></a>
+</dd>
+<dt> <var>TAR_CTIME</var></dt>
+<dd><p>Time of last status change.
+</p>
+<a name="IDX229"></a>
+</dd>
+<dt> <var>TAR_SIZE</var></dt>
+<dd><p>Size of the file.
+</p>
+<a name="IDX230"></a>
+</dd>
+<dt> <var>TAR_UID</var></dt>
+<dd><p>UID of the file owner.
+</p>
+<a name="IDX231"></a>
+</dd>
+<dt> <var>TAR_GID</var></dt>
+<dd><p>GID of the file owner.
+</p></dd>
+</dl>
+
+<p>In addition to these variables, <code>TAR_VERSION</code> contains the
+<acronym>GNU</acronym> <code>tar</code> version number.
+</p>
+<p>If <var>command</var> exits with a non-0 status, <code>tar</code> will print
+an error message similar to the following:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar: 2345: Child
returned status 1
+</pre></td></tr></table>
+
+<p>Here, ‘<samp>2345</samp>’ is the PID of the finished process.
+</p>
+<p>If this behavior is not wanted, use
‘<samp>--ignore-command-error</samp>’:
+</p>
+<dl compact="compact">
+<dd><a name="IDX232"></a>
+</dd>
+<dt> ‘<samp>--ignore-command-error</samp>’</dt>
+<dd><p>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.
+</p>
+<a name="IDX233"></a>
+</dd>
+<dt> ‘<samp>--no-ignore-command-error</samp>’</dt>
+<dd><p>Cancel the effect of any previous
‘<samp>--ignore-command-error</samp>’
+option. This option is useful if you have set
+‘<samp>--ignore-command-error</samp>’ in <code>TAR_OPTIONS</code>
+(see <a href="#TAR_005fOPTIONS">TAR_OPTIONS</a>) and wish to temporarily
cancel it.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="remove-files"></a>
+<a name="SEC79"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC78" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC80" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Removing Files </h4>
+
+
+
+
+
+<dl compact="compact">
+<dd><a name="IDX234"></a>
+</dd>
+<dt> ‘<samp>--remove-files</samp>’</dt>
+<dd><p>Remove files after adding them to the archive.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Scarce"></a>
+<a name="SEC80"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC79" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC81" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC63" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 4.4.3 Coping with Scarce Resources </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX235"></a>
+<a name="IDX236"></a>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC81">Starting
File</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC82">Same
Order</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Starting-File"></a>
+<a name="SEC81"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC80" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC82" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC80" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Starting File </h4>
+
+<dl compact="compact">
+<dd><a name="IDX237"></a>
+</dd>
+<dt> ‘<samp>--starting-file=<var>name</var></samp>’</dt>
+<dt> ‘<samp>-K <var>name</var></samp>’</dt>
+<dd><p>Starts an operation in the middle of an archive. Use in conjunction
+with ‘<samp>--extract</samp>’ (‘<samp>--get</samp>’,
‘<samp>-x</samp>’) or ‘<samp>--list</samp>’
(‘<samp>-t</samp>’).
+</p></dd>
+</dl>
+
+<a name="IDX238"></a>
+<p>If a previous attempt to extract files failed due to lack of disk
+space, you can use ‘<samp>--starting-file=<var>name</var></samp>’
(‘<samp>-K
+<var>name</var></samp>’) to start extracting only after member
<var>name</var> 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 <code>tar</code>, remove unnecessary files from
+the file system, and then restart the same <code>tar</code> operation.
+In this case, ‘<samp>--starting-file</samp>’ is not necessary.
+See section <a href="#SEC88">Using <code>tar</code> to Perform Incremental
Dumps</a>, See section <a href="#SEC47">Asking for Confirmation During
Operations</a>, and <a href="#SEC102">Excluding Some Files</a>.)
+</p>
+<hr size="6">
+<a name="Same-Order"></a>
+<a name="SEC82"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC81" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC83" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC80" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="unnumberedsubsubsec"> Same Order </h4>
+
+<dl compact="compact">
+<dd><a name="IDX239"></a>
+<a name="IDX240"></a>
+<a name="IDX241"></a>
+</dd>
+<dt> ‘<samp>--same-order</samp>’</dt>
+<dt> ‘<samp>--preserve-order</samp>’</dt>
+<dt> ‘<samp>-s</samp>’</dt>
+<dd><p>To process large lists of file names on machines with small amounts of
+memory. Use in conjunction with ‘<samp>--compare</samp>’
(‘<samp>--diff</samp>’,
+‘<samp>-d</samp>’), ‘<samp>--list</samp>’
(‘<samp>-t</samp>’) or ‘<samp>--extract</samp>’
+(‘<samp>--get</samp>’, ‘<samp>-x</samp>’).
+</p></dd>
+</dl>
+
+<p>The ‘<samp>--same-order</samp>’
(‘<samp>--preserve-order</samp>’, ‘<samp>-s</samp>’)
option tells <code>tar</code> 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</samp>’ on the archive and
editing its output.
+</p>
+<p>This option is probably never needed on modern computer systems.
+</p>
+<hr size="6">
+<a name="backup"></a>
+<a name="SEC83"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC82" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC84" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 4.5 Backup options </h2>
+
+
+<p><acronym>GNU</acronym> <code>tar</code> 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
+<acronym>GNU</acronym> programs (<code>cp</code>, <code>install</code>,
<code>ln</code>,
+and <code>mv</code>, for example) offer similar options.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--backup[=<var>method</var>]</samp>’</dt>
+<dd><a name="IDX242"></a>
+<a name="IDX243"></a>
+<a name="IDX244"></a>
+<p>Back up files that are about to be overwritten or removed.
+Without this option, the original versions are destroyed.
+</p>
+<p>Use <var>method</var> to determine the type of backups made.
+If <var>method</var> is not specified, use the value of the
<code>VERSION_CONTROL</code>
+environment variable. And if <code>VERSION_CONTROL</code> is not set,
+use the ‘<samp>existing</samp>’ method.
+</p>
+<a name="IDX245"></a>
+<p>This option corresponds to the Emacs variable
‘<samp>version-control</samp>’;
+the same values for <var>method</var> are accepted as in Emacs. This option
+also allows more descriptive names. The valid <var>method</var>s are:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>t</samp>’</dt>
+<dt> ‘<samp>numbered</samp>’</dt>
+<dd><a name="IDX246"></a>
+<p>Always make numbered backups.
+</p>
+</dd>
+<dt> ‘<samp>nil</samp>’</dt>
+<dt> ‘<samp>existing</samp>’</dt>
+<dd><a name="IDX247"></a>
+<p>Make numbered backups of files that already have them, simple backups
+of the others.
+</p>
+</dd>
+<dt> ‘<samp>never</samp>’</dt>
+<dt> ‘<samp>simple</samp>’</dt>
+<dd><a name="IDX248"></a>
+<p>Always make simple backups.
+</p>
+</dd>
+</dl>
+
+</dd>
+<dt> ‘<samp>--suffix=<var>suffix</var></samp>’</dt>
+<dd><a name="IDX249"></a>
+<a name="IDX250"></a>
+<a name="IDX251"></a>
+<p>Append <var>suffix</var> to each backup file made with
‘<samp>--backup</samp>’. If this
+option is not specified, the value of the <code>SIMPLE_BACKUP_SUFFIX</code>
+environment variable is used. And if <code>SIMPLE_BACKUP_SUFFIX</code> is not
+set, the default is ‘<samp>~</samp>’, just as in Emacs.
+</p>
+</dd>
+</dl>
+
+<hr size="6">
+<a name="Applications"></a>
+<a name="SEC84"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC83" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC85" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 4.6 Notable <code>tar</code> Usages </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+
+
+
+
+
+
+
+
+<a name="IDX252"></a>
+<p>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 <code>uuencode</code> 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 <code>tar</code> program.
+</p>
+<p>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 <em>pipe</em>, which is one a Unix redirection mechanism:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>(cd sourcedir;
tar -cf - .) | (cd targetdir; tar -xf -)</kbd>
+</pre></td></tr></table>
+
+<p>You can avoid subshells by using ‘<samp>-C</samp>’ option:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -C
sourcedir -cf - . | tar -C targetdir -xf -</kbd>
+</pre></td></tr></table>
+
+<p>The command also works using short option forms:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>(cd sourcedir;
tar --create --file=- . ) \
+ | (cd targetdir; tar --extract --file=-)</kbd>
+# Or:
+$ <kbd>tar --directory sourcedir --create --file=- . ) \
+ | tar --directory targetdir --extract --file=-</kbd>
+</pre></td></tr></table>
+
+<p>This is one of the easiest methods to transfer a <code>tar</code> archive.
+</p>
+<hr size="6">
+<a name="looking-ahead"></a>
+<a name="SEC85"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC84" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 4.7 Looking Ahead: The Rest of this Manual </h2>
+
+<p>You have now seen how to use all eight of the operations available to
+<code>tar</code>, 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 <code>tar</code> (this can help you save time if you expect to
+archive the same list of files a number of times), and so forth.
+
+
+</p>
+
+<p>If there are too many files to conveniently list on the command line,
+you can list the names in a file, and <code>tar</code> will read that file.
+See section <a href="#SEC100">Reading Names from a File</a>.
+</p>
+<p>There are various ways of causing <code>tar</code> to skip over some files,
+and not archive them. See section <a href="#SEC97">Choosing Files and Names
for <code>tar</code></a>.
+</p>
+<hr size="6">
+<a name="Backups"></a>
+<a name="SEC86"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC85" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC87" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 5. Performing Backups and Restoring Files </h1>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p><acronym>GNU</acronym> <code>tar</code> 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.
+</p>
+<p>Some users are enthusiastic about <code>Amanda</code> (The Advanced Maryland
+Automatic Network Disk Archiver), a backup system developed by James
+da Silva ‘<tt>address@hidden</tt>’ and available on many Unix
systems.
+This is free software, and it is available at these places:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">http://www.cs.umd.edu/projects/amanda/amanda.html
+ftp://ftp.cs.umd.edu/pub/amanda
+</pre></td></tr></table>
+
+
+
+
+
+<p>This chapter documents both the provided shell scripts and <code>tar</code>
+options which are more specific to usage as a backup tool.
+</p>
+<p>To <em>back up</em> 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 <em>backups</em> are also
+called <em>dumps</em>.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC87">5.1 Using <code>tar</code>
to Perform Full Dumps</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC88">5.2 Using <code>tar</code>
to Perform Incremental Dumps</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC89">5.3 Levels of
Backups</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC90">5.4 Setting Parameters for
Backups and Restoration</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC95">5.5 Using the Backup
Scripts</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC96">5.6 Using the Restore
Script</a></td><td> </td><td align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Full-Dumps"></a>
+<a name="SEC87"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC86" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC88" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 5.1 Using <code>tar</code> to Perform Full Dumps </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX253"></a>
+<a name="IDX254"></a>
+
+<a name="IDX255"></a>
+<p>Full dumps should only be made when no other people or programs
+are modifying files in the file system. If files are modified while
+<code>tar</code> 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.)
+</p>
+<p>You will want to use the
‘<samp>--label=<var>archive-label</var></samp>’
+(‘<samp>-V <var>archive-label</var></samp>’) 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.
+</p>
+<p>Unless the file system you are dumping is guaranteed to fit on
+one volume, you will need to use the ‘<samp>--multi-volume</samp>’
(‘<samp>-M</samp>’) option.
+Make sure you have enough tapes on hand to complete the backup.
+</p>
+<p>If you want to dump each file system separately you will need to use
+the ‘<samp>--one-file-system</samp>’ option to prevent
+<code>tar</code> from crossing file system boundaries when storing
+(sub)directories.
+</p>
+<p>The ‘<samp>--incremental</samp>’
(‘<samp>-G</samp>’) (see section <a href="#SEC88">Using
<code>tar</code> to Perform Incremental Dumps</a>)
+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.
+</p>
+<p>Unless you are in a hurry, and trust the <code>tar</code> program (and your
+tapes), it is a good idea to use the ‘<samp>--verify</samp>’
(‘<samp>-W</samp>’)
+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.
+</p>
+<hr size="6">
+<a name="Incremental-Dumps"></a>
+<a name="SEC88"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC87" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC89" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 5.2 Using <code>tar</code> to Perform Incremental Dumps
</h2>
+
+<p><em>Incremental backup</em> is a special form of <acronym>GNU</acronym>
<code>tar</code> archive that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> currently offers two options for
handling incremental
+backups:
‘<samp>--listed-incremental=<var>snapshot-file</var></samp>’
(‘<samp>-g
+<var>snapshot-file</var></samp>’) and
‘<samp>--incremental</samp>’ (‘<samp>-G</samp>’).
+</p>
+<a name="IDX256"></a>
+<p>The option ‘<samp>--listed-incremental</samp>’ instructs tar to
operate on
+an incremental archive with additional metadata stored in a standalone
+file, called a <em>snapshot file</em>. 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:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--listed-incremental=<var>file</var></samp>’</dt>
+<dt> ‘<samp>-g <var>file</var></samp>’</dt>
+<dd><p> Handle incremental backups with snapshot data in <var>file</var>.
+</p></dd>
+</dl>
+
+<p>To create an incremental backup, you would use
+‘<samp>--listed-incremental</samp>’ together with
‘<samp>--create</samp>’
+(see section <a href="#SEC17">How to Create Archives</a>). For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create \
+ --file=archive.1.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr</kbd>
+</pre></td></tr></table>
+
+<p>This will create in ‘<tt>archive.1.tar</tt>’ an incremental
backup of
+the ‘<tt>/usr</tt>’ file system, storing additional metadata in
the file
+‘<tt>/var/log/usr.snar</tt>’. If this file does not exist, it
will be
+created. The created archive will then be a <em>level 0 backup</em>;
+please see the next section for more on backup levels.
+</p>
+<p>Otherwise, if the file ‘<tt>/var/log/usr.snar</tt>’ 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 ‘<tt>/usr/doc/old</tt>’ and create
+directory ‘<tt>/usr/local/db</tt>’ with the following contents:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>ls
/usr/local/db</kbd>
+/usr/local/db/data
+/usr/local/db/index
+</pre></td></tr></table>
+
+<p>Some time later you create another incremental backup. You will
+then see:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar \
+ /usr</kbd>
+tar: usr/local/db: Directory is new
+usr/local/db/
+usr/local/db/data
+usr/local/db/index
+</pre></td></tr></table>
+
+<p>The created archive ‘<tt>archive.2.tar</tt>’ will contain only
these
+three members. This archive is called a <em>level 1 backup</em>. Notice
+that ‘<tt>/var/log/usr.snar</tt>’ will be updated with the new
data, so if
+you plan to create more ‘<samp>level 1</samp>’ backups, it is
necessary to
+create a working copy of the snapshot file before running
+<code>tar</code>. The above example will then be modified as follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>cp
/var/log/usr.snar /var/log/usr.snar-1</kbd>
+$ <kbd>tar --create \
+ --file=archive.2.tar \
+ --listed-incremental=/var/log/usr.snar-1 \
+ /usr</kbd>
+</pre></td></tr></table>
+
+<p>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 ‘<samp>--atime-preserve=replace</samp>’ option), or if
you set the clock
+backwards.
+</p>
+<p>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.
+</p>
+<p>Note that incremental archives use <code>tar</code> extensions and may
+not be readable by non-<acronym>GNU</acronym> versions of the <code>tar</code>
program.
+</p>
+<a name="IDX257"></a>
+<a name="IDX258"></a>
+<p>To extract from the incremental dumps, use
+‘<samp>--listed-incremental</samp>’ together with
‘<samp>--extract</samp>’
+option (see section <a href="#SEC27">Extracting Specific Files</a>). In this
case, <code>tar</code> 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 ‘<samp>--listed-incremental</samp>’,
the usual
+practice is to use ‘<samp>--listed-incremental=/dev/null</samp>’.
+Alternatively, you can use ‘<samp>--incremental</samp>’, which
needs no
+arguments. In general, ‘<samp>--incremental</samp>’
(‘<samp>-G</samp>’) can be
+used as a shortcut for ‘<samp>--listed-incremental</samp>’ when
listing or
+extracting incremental backups (for more information, regarding this
+option, see <a href="#incremental_002dop">incremental-op</a>).
+</p>
+<p>When extracting from the incremental backup <acronym>GNU</acronym>
<code>tar</code> attempts to
+restore the exact state the file system had when the archive was
+created. In particular, it will <em>delete</em> 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
‘<tt>/usr</tt>’
+file system, one would do<a name="DOCF12" href="#FOOT12">(12)</a>:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.1.tar</kbd>
+$ <kbd>tar --extract \
+ --listed-incremental=/dev/null \
+ --file archive.2.tar</kbd>
+</pre></td></tr></table>
+
+<p>To list the contents of an incremental archive, use
‘<samp>--list</samp>’
+(see section <a href="#SEC23">How to List Archives</a>), as usual. To obtain
more information about the
+archive, use ‘<samp>--listed-incremental</samp>’ or
‘<samp>--incremental</samp>’
+combined with two ‘<samp>--verbose</samp>’ options<a name="DOCF13"
href="#FOOT13">(13)</a>:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tar --list
--incremental --verbose --verbose archive.tar</kbd>
+</pre></td></tr></table>
+
+<p>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
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><var>x</var>
<var>file</var>
+</pre></td></tr></table>
+
+<p>where <var>x</var> is a letter describing the status of the file:
‘<samp>Y</samp>’
+if the file is present in the archive, ‘<samp>N</samp>’ if the
file is not
+included in the archive, or a ‘<samp>D</samp>’ if the file is a
directory (and
+is included in the archive). See section <a href="#SEC170">Dumpdir</a>, 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.
+</p>
+<p><a name="incremental_002dop"></a>The option
‘<samp>--incremental</samp>’ (‘<samp>-G</samp>’)
+gives the same behavior as ‘<samp>--listed-incremental</samp>’
when used
+with ‘<samp>--list</samp>’ and
‘<samp>--extract</samp>’ options. When used with
+‘<samp>--create</samp>’ option, it creates an incremental archive
without
+creating snapshot file. Thus, it is impossible to create several
+levels of incremental backups with ‘<samp>--incremental</samp>’
option.
+</p>
+<hr size="6">
+<a name="Backup-Levels"></a>
+<a name="SEC89"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC88" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC90" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 5.3 Levels of Backups </h2>
+
+<p>An archive containing all the files in the file system is called a
+<em>full backup</em> or <em>full dump</em>. 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.
+</p>
+<p>It is more efficient to do a full dump only occasionally. To back up
+files between full dumps, you can use <em>incremental dumps</em>. A <em>level
+one</em> dump archives all the files that have changed since the last full
+dump.
+</p>
+<p>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).
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> 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 <code>tar</code> commands by hand.
+</p>
+<p>Before you use these scripts, you need to edit the file
+‘<tt>backup-specs</tt>’, which specifies parameters used by the
backup
+scripts and by the restore script. This file is usually located
+in ‘<tt>/etc/backup</tt>’ directory. See section <a
href="#SEC90">Setting Parameters for Backups and Restoration</a>, for its
+detailed description. Once the backup parameters are set, you can
+perform backups or restoration by running the appropriate script.
+</p>
+<p>The name of the backup script is <code>backup</code>. The name of the
+restore script is <code>restore</code>. The following sections describe
+their use in detail.
+</p>
+<p><em>Please Note:</em> 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. See section <a href="#SEC88">Using
<code>tar</code> to Perform Incremental Dumps</a>, before
+making such an attempt.
+</p>
+<hr size="6">
+<a name="Backup-Parameters"></a>
+<a name="SEC90"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC89" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC91" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 5.4 Setting Parameters for Backups and Restoration </h2>
+
+<p>The file ‘<tt>backup-specs</tt>’ specifies backup parameters
for the
+backup and restoration scripts provided with <code>tar</code>. You must
+edit ‘<tt>backup-specs</tt>’ to fit your system configuration and
schedule
+before using these scripts.
+</p>
+<p>Syntactically, ‘<tt>backup-specs</tt>’ 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</code> below).
+For more information about shell script syntax, please refer to
+<a
href="http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
g_02">the definition of the Shell Command Language</a>. See also
+<a href="bashref.html#Top">(bashref)Top</a> section `Bash Features' in
<cite>Bash Reference Manual</cite>.
+</p>
+<p>The shell variables controlling behavior of <code>backup</code> and
+<code>restore</code> are described in the following subsections.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC91">5.4.1 General-Purpose
Variables</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC92">5.4.2 Magnetic Tape
Control</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC93">5.4.3 User
Hooks</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC94">5.4.4 An Example Text of
‘<tt>Backup-specs</tt>’</a></td><td> </td><td
align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="General_002dPurpose-Variables"></a>
+<a name="SEC91"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC90" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC92" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC90" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 5.4.1 General-Purpose Variables </h3>
+
+<dl>
+<dt><u>Backup variable:</u> <b>ADMINISTRATOR</b>
+<a name="IDX263"></a>
+</dt>
+<dd><p>The user name of the backup administrator. <code>Backup</code> scripts
+sends a backup report to this address.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>BACKUP_HOUR</b>
+<a name="IDX264"></a>
+</dt>
+<dd><p>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>:<var>minutes</var>,
+or the string ‘<samp>now</samp>’.
+</p>
+<p>This variable is used by <code>backup</code>. Its value may be overridden
+using ‘<samp>--time</samp>’ option (see section <a
href="#SEC95">Using the Backup Scripts</a>).
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>TAPE_FILE</b>
+<a name="IDX265"></a>
+</dt>
+<dd><p>The device <code>tar</code> writes the archive to. If
<var>TAPE_FILE</var>
+is a remote archive (see <a href="#remote_002ddev">remote-dev</a>), backup
script will suppose
+that your <code>mt</code> is able to access remote devices. If <var>RSH</var>
+(see <a href="#RSH">RSH</a>) is set, ‘<samp>--rsh-command</samp>’
option will be added to
+invocations of <code>mt</code>.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>BLOCKING</b>
+<a name="IDX266"></a>
+</dt>
+<dd><p>The blocking factor <code>tar</code> will use when writing the dump
archive.
+See section <a href="#SEC149">The Blocking Factor of an Archive</a>.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>BACKUP_DIRS</b>
+<a name="IDX267"></a>
+</dt>
+<dd><p>A list of file systems to be dumped (for <code>backup</code>), or
restored
+(for <code>restore</code>). 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.
+</p>
+<p>The host name specifies which host to run <code>tar</code> on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have <acronym>GNU</acronym> <code>tar</code> 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 <code>pwd</code> 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.
+</p>
+<p>If the list of file systems is very long you may wish to put it
+in a separate file. This file is usually named
+‘<tt>/etc/backup/dirs</tt>’, but this name may be overridden in
+‘<tt>backup-specs</tt>’ using <code>DIRLIST</code> variable.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>DIRLIST</b>
+<a name="IDX268"></a>
+</dt>
+<dd><p>A path to the file containing the list of the file systems to backup
+or restore. By default it is ‘<tt>/etc/backup/dirs</tt>’.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>BACKUP_FILES</b>
+<a name="IDX269"></a>
+</dt>
+<dd><p>A list of individual files to be dumped (for <code>backup</code>), or
restored
+(for <code>restore</code>). These should be accessible from the machine on
+which the backup script is run.
+</p>
+<p>If the list of file systems is very long you may wish to store it
+in a separate file. This file is usually named
+‘<tt>/etc/backup/files</tt>’, but this name may be overridden in
+‘<tt>backup-specs</tt>’ using <code>FILELIST</code> variable.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>FILELIST</b>
+<a name="IDX270"></a>
+</dt>
+<dd><p>A path to the file containing the list of the individual files to backup
+or restore. By default it is ‘<tt>/etc/backup/files</tt>’.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>MT</b>
+<a name="IDX271"></a>
+</dt>
+<dd><p>Full file name of <code>mt</code> binary.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>RSH</b>
+<a name="IDX272"></a>
+</dt>
+<dd><p><a name="RSH"></a>
+Full file name of <code>rsh</code> binary or its equivalent. You may wish to
+set it to <code>ssh</code>, to improve security. In this case you will have
+to use public key authentication.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>RSH_COMMAND</b>
+<a name="IDX273"></a>
+</dt>
+<dd><p>Full file name of <code>rsh</code> binary on remote mashines. This will
+be passed via ‘<samp>--rsh-command</samp>’ option to the remote
invocation
+of <acronym>GNU</acronym> <code>tar</code>.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>VOLNO_FILE</b>
+<a name="IDX274"></a>
+</dt>
+<dd><p>Name of temporary file to hold volume numbers. This needs to be
accessible
+by all the machines which have file systems to be dumped.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>XLIST</b>
+<a name="IDX275"></a>
+</dt>
+<dd><p>Name of <em>exclude file list</em>. An <em>exclude file list</em> 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., ‘<tt>/etc/shadow</tt>’ from backups).
+</p>
+<p>This variable affects only <code>backup</code>.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>SLEEP_TIME</b>
+<a name="IDX276"></a>
+</dt>
+<dd><p>Time to sleep between dumps of any two successive file systems
+</p>
+<p>This variable affects only <code>backup</code>.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>DUMP_REMIND_SCRIPT</b>
+<a name="IDX277"></a>
+</dt>
+<dd><p>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</acronym> <code>tar</code> will
display its built-in
+prompt, and will expect confirmation from the console. For the
+description of the default prompt, see <a href="#change-volume-prompt">change
volume prompt</a>.
+</p>
+</dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>SLEEP_MESSAGE</b>
+<a name="IDX278"></a>
+</dt>
+<dd><p>Message to display on the terminal while waiting for dump time. Usually
+this will just be some literal text.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>TAR</b>
+<a name="IDX279"></a>
+</dt>
+<dd><p>Full file name of the <acronym>GNU</acronym> <code>tar</code>
executable. If this is not set, backup
+scripts will search <code>tar</code> in the current shell path.
+</p></dd></dl>
+
+<hr size="6">
+<a name="Magnetic-Tape-Control"></a>
+<a name="SEC92"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC91" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC93" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC90" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 5.4.2 Magnetic Tape Control </h3>
+
+<p>Backup scripts access tape device using special <em>hook functions</em>.
+These functions take a single argument – the name of the tape
+device. Their names are kept in the following variables:
+</p>
+<dl>
+<dt><u>Backup variable:</u> <b>MT_BEGIN</b>
+<a name="IDX280"></a>
+</dt>
+<dd><p>The name of <em>begin</em> function. This function is called before
+accessing the drive. By default it retensions the tape:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">MT_BEGIN=mt_begin
+
+mt_begin() {
+ mt -f "$1" retension
+}
+</pre></td></tr></table>
+</dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>MT_REWIND</b>
+<a name="IDX281"></a>
+</dt>
+<dd><p>The name of <em>rewind</em> function. The default definition is as
+follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">MT_REWIND=mt_rewind
+
+mt_rewind() {
+ mt -f "$1" rewind
+}
+</pre></td></tr></table>
+
+</dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>MT_OFFLINE</b>
+<a name="IDX282"></a>
+</dt>
+<dd><p>The name of the function switching the tape off line. By default
+it is defined as follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">MT_OFFLINE=mt_offline
+
+mt_offline() {
+ mt -f "$1" offl
+}
+</pre></td></tr></table>
+</dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>MT_STATUS</b>
+<a name="IDX283"></a>
+</dt>
+<dd><p>The name of the function used to obtain the status of the archive
device,
+including error count. Default definition:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">MT_STATUS=mt_status
+
+mt_status() {
+ mt -f "$1" status
+}
+</pre></td></tr></table>
+</dd></dl>
+
+<hr size="6">
+<a name="User-Hooks"></a>
+<a name="SEC93"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC92" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC94" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC90" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 5.4.3 User Hooks </h3>
+
+<p><em>User hooks</em> are shell functions executed before and after
+each <code>tar</code> invocation. Thus, there are <em>backup
+hooks</em>, which are executed before and after dumping each file
+system, and <em>restore hooks</em>, executed before and
+after restoring a file system. Each user hook is a shell function
+taking four arguments:
+</p>
+<dl>
+<dt><u>User Hook Function:</u> <b>hook</b><i> <var>level</var> <var>host</var>
<var>fs</var> <var>fsname</var></i>
+<a name="IDX284"></a>
+</dt>
+<dd><p>Its arguments are:
+</p>
+<dl compact="compact">
+<dt> <var>level</var></dt>
+<dd><p>Current backup or restore level.
+</p>
+</dd>
+<dt> <var>host</var></dt>
+<dd><p>Name or IP address of the host machine being dumped or restored.
+</p>
+</dd>
+<dt> <var>fs</var></dt>
+<dd><p>Full path name to the file system being dumped or restored.
+</p>
+</dd>
+<dt> <var>fsname</var></dt>
+<dd><p>File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
+</p></dd>
+</dl>
+</dd></dl>
+
+<p>Following variables keep the names of user hook functions
+</p>
+<dl>
+<dt><u>Backup variable:</u> <b>DUMP_BEGIN</b>
+<a name="IDX285"></a>
+</dt>
+<dd><p>Dump begin function. It is executed before dumping the file system.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>DUMP_END</b>
+<a name="IDX286"></a>
+</dt>
+<dd><p>Executed after dumping the file system.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>RESTORE_BEGIN</b>
+<a name="IDX287"></a>
+</dt>
+<dd><p>Executed before restoring the file system.
+</p></dd></dl>
+
+<dl>
+<dt><u>Backup variable:</u> <b>RESTORE_END</b>
+<a name="IDX288"></a>
+</dt>
+<dd><p>Executed after restoring the file system.
+</p></dd></dl>
+
+<hr size="6">
+<a name="backup_002dspecs-example"></a>
+<a name="SEC94"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC93" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC95" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC90" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 5.4.4 An Example Text of
‘<tt>Backup-specs</tt>’ </h3>
+
+<p>The following is an example of ‘<tt>backup-specs</tt>’:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"># site-specific
parameters for file system backup.
+
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
+
+# Use <code>ssh</code> instead of the less secure <code>rsh</code>
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
+
+# Override MT_STATUS function:
+my_status() {
+ mts -t $TAPE_FILE
+}
+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]"
+
+</pre></td></tr></table>
+
+<hr size="6">
+<a name="Scripted-Backups"></a>
+<a name="SEC95"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC94" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC96" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 5.5 Using the Backup Scripts </h2>
+
+<p>The syntax for running a backup script is:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">backup
--level=<var>level</var> --time=<var>time</var>
+</pre></td></tr></table>
+
+<p>The ‘<samp>level</samp>’ option requests the dump level. Thus,
to produce
+a full dump, specify <code>--level=0</code> (this is the default, so
+‘<samp>--level</samp>’ may be omitted if its value is
<code>0</code>).
+<a name="DOCF14" href="#FOOT14">(14)</a>
+</p>
+<p>The ‘<samp>--time</samp>’ option determines when should the
backup be
+run. <var>Time</var> may take three forms:
+</p>
+<dl compact="compact">
+<dt> <var>hh</var>:<var>mm</var></dt>
+<dd>
+<p>The dump must be run at <var>hh</var> hours <var>mm</var> minutes.
+</p>
+</dd>
+<dt> <var>hh</var></dt>
+<dd>
+<p>The dump must be run at <var>hh</var> hours
+</p>
+</dd>
+<dt> now</dt>
+<dd>
+<p>The dump must be run immediately.
+</p></dd>
+</dl>
+
+<p>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</code> 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 (see section <a
href="#SEC96">Using the Restore Script</a>).
+</p>
+<p>The backup scripts write two files on the file system. The first is a
+record file in ‘<tt>/etc/tar-backup/</tt>’, 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. See section <a href="#SEC169">Format of the Incremental Snapshot
Files</a>, for a more detailed explanation of this
+file.
+</p>
+<p>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
+‘<tt>log-<var>mm-dd-yyyy</var>-level-<var>n</var></tt>’, where
<var>mm-dd-yyyy</var>
+represents current date, and <var>n</var> represents current dump level number.
+</p>
+<p>The script also prints the name of each system being dumped to the
+standard output.
+</p>
+<p>Following is the full list of options accepted by <code>backup</code>
+script:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>-l <var>level</var></samp>’</dt>
+<dt> ‘<samp>--level=<var>level</var></samp>’</dt>
+<dd><p>Do backup level <var>level</var> (default 0).
+</p>
+</dd>
+<dt> ‘<samp>-f</samp>’</dt>
+<dt> ‘<samp>--force</samp>’</dt>
+<dd><p>Force backup even if today's log file already exists.
+</p>
+</dd>
+<dt> ‘<samp>-v[<var>level</var>]</samp>’</dt>
+<dt> ‘<samp>--verbose[=<var>level</var>]</samp>’</dt>
+<dd><p>Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault <var>level</var>
+is 100, which means the highest debugging level.
+</p>
+</dd>
+<dt> ‘<samp>-t <var>start-time</var></samp>’</dt>
+<dt> ‘<samp>--time=<var>start-time</var></samp>’</dt>
+<dd><p>Wait till <var>time</var>, then do backup.
+</p>
+</dd>
+<dt> ‘<samp>-h</samp>’</dt>
+<dt> ‘<samp>--help</samp>’</dt>
+<dd><p>Display short help message and exit.
+</p>
+</dd>
+<dt> ‘<samp>-V</samp>’</dt>
+<dt> ‘<samp>--version</samp>’</dt>
+<dd><p>Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+</p></dd>
+</dl>
+
+
+<hr size="6">
+<a name="Scripted-Restoration"></a>
+<a name="SEC96"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC95" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 5.6 Using the Restore Script </h2>
+
+<p>To restore files that were archived using a scripted backup, use the
+<code>restore</code> script. Its usage is quite straightforward. In the
+simplest form, invoke <code>restore --all</code>, it will
+then restore all the file systems and files specified in
+‘<tt>backup-specs</tt>’ (see section <a
href="#SEC91">BACKUP_DIRS</a>).
+</p>
+<p>You may select the file systems (and/or files) to restore by
+giving <code>restore</code> list of <em>patterns</em> in its command
+line. For example, running
+</p>
+<table><tr><td> </td><td><pre class="smallexample">restore 'albert:*'
+</pre></td></tr></table>
+
+<p>will restore all file systems on the machine
‘<samp>albert</samp>’. A more
+complicated example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">restore 'albert:*'
'*:/var'
+</pre></td></tr></table>
+
+<p>This command will restore all file systems on the machine
‘<samp>albert</samp>’
+as well as ‘<tt>/var</tt>’ file system on all machines.
+</p>
+<p>By default <code>restore</code> 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 ‘<samp>--level</samp>’ option, as shown in the example below:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">restore --level=1
+</pre></td></tr></table>
+
+<p>The full list of options accepted by <code>restore</code> follows:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>-a</samp>’</dt>
+<dt> ‘<samp>--all</samp>’</dt>
+<dd><p>Restore all file systems and files specified in
‘<tt>backup-specs</tt>’
+</p>
+</dd>
+<dt> ‘<samp>-l <var>level</var></samp>’</dt>
+<dt> ‘<samp>--level=<var>level</var></samp>’</dt>
+<dd><p>Start restoring from the given backup level, instead of the default 0.
+</p>
+</dd>
+<dt> ‘<samp>-v[<var>level</var>]</samp>’</dt>
+<dt> ‘<samp>--verbose[=<var>level</var>]</samp>’</dt>
+<dd><p>Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault <var>level</var>
+is 100, which means the highest debugging level.
+</p>
+</dd>
+<dt> ‘<samp>-h</samp>’</dt>
+<dt> ‘<samp>--help</samp>’</dt>
+<dd><p>Display short help message and exit.
+</p>
+</dd>
+<dt> ‘<samp>-V</samp>’</dt>
+<dt> ‘<samp>--version</samp>’</dt>
+<dd><p>Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+</p></dd>
+</dl>
+
+<p>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. See section <a href="#SEC151">Tape Positions and Tape
Marks</a>, for a discussion of tape
+positioning.
+</p>
+<blockquote><p><strong>Warning:</strong> The script will delete files from the
active file
+system if they were not in the file system when the archive was made.
+</p></blockquote>
+
+<p>See section <a href="#SEC88">Using <code>tar</code> to Perform Incremental
Dumps</a>, for an explanation of how the script makes
+that determination.
+</p>
+<hr size="6">
+<a name="Choosing"></a>
+<a name="SEC97"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC96" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC98" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 6. Choosing Files and Names for <code>tar</code> </h1>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>Certain options to <code>tar</code> 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.
+</p>
+<p>This chapter discusses these options in detail.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC98">6.1 Choosing and Naming
Archive Files</a></td><td> </td><td align="left" valign="top">
Choosing the Archive's Name
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC99">6.2 Selecting Archive
Members</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC100">6.3 Reading Names from a
File</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC102">6.4 Excluding Some
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC104">6.5 Wildcards Patterns and
Matching</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC106">6.6 Quoting Member
Names</a></td><td> </td><td align="left" valign="top">
Ways of Quoting Special Characters in Names
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC107">6.7 Modifying File and
Member Names</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC108">6.8 Operating Only on New
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC109">6.9 Descending into
Directories</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC110">6.10 Crossing File System
Boundaries</a></td><td> </td><td align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="file"></a>
+<a name="SEC98"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC97" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC99" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.1 Choosing and Naming Archive Files </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX289"></a>
+<a name="IDX290"></a>
+<a name="IDX291"></a>
+<a name="IDX292"></a>
+<p>By default, <code>tar</code> 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 <code>tar</code>
+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
+<code>tar</code> where to find (or create) the archive. The
+‘<samp>--file=<var>archive-name</var></samp>’ (‘<samp>-f
<var>archive-name</var></samp>’)
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
+</p>
+<dl compact="compact">
+<dd><a name="IDX293"></a>
+</dd>
+<dt> ‘<samp>--file=<var>archive-name</var></samp>’</dt>
+<dt> ‘<samp>-f <var>archive-name</var></samp>’</dt>
+<dd><p>Name the archive to create or operate on. Use in conjunction with
+any operation.
+</p></dd>
+</dl>
+
+<p>For example, in this <code>tar</code> command,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cvf
collection.tar blues folk jazz</kbd>
+</pre></td></tr></table>
+
+<p>‘<tt>collection.tar</tt>’ is the name of the archive. It must
directly
+follow the ‘<samp>-f</samp>’ option, since whatever directly
follows ‘<samp>-f</samp>’
+<em>will</em> 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 <code>tar</code> will use this file's name
+for the archive name.
+</p>
+<p>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.
+</p>
+<a name="IDX294"></a>
+<a name="IDX295"></a>
+<p>If you do not name the archive, <code>tar</code> uses the value of the
+environment variable <code>TAPE</code> as the file name for the archive. If
+that is not available, <code>tar</code> uses a default, compiled-in archive
+name, usually that for tape unit zero (i.e. ‘<tt>/dev/tu00</tt>’).
+</p>
+<a name="IDX296"></a>
+<a name="IDX297"></a>
+<p>If you use ‘<tt>-</tt>’ as an <var>archive-name</var>,
<code>tar</code> reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
+‘<tt>-</tt>’ as an <var>archive-name</var> when modifying an
archive,
+<code>tar</code> reads the original archive from its standard input and
+writes the entire new archive to its standard output.
+</p>
+<p>The following example is a convenient way of copying directory
+hierarchy from ‘<tt>sourcedir</tt>’ to
‘<tt>targetdir</tt>’.
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>(cd sourcedir;
tar -cf - .) | (cd targetdir; tar -xpf -)</kbd>
+</pre></td></tr></table>
+
+<p>The ‘<samp>-C</samp>’ option allows to avoid using subshells:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -C
sourcedir -cf - . | tar -C targetdir -xpf -</kbd>
+</pre></td></tr></table>
+
+<p>In both examples above, the leftmost <code>tar</code> invocation archives
+the contents of ‘<tt>sourcedir</tt>’ to the standard output, while
the
+rightmost one reads this archive from its standard input and
+extracts it. The ‘<samp>-p</samp>’ option tells it to restore
permissions
+of the extracted files.
+</p>
+<a name="IDX298"></a>
+<a name="IDX299"></a>
+<p><a name="remote_002ddev"></a>
+To specify an archive file on a device attached to a remote machine,
+use the following:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample"><kbd>--file=<var>hostname</var>:/<var>dev</var>/<var>file-name</var></kbd>
+</pre></td></tr></table>
+
+<p><code>tar</code> will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
+‘<samp>--file=@<var>hostname</var>:/<var>dev</var>/<var>file-name</var></samp>’,
<code>tar</code>
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
+</p>
+<a name="IDX300"></a>
+<p><a name="local-and-remote-archives"></a>
+If the archive file name includes a colon (‘<samp>:</samp>’), then
it is assumed
+to be a file on another machine. If the archive file is
+‘<samp><var>user</var>@<var>host</var>:<var>file</var></samp>’,
then <var>file</var> is used on the
+host <var>host</var>. The remote host is accessed using the <code>rsh</code>
+program, with a username of <var>user</var>. If the username is omitted
+(along with the ‘<samp>@</samp>’ sign), then your user name will
be used.
+(This is the normal <code>rsh</code> behavior.) It is necessary for the
+remote machine, in addition to permitting your <code>rsh</code> access, to
+have the ‘<tt>rmt</tt>’ program installed (This command is
included in
+the <acronym>GNU</acronym> <code>tar</code> distribution and by default is
installed under
+‘<tt><var>prefix</var>/libexec/rmt</tt>’, were <var>prefix</var>
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 ‘<samp>--force-local</samp>’ option.
+</p>
+<p>When the archive is being created to ‘<tt>/dev/null</tt>’,
<acronym>GNU</acronym> <code>tar</code>
+tries to minimize input and output operations. The Amanda backup
+system, when used with <acronym>GNU</acronym> <code>tar</code>, has an initial
sizing pass which
+uses this feature.
+</p>
+<hr size="6">
+<a name="Selecting-Archive-Members"></a>
+<a name="SEC99"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC98" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC100" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.2 Selecting Archive Members </h2>
+
+<p><em>File Name arguments</em> specify which files in the file system
+<code>tar</code> operates on, when creating or adding to an archive, or which
+archive members <code>tar</code> operates on, when reading or deleting from
+an archive. See section <a href="#SEC51">The Five Advanced <code>tar</code>
Operations</a>.
+</p>
+<p>To specify file names, you can include them as the last arguments on
+the command line, as follows:
+</p><table><tr><td> </td><td><pre class="smallexample"><kbd>tar</kbd>
<var>operation</var> [<var>option1</var> <var>option2</var> …]
[<var>file name-1</var> <var>file name-2</var> …]
+</pre></td></tr></table>
+
+<p>If a file name begins with dash (‘<samp>-</samp>’), precede it
with
+‘<samp>--add-file</samp>’ option to prevent it from being treated
as an
+option.
+</p>
+<p><a name="input-name-quoting"></a>
+By default <acronym>GNU</acronym> <code>tar</code> attempts to
<em>unquote</em> each file or member
+name, replacing <em>escape sequences</em> according to the following
+table:
+</p>
+<table>
+<thead><tr><th><p> Escape </p></th><th><p> Replaced with
+</p></th></tr></thead>
+<tr><td><p> \a </p></td><td><p> Audible bell (ASCII 7)
+</p></td></tr>
+<tr><td><p> \b </p></td><td><p> Backspace (ASCII 8)
+</p></td></tr>
+<tr><td><p> \f </p></td><td><p> Form feed (ASCII 12)
+</p></td></tr>
+<tr><td><p> \n </p></td><td><p> New line (ASCII 10)
+</p></td></tr>
+<tr><td><p> \r </p></td><td><p> Carriage return (ASCII 13)
+</p></td></tr>
+<tr><td><p> \t </p></td><td><p> Horizontal tabulation (ASCII 9)
+</p></td></tr>
+<tr><td><p> \v </p></td><td><p> Vertical tabulation (ASCII 11)
+</p></td></tr>
+<tr><td><p> \? </p></td><td><p> ASCII 127
+</p></td></tr>
+<tr><td><p> \<var>n</var> </p></td><td><p> ASCII <var>n</var> (<var>n</var>
should be an octal number
+ of up to 3 digits)
+</p></td></tr>
+</table>
+
+<p>A backslash followed by any other symbol is retained.
+</p>
+<p>This default behavior is controlled by the following command line
+option:
+</p>
+<dl compact="compact">
+<dd><a name="IDX301"></a>
+</dd>
+<dt> ‘<samp>--unquote</samp>’</dt>
+<dd><p>Enable unquoting input file or member names (default).
+</p>
+<a name="IDX302"></a>
+</dd>
+<dt> ‘<samp>--no-unquote</samp>’</dt>
+<dd><p>Disable unquoting input file or member names.
+</p></dd>
+</dl>
+
+<p>If you specify a directory name as a file name argument, all the files
+in that directory are operated on by <code>tar</code>.
+</p>
+<p>If you do not specify files, <code>tar</code> behavior differs depending
+on the operation mode as described below:
+</p>
+<p>When <code>tar</code> is invoked with ‘<samp>--create</samp>’
(‘<samp>-c</samp>’),
+<code>tar</code> will stop immediately, reporting the following:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cf
a.tar</kbd>
+tar: Cowardly refusing to create an empty archive
+Try `tar --help' or `tar --usage' for more information.
+</pre></td></tr></table>
+
+<p>If you specify either ‘<samp>--list</samp>’
(‘<samp>-t</samp>’) or
+‘<samp>--extract</samp>’ (‘<samp>--get</samp>’,
‘<samp>-x</samp>’), <code>tar</code>
+operates on all the archive members in the archive.
+</p>
+<p>If run with ‘<samp>--diff</samp>’ option, tar will compare the
archive with
+the contents of the current working directory.
+</p>
+<p>If you specify any other operation, <code>tar</code> does nothing.
+</p>
+<p>By default, <code>tar</code> 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 <code>tar</code> selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
+</p>
+<hr size="6">
+<a name="files"></a>
+<a name="SEC100"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC99" title="Previous section
in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC101" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.3 Reading Names from a File </h2>
+
+<p>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
+‘<samp>--files-from=<var>file-of-names</var></samp>’
(‘<samp>-T
+<var>file-of-names</var></samp>’) option to <code>tar</code>. Give the
name of the
+file which contains the list of files to include as the argument to
+‘<samp>--files-from</samp>’. 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 <code>find</code> utility.
+</p>
+<dl compact="compact">
+<dd><a name="IDX303"></a>
+</dd>
+<dt> ‘<samp>--files-from=<var>file-name</var></samp>’</dt>
+<dt> ‘<samp>-T <var>file-name</var></samp>’</dt>
+<dd><p>Get names to extract or create from file <var>file-name</var>.
+</p></dd>
+</dl>
+
+<p>If you give a single dash as a file name for
‘<samp>--files-from</samp>’, (i.e.,
+you specify either <code>--files-from=-</code> or <code>-T -</code>), then the
file
+names are read from standard input.
+</p>
+<p>Unless you are running <code>tar</code> with
‘<samp>--create</samp>’, you can not use
+both <code>--files-from=-</code> and <code>--file=-</code> (<code>-f -</code>)
in the same
+command.
+</p>
+<p>Any number of ‘<samp>-T</samp>’ options can be given in the
command line.
+</p>
+<p>The following example shows how to use <code>find</code> to generate a list
of
+files smaller than 400K in length and put that list into a file
+called ‘<tt>small-files</tt>’. You can then use the
‘<samp>-T</samp>’ option to
+<code>tar</code> to specify the files from that file,
‘<tt>small-files</tt>’, to
+create the archive ‘<tt>little.tgz</tt>’. (The
‘<samp>-z</samp>’ option to
+<code>tar</code> compresses the archive with <code>gzip</code>; see section <a
href="#SEC126">Creating and Reading Compressed Archives</a> for
+more information.)
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>find . -size
-400 -print > small-files</kbd>
+$ <kbd>tar -c -v -z -T small-files -f little.tgz</kbd>
+</pre></td></tr></table>
+
+<p>In the file list given by ‘<samp>-T</samp>’ option, any file
name beginning
+with ‘<samp>-</samp>’ character is considered a <code>tar</code>
option and is
+processed accordingly.<a name="DOCF15" href="#FOOT15">(15)</a> For example,
+the common use of this feature is to change to another directory by
+specifying ‘<samp>-C</samp>’ option:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>cat list</kbd>
+-C/etc
+passwd
+hosts
+-C/lib
+libc.a
+$ <kbd>tar -c -f foo.tar --files-from list</kbd>
+</pre></td></tr></table>
+
+<p>In this example, <code>tar</code> will first switch to
‘<tt>/etc</tt>’
+directory and add files ‘<tt>passwd</tt>’ and
‘<tt>hosts</tt>’ to the
+archive. Then it will change to ‘<tt>/lib</tt>’ directory and
will archive
+the file ‘<tt>libc.a</tt>’. Thus, the resulting archive
‘<tt>foo.tar</tt>’ will
+contain:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf
foo.tar</kbd>
+passwd
+hosts
+libc.a
+</pre></td></tr></table>
+
+<a name="IDX304"></a>
+<p>Notice that the option parsing algorithm used with
‘<samp>-T</samp>’ is
+stricter than the one used by shell. Namely, when specifying option
+arguments, you should observe the following rules:
+</p>
+<ul>
+<li>
+When using short (single-letter) option form, its argument must
+immediately follow the option letter, without any intervening
+whitespace. For example: <code>-Cdir</code>.
+
+</li><li>
+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</code>.
+
+</li><li>
+For both short and long option forms, the option argument can be given
+on the next line after the option name, e.g.:
+
+<table><tr><td> </td><td><pre class="smallexample">--directory
+dir
+</pre></td></tr></table>
+
+<p>and
+</p>
+<table><tr><td> </td><td><pre class="smallexample">-C
+dir
+</pre></td></tr></table>
+</li></ul>
+
+<a name="IDX305"></a>
+<p>If you happen to have a file whose name starts with
‘<samp>-</samp>’,
+precede it with ‘<samp>--add-file</samp>’ option to prevent it from
+being recognized as an option. For example: <code>--add-file=--my-file</code>.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC101">6.3.1 <code>NUL</code>
Terminated File Names</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="nul"></a>
+<a name="SEC101"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC100" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC102" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC100" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 6.3.1 <code>NUL</code> Terminated File Names </h3>
+
+<p>The ‘<samp>--null</samp>’ option causes
+‘<samp>--files-from=<var>file-of-names</var></samp>’
(‘<samp>-T <var>file-of-names</var></samp>’)
+to read file names terminated by a <code>NUL</code> instead of a newline, so
+files whose names contain newlines can be archived using
+‘<samp>--files-from</samp>’.
+</p>
+<dl compact="compact">
+<dd><a name="IDX306"></a>
+</dd>
+<dt> ‘<samp>--null</samp>’</dt>
+<dd><p>Only consider <code>NUL</code> terminated file names, instead of files
that
+terminate in a newline.
+</p></dd>
+</dl>
+
+<p>The ‘<samp>--null</samp>’ option is just like the one in
<acronym>GNU</acronym>
+<code>xargs</code> and <code>cpio</code>, and is useful with the
+‘<samp>-print0</samp>’ predicate of <acronym>GNU</acronym>
<code>find</code>. In
+<code>tar</code>, ‘<samp>--null</samp>’ also disables special
handling for
+file names that begin with dash.
+</p>
+<p>This example shows how to use <code>find</code> to generate a list of files
+larger than 800K in length and put that list into a file called
+‘<tt>long-files</tt>’. The ‘<samp>-print0</samp>’
option to <code>find</code> is just
+like ‘<samp>-print</samp>’, except that it separates files with a
<code>NUL</code>
+rather than with a newline. You can then run <code>tar</code> with both the
+‘<samp>--null</samp>’ and ‘<samp>-T</samp>’ options to
specify that <code>tar</code> get the
+files from that file, ‘<tt>long-files</tt>’, to create the archive
+‘<tt>big.tgz</tt>’. The ‘<samp>--null</samp>’ option
to <code>tar</code> will cause
+<code>tar</code> to recognize the <code>NUL</code> separator between files.
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>find . -size
+800 -print0 > long-files</kbd>
+$ <kbd>tar -c -v --null --files-from=long-files --file=big.tar</kbd>
+</pre></td></tr></table>
+
+
+
+
+
+<hr size="6">
+<a name="exclude"></a>
+<a name="SEC102"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC101" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC103" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.4 Excluding Some Files </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX307"></a>
+<a name="IDX308"></a>
+<a name="IDX309"></a>
+<p>To avoid operating on files whose names match a particular pattern,
+use the ‘<samp>--exclude</samp>’ or
‘<samp>--exclude-from</samp>’ options.
+</p>
+<dl compact="compact">
+<dd><a name="IDX310"></a>
+</dd>
+<dt> ‘<samp>--exclude=<var>pattern</var></samp>’</dt>
+<dd><p>Causes <code>tar</code> to ignore files that match the
<var>pattern</var>.
+</p></dd>
+</dl>
+
+<a name="IDX311"></a>
+<p>The ‘<samp>--exclude=<var>pattern</var></samp>’ option prevents
any file or
+member whose name matches the shell wildcard (<var>pattern</var>) from
+being operated on.
+For example, to create an archive with all the contents of the directory
+‘<tt>src</tt>’ except for files whose names end in
‘<tt>.o</tt>’, use the
+command ‘<samp>tar -cf src.tar --exclude='*.o' src</samp>’.
+</p>
+<p>You may give multiple ‘<samp>--exclude</samp>’ options.
+</p>
+<dl compact="compact">
+<dd><a name="IDX312"></a>
+</dd>
+<dt> ‘<samp>--exclude-from=<var>file</var></samp>’</dt>
+<dt> ‘<samp>-X <var>file</var></samp>’</dt>
+<dd><p>Causes <code>tar</code> to ignore files that match the patterns listed
in
+<var>file</var>.
+</p></dd>
+</dl>
+
+<a name="IDX313"></a>
+<p>Use the ‘<samp>--exclude-from</samp>’ option to read a
+list of patterns, one per line, from <var>file</var>; <code>tar</code> will
+ignore files matching those patterns. Thus if <code>tar</code> is
+called as ‘<samp>tar -c -X foo .</samp>’ and the file
‘<tt>foo</tt>’ contains a
+single line ‘<tt>*.o</tt>’, no files whose names end in
‘<tt>.o</tt>’ will be
+added to the archive.
+</p>
+<dl compact="compact">
+<dd><a name="IDX314"></a>
+</dd>
+<dt> ‘<samp>--exclude-caches</samp>’</dt>
+<dd><p>Causes <code>tar</code> to ignore directories containing a cache
directory tag.
+</p></dd>
+</dl>
+
+<a name="IDX315"></a>
+<p>When creating an archive, the ‘<samp>--exclude-caches</samp>’
option causes
+<code>tar</code> to exclude all directories that contain a <em>cache
+directory tag</em>. A cache directory tag is a short file with the
+well-known name ‘<tt>CACHEDIR.TAG</tt>’ and having a standard
header
+specified in <a
href="http://www.brynosaurus.com/cachedir/spec.html";>http://www.brynosaurus.com/cachedir/spec.html</a>.
+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.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC103">Problems with Using the
<code>exclude</code> Options</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="problems-with-exclude"></a>
+<a name="SEC103"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC102" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC104" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC102" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="unnumberedsubsec"> Problems with Using the <code>exclude</code>
Options </h3>
+
+<p>Some users find ‘<samp>exclude</samp>’ options confusing. Here
are some common
+pitfalls:
+</p>
+<ul>
+<li>
+The main operating mode of <code>tar</code> 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</samp>’, but
+explicitly name the file ‘<samp>dir.o/foo</samp>’ after all the
options have been
+listed, ‘<samp>dir.o/foo</samp>’ will be excluded from the archive.
+
+</li><li>
+You can sometimes confuse the meanings of ‘<samp>--exclude</samp>’
and
+‘<samp>--exclude-from</samp>’. Be careful: use
‘<samp>--exclude</samp>’ when files
+to be excluded are given as a pattern on the command line. Use
+‘<samp>--exclude-from</samp>’ 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.
+
+</li><li>
+When you use ‘<samp>--exclude=<var>pattern</var></samp>’, be sure
to quote the
+<var>pattern</var> parameter, so <acronym>GNU</acronym> <code>tar</code> sees
wildcard characters
+like ‘<samp>*</samp>’. If you do not do this, the shell might
expand the
+‘<samp>*</samp>’ itself using files at hand, so <code>tar</code>
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.
+
+<p>For example, write:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
<var>archive.tar</var> --exclude '*.o' <var>directory</var></kbd>
+</pre></td></tr></table>
+
+<p>rather than:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"># <em>Wrong!</em>
+$ <kbd>tar -c -f <var>archive.tar</var> --exclude *.o
<var>directory</var></kbd>
+</pre></td></tr></table>
+
+</li><li>
+You must use use shell syntax, or globbing, rather than <code>regexp</code>
+syntax, when using exclude options in <code>tar</code>. If you try to use
+<code>regexp</code> syntax to describe files to be excluded, your command
+might fail.
+
+</li><li>
+
+
+
+In earlier versions of <code>tar</code>, what is now the
+‘<samp>--exclude-from</samp>’ option was called
‘<samp>--exclude</samp>’ instead.
+Now, ‘<samp>--exclude</samp>’ applies to patterns listed on the
command
+line and ‘<samp>--exclude-from</samp>’ applies to patterns listed
in a
+file.
+
+</li></ul>
+
+<hr size="6">
+<a name="wildcards"></a>
+<a name="SEC104"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC103" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC105" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.5 Wildcards Patterns and Matching </h2>
+
+<p><em>Globbing</em> is the operation by which <em>wildcard</em> characters,
+‘<samp>*</samp>’ or ‘<samp>?</samp>’ for example, are
replaced and expanded into all
+existing files matching the given pattern. <acronym>GNU</acronym>
<code>tar</code> 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 <code>tar</code> archives. This section has the
+purpose of explaining wildcard syntax for <code>tar</code>.
+</p>
+
+
+
+
+<p>A <var>pattern</var> 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</samp>’
+will match only ‘<samp>a</samp>’, and not
‘<samp>A</samp>’. The character ‘<samp>?</samp>’ in the
+pattern matches any single character in the matched string. The character
+‘<samp>*</samp>’ in the pattern matches zero, one, or more single
characters in
+the matched string. The character ‘<samp>\</samp>’ says to take
the following
+character of the pattern <em>literally</em>; it is useful when one needs to
+match the ‘<samp>?</samp>’, ‘<samp>*</samp>’,
‘<samp>[</samp>’ or ‘<samp>\</samp>’ characters,
themselves.
+</p>
+<p>The character ‘<samp>[</samp>’, up to the matching
‘<samp>]</samp>’, introduces a character
+class. A <em>character class</em> is a list of acceptable characters
+for the next single character of the matched string. For example,
+‘<samp>[abcde]</samp>’ 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>\</samp>’ lose their special
meaning; for example,
+‘<samp>[-\\[*?]]</samp>’ would match any of the characters,
‘<samp>-</samp>’, ‘<samp>\</samp>’,
+‘<samp>[</samp>’, ‘<samp>*</samp>’,
‘<samp>?</samp>’, or ‘<samp>]</samp>’. (Due to parsing
constraints,
+the characters ‘<samp>-</samp>’ and ‘<samp>]</samp>’
must either come <em>first</em> or
+<em>last</em> in a character class.)
+</p>
+<a name="IDX316"></a>
+<a name="IDX317"></a>
+<p>If the first character of the class after the opening
‘<samp>[</samp>’
+is ‘<samp>!</samp>’ or ‘<samp>^</samp>’, then the
meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are <em>forbidden</em> as the next single character of the matched string.
+</p>
+<p>Other characters of the class stand for themselves. The special
+construction ‘<samp>[<var>a</var>-<var>e</var>]</samp>’, using an
hyphen between two
+letters, is meant to represent all characters between <var>a</var> and
+<var>e</var>, inclusive.
+</p>
+
+
+
+
+<p>Periods (‘<samp>.</samp>’) or forward slashes
(‘<samp>/</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.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC105">Controlling
Pattern-Matching</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="controlling-pattern_002dmatching"></a>
+<a name="SEC105"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC104" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC106" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC104" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="unnumberedsubsec"> Controlling Pattern-Matching </h3>
+
+<p>For the purposes of this section, we call <em>exclusion members</em> all
+member names obtained while processing ‘<samp>--exclude</samp>’ and
+‘<samp>--exclude-from</samp>’ options, and <em>inclusion
members</em> those
+member names that were given in the command line or read from the file
+specified with ‘<samp>--files-from</samp>’ option.
+</p>
+<p>These two pairs of member lists are used in the following operations:
+‘<samp>--diff</samp>’, ‘<samp>--extract</samp>’,
‘<samp>--list</samp>’,
+‘<samp>--update</samp>’.
+</p>
+<p>There are no inclusion members in create mode
(‘<samp>--create</samp>’ and
+‘<samp>--append</samp>’), since in this mode the names obtained
from the
+command line refer to <em>files</em>, not archive members.
+</p>
+<p>By default, inclusion members are compared with archive members
+literally <a name="DOCF16" href="#FOOT16">(16)</a> and exclusion members are
+treated as globbing patterns. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf
foo.tar</kbd>
+a.c
+b.c
+a.txt
+[remarks]
+# <i>Member names are used verbatim:</i>
+$ <kbd>tar -xf foo.tar -v '[remarks]'</kbd>
+[remarks]
+# <i>Exclude member names are globbed:</i>
+$ <kbd>tar -xf foo.tar -v --exclude '*.c'</kbd>
+a.txt
+[remarks]
+</pre></td></tr></table>
+
+<p>This behavior can be altered by using the following options:
+</p>
+<dl compact="compact">
+<dd><a name="IDX318"></a>
+</dd>
+<dt> ‘<samp>--wildcards</samp>’</dt>
+<dd><p>Treat all member names as wildcards.
+</p>
+<a name="IDX319"></a>
+</dd>
+<dt> ‘<samp>--no-wildcards</samp>’</dt>
+<dd><p>Treat all member names as literal strings.
+</p></dd>
+</dl>
+
+<p>Thus, to extract files whose names end in ‘<samp>.c</samp>’,
you can use:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -xf foo.tar
-v --wildcards '*.c'</kbd>
+a.c
+b.c
+</pre></td></tr></table>
+
+<p>Notice quoting of the pattern to prevent the shell from interpreting
+it.
+</p>
+<p>The effect of ‘<samp>--wildcards</samp>’ option is cancelled by
+‘<samp>--no-wildcards</samp>’. This can be used to pass part of
+the command line arguments verbatim and other part as globbing
+patterns. For example, the following invocation:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -xf foo.tar
--wildcards '*.txt' --no-wildcards '[remarks]'</kbd>
+</pre></td></tr></table>
+
+<p>instructs <code>tar</code> to extract from ‘<tt>foo.tar</tt>’
all files whose
+names end in ‘<samp>.txt</samp>’ and the file named
‘<tt>[remarks]</tt>’.
+</p>
+<p>Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where ‘<samp>*</samp>’,
‘<samp>?</samp>’, and
+‘<samp>[...]</samp>’ are the usual shell wildcards,
‘<samp>\</samp>’ escapes wildcards,
+and wildcards can match ‘<samp>/</samp>’.
+</p>
+<p>Other than optionally stripping leading ‘<samp>/</samp>’ from
names
+(see section <a href="#SEC112">Absolute File Names</a>), patterns and names
are used as-is. For
+example, trailing ‘<samp>/</samp>’ is not trimmed from a
user-specified name
+before deciding whether to exclude it.
+</p>
+<p>However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">--ignore-case
--exclude='makefile' --no-ignore-case ---exclude='readme'
+</pre></td></tr></table>
+
+<p>ignores case when excluding ‘<samp>makefile</samp>’, but not
when excluding
+‘<samp>readme</samp>’.
+</p>
+<dl compact="compact">
+<dd><a name="IDX320"></a>
+<a name="IDX321"></a>
+</dd>
+<dt> ‘<samp>--anchored</samp>’</dt>
+<dt> ‘<samp>--no-anchored</samp>’</dt>
+<dd><p>If anchored, a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any
+subsequence. Default is ‘<samp>--no-anchored</samp>’ for
exclusion members
+and ‘<samp>--anchored</samp>’ inclusion members.
+</p>
+<a name="IDX322"></a>
+<a name="IDX323"></a>
+</dd>
+<dt> ‘<samp>--ignore-case</samp>’</dt>
+<dt> ‘<samp>--no-ignore-case</samp>’</dt>
+<dd><p>When ignoring case, upper-case patterns match lower-case names and vice
versa.
+When not ignoring case (the default), matching is case-sensitive.
+</p>
+<a name="IDX324"></a>
+<a name="IDX325"></a>
+</dd>
+<dt> ‘<samp>--wildcards-match-slash</samp>’</dt>
+<dt> ‘<samp>--no-wildcards-match-slash</samp>’</dt>
+<dd><p>When wildcards match slash (the default for exclusion members), a
+wildcard like ‘<samp>*</samp>’ in the pattern can match a
‘<samp>/</samp>’ in the
+name. Otherwise, ‘<samp>/</samp>’ is matched only by
‘<samp>/</samp>’.
+</p>
+</dd>
+</dl>
+
+<p>The ‘<samp>--recursion</samp>’ and
‘<samp>--no-recursion</samp>’ options
+(see section <a href="#SEC109">Descending into Directories</a>) 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.
+</p>
+<p>The following table summarizes pattern-matching default values:
+</p>
+<table>
+<thead><tr><th><p> Members </p></th><th><p> Default settings
+</p></th></tr></thead>
+<tr><td><p> Inclusion </p></td><td><p> ‘<samp>--no-wildcards --anchored
--no-wildcards-match-slash</samp>’
+</p></td></tr>
+<tr><td><p> Exclusion </p></td><td><p> ‘<samp>--wildcards --no-anchored
--wildcards-match-slash</samp>’
+</p></td></tr>
+</table>
+
+<hr size="6">
+<a name="quoting-styles"></a>
+<a name="SEC106"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC105" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC107" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.6 Quoting Member Names </h2>
+
+<p>When displaying member names, <code>tar</code> takes care to avoid
+ambiguities caused by certain characters. This is called <em>name
+quoting</em>. The characters in question are:
+</p>
+<ul>
+<li> Non-printable control characters:
+
+<table>
+<thead><tr><th><p> Character </p></th><th><p> ASCII </p></th><th><p> Character
name
+</p></th></tr></thead>
+<tr><td><p> \a </p></td><td><p> 7 </p></td><td><p> Audible bell
+</p></td></tr>
+<tr><td><p> \b </p></td><td><p> 8 </p></td><td><p> Backspace
+</p></td></tr>
+<tr><td><p> \f </p></td><td><p> 12 </p></td><td><p> Form feed
+</p></td></tr>
+<tr><td><p> \n </p></td><td><p> 10 </p></td><td><p> New line
+</p></td></tr>
+<tr><td><p> \r </p></td><td><p> 13 </p></td><td><p> Carriage return
+</p></td></tr>
+<tr><td><p> \t </p></td><td><p> 9 </p></td><td><p> Horizontal tabulation
+</p></td></tr>
+<tr><td><p> \v </p></td><td><p> 11 </p></td><td><p> Vertical tabulation
+</p></td></tr>
+</table>
+
+</li><li> Space (ASCII 32)
+
+</li><li> Single and double quotes (‘<samp>'</samp>’ and
‘<samp>"</samp>’)
+
+</li><li> Backslash (‘<samp>\</samp>’)
+</li></ul>
+
+<p>The exact way <code>tar</code> uses to quote these characters depends on
+the <em>quoting style</em>. The default quoting style, called
+<em>escape</em> (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</samp>’ in the
+above table, a space is printed as ‘<samp>\ </samp>’ and a
backslash as ‘<samp>\\</samp>’.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> offers seven distinct quoting
styles, which can be selected
+using ‘<samp>--quoting-style</samp>’ option:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--quoting-style=<var>style</var></samp>’</dt>
+<dd><a name="IDX326"></a>
+
+<p>Sets quoting style. Valid values for <var>style</var> argument are:
+literal, shell, shell-always, c, escape, locale, clocale.
+</p></dd>
+</dl>
+
+<p>These styles are described in detail below. To illustrate their
+effect, we will use an imaginary tar archive ‘<tt>arch.tar</tt>’
+containing the following members:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"># 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
+</pre></td></tr></table>
+
+<p>Here is how usual <code>ls</code> command would have listed them, if they
+had existed in the current working directory:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>ls</kbd>
+a\ttab
+a\nnewline
+a\ space
+a"double"quote
+a'single'quote
+a\\backslash
+</pre></td></tr></table>
+
+<p>Quoting styles:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>literal</samp>’</dt>
+<dd><p>No quoting, display each character as is:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf arch.tar
--quoting-style=literal</kbd>
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\backslash
+./a tab
+./a
+newline
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>shell</samp>’</dt>
+<dd><p>Display characters the same way Bourne shell does:
+control characters, except ‘<samp>\t</samp>’ and
‘<samp>\n</samp>’, are printed using
+backslash escapes, ‘<samp>\t</samp>’ and
‘<samp>\n</samp>’ are printed as is, and a
+single quote is printed as ‘<samp>\'</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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf arch.tar
--quoting-style=shell</kbd>
+./
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>shell-always</samp>’</dt>
+<dd><p>Same as ‘<samp>shell</samp>’, but the names are always
enclosed in single
+quotes:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf arch.tar
--quoting-style=shell-always</kbd>
+'./'
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>c</samp>’</dt>
+<dd><p>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>\"</samp>’,
+backslash characters are represented as ‘<samp>\\</samp>’. Single
quotes and
+spaces are not quoted:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf arch.tar
--quoting-style=c</kbd>
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>escape</samp>’</dt>
+<dd><p>Control characters are printed using backslash notation, a space is
+printed as ‘<samp>\ </samp>’ and a backslash as
‘<samp>\\</samp>’. This is the
+default quoting style, unless it was changed when configured the
+package.
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf arch.tar
--quoting-style=escape</kbd>
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>locale</samp>’</dt>
+<dd><p>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>`</samp>’ as left and
‘<samp>'</samp>’ as right
+quotation marks. Any occurrences of the right quotation mark in a
+name are escaped with ‘<samp>\</samp>’, for example:
+</p>
+<p>For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf arch.tar
--quoting-style=locale</kbd>
+`./'
+`./a space'
+`./a\'single\'quote'
+`./a"double"quote'
+`./a\\backslash'
+`./a\ttab'
+`./a\nnewline'
+</pre></td></tr></table>
+
+</dd>
+<dt> ‘<samp>clocale</samp>’</dt>
+<dd><p>Same as ‘<samp>locale</samp>’, but
‘<samp>"</samp>’ is used for both left and right
+quotation marks, if not provided by the currently selected locale:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf arch.tar
--quoting-style=clocale</kbd>
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
+</pre></td></tr></table>
+</dd>
+</dl>
+
+<p>You can specify which characters should be quoted in addition to those
+implied by the current quoting style:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--quote-chars=<var>string</var></samp>’</dt>
+<dd><p>Always quote characters from <var>string</var>, even if the selected
+quoting style would not quote them.
+</p></dd>
+</dl>
+
+<p>For example, using ‘<samp>escape</samp>’ quoting (compare with
the usual
+escape listing above):
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar tf arch.tar
--quoting-style=escape --quote-chars=' "'</kbd>
+./
+./a\ space
+./a'single'quote
+./a\"double\"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+</pre></td></tr></table>
+
+<p>To disable quoting of such additional characters, use the following
+option:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--no-quote-chars=<var>string</var></samp>’</dt>
+<dd><p>Remove characters listed in <var>string</var> from the list of quoted
+characters set by the previous ‘<samp>--quote-chars</samp>’ option.
+</p></dd>
+</dl>
+
+<p>This option is particularly useful if you have added
+‘<samp>--quote-chars</samp>’ to your <code>TAR_OPTIONS</code> (see
<a href="#TAR_005fOPTIONS">TAR_OPTIONS</a>)
+and wish to disable it for the current invocation.
+</p>
+<p>Note, that ‘<samp>--no-quote-chars</samp>’ does <em>not</em>
disable those
+characters that are quoted by default in the selected quoting style.
+</p>
+<hr size="6">
+<a name="transform"></a>
+<a name="SEC107"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC106" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC108" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.7 Modifying File and Member Names </h2>
+
+<p><code>Tar</code> 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.
+</p>
+<p>First of all, it is often unsafe to extract archive members with
+absolute file names or those that begin with a ‘<tt>../</tt>’.
<acronym>GNU</acronym> <code>tar</code>
+takes special precautions when extracting such names and provides a
+special option for handling them, which is described in
+<a href="#SEC112">Absolute File Names</a>.
+</p>
+<p>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.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> provides two options for these
needs.
+</p>
+<dl compact="compact">
+<dd><a name="IDX327"></a>
+</dd>
+<dt> ‘<samp>--strip-components=<var>number</var></samp>’</dt>
+<dd><p>Strip given <var>number</var> of leading components from file names
before
+extraction.
+</p></dd>
+</dl>
+
+<p>For example, suppose you have archived whole ‘<tt>/usr</tt>’
hierarchy to
+a tar archive named ‘<tt>usr.tar</tt>’. Among other files, this
archive
+contains ‘<tt>usr/include/stdlib.h</tt>’, which you wish to
extract to
+the current working directory. To do so, you type:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -xf usr.tar
--strip=2 usr/include/stdlib.h</kbd>
+</pre></td></tr></table>
+
+<p>The option ‘<samp>--strip=2</samp>’ instructs <code>tar</code>
to strip the
+two leading components (‘<tt>usr/</tt>’ and
‘<tt>include/</tt>’) off the file
+name.
+</p>
+<p>If you add to the above invocation ‘<samp>--verbose</samp>’
(‘<samp>-v</samp>’)
+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 <code>tar</code> provides a special option for
+altering this behavior:
+</p>
+<p><a name="show_002dtransformed_002dnames"></a>
+</p><dl compact="compact">
+<dd><a name="IDX328"></a>
+</dd>
+<dt> ‘<samp>--show-transformed-names</samp>’</dt>
+<dd><p>Display file or member names with all requested transformations
+applied.
+</p></dd>
+</dl>
+
+<p>For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -xf usr.tar
-v --strip=2 usr/include/stdlib.h</kbd>
+usr/include/stdlib.h
+$ <kbd>tar -xf usr.tar -v --strip=2 --show-transformed
usr/include/stdlib.h</kbd>
+stdlib.h
+</pre></td></tr></table>
+
+<p>Notice that in both cases the file is ‘<tt>stdlib.h</tt>’
extracted to the
+current working directory, ‘<samp>--show-transformed-names</samp>’
affects
+only the way its name is displayed.
+</p>
+<p>This option is especially useful for verifying whether the invocation
+will have the desired effect. Thus, before running
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -x
--strip=<var>n</var></kbd>
+</pre></td></tr></table>
+
+<p>it is often advisable to run
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -t -v
--show-transformed --strip=<var>n</var></kbd>
+</pre></td></tr></table>
+
+<p>to make sure the command will produce the intended results.
+</p>
+<p>In case you need to apply more complex modifications to the file name,
+<acronym>GNU</acronym> <code>tar</code> provides a general-purpose
transformation option:
+</p>
+<dl compact="compact">
+<dd><a name="IDX329"></a>
+</dd>
+<dt> ‘<samp>--transform=<var>expression</var></samp>’</dt>
+<dd><p>Modify file names using supplied <var>expression</var>.
+</p></dd>
+</dl>
+
+<p>The <var>expression</var> is a <code>sed</code>-like replace expression of
the
+form:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">s/<var>regexp</var>/<var>replace</var>/[<var>flags</var>]
+</pre></td></tr></table>
+
+<p>where <var>regexp</var> is a <em>regular expression</em>,
<var>replace</var> is a
+replacement for each file name part that matches <var>regexp</var>. Both
+<var>regexp</var> and <var>replace</var> are described in detail in
+<a href="sed.html#The-_0022s_0022-Command">The "s" Command: (sed)The
"s" Command</a> section `The `s' Command' in <cite>GNU sed</cite>.
+</p>
+<p>Supported <var>flags</var> are:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>g</samp>’</dt>
+<dd><p>Apply the replacement to <em>all</em> matches to the <var>regexp</var>,
not
+just the first.
+</p>
+</dd>
+<dt> ‘<samp>i</samp>’</dt>
+<dd><p>Use case-insensitive matching
+</p>
+</dd>
+<dt> ‘<samp>x</samp>’</dt>
+<dd><p><var>regexp</var> is an <em>extended regular expression</em> (see <a
href="sed.html#Extended-regexps">Extended regular expressions: (sed)Extended
regexps</a> section `Extended regular expressions' in <cite>GNU sed</cite>).
+</p>
+</dd>
+<dt> ‘<samp><var>number</var></samp>’</dt>
+<dd><p>Only replace the <var>number</var>th match of the <var>regexp</var>.
+</p>
+<p>Note: the <var>posix</var> standard does not specify what should happen
+when you mix the ‘<samp>g</samp>’ and <var>number</var> modifiers.
<acronym>GNU</acronym> <code>tar</code>
+follows the GNU <code>sed</code> implementation in this regard, so
+the the interaction is defined to be: ignore matches before the
+<var>number</var>th, and then match and replace all matches from the
+<var>number</var>th on.
+</p>
+</dd>
+</dl>
+
+<p>Any delimiter can be used in lieue of ‘<samp>/</samp>’, the
only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">s/one/two/
+s,one,two,
+</pre></td></tr></table>
+
+<p>Changing delimiters is often useful when the <var>regex</var> contains
+slashes. For example, it is more convenient to write <code>s,/,-,</code> than
+<code>s/\//-/</code>.
+</p>
+<p>Here are several examples of ‘<samp>--transform</samp>’ usage:
+</p>
+<ol>
+<li> Extract ‘<tt>usr/</tt>’ hierarchy into
‘<tt>usr/local/</tt>’:
+
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar
--transform='s,usr/,usr/local/,' -x -f arch.tar</kbd>
+</pre></td></tr></table>
+
+</li><li> Strip two leading directory components (equivalent to
+‘<samp>--strip-components=2</samp>’):
+
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar
--transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar</kbd>
+</pre></td></tr></table>
+
+</li><li> Prepend ‘<tt>/prefix/</tt>’ to each file name:
+
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --transform
's,^,/prefix/,' -x -f arch.tar</kbd>
+</pre></td></tr></table>
+
+</li><li> Convert each file name to lower case:
+
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --transform
's/.*/\L&/' -x -f arch.tar</kbd>
+</pre></td></tr></table>
+
+</li></ol>
+
+<p>Unlike ‘<samp>--strip-components</samp>’,
‘<samp>--transform</samp>’ can be used
+in any <acronym>GNU</acronym> <code>tar</code> operation mode. For example,
the following command
+adds files to the archive while replacing the leading
‘<tt>usr/</tt>’
+component with ‘<tt>var/</tt>’:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cf
arch.tar --transform='s,^usr/,var/,' /</kbd>
+</pre></td></tr></table>
+
+<p>To test ‘<samp>--transform</samp>’ effect we suggest using
+‘<samp>--show-transformed-names</samp>’ option:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cf
arch.tar --transform='s,^usr/,var/,' \
+ --verbose --show-transformed-names /</kbd>
+</pre></td></tr></table>
+
+<p>If both ‘<samp>--strip-components</samp>’ and
‘<samp>--transform</samp>’ are used
+together, then ‘<samp>--transform</samp>’ is applied first, and
the required
+number of components is then stripped from its result.
+</p>
+<hr size="6">
+<a name="after"></a>
+<a name="SEC108"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC107" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC109" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.8 Operating Only on New Files </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX330"></a>
+<a name="IDX331"></a>
+<a name="IDX332"></a>
+<a name="IDX333"></a>
+<p>The ‘<samp>--after-date=<var>date</var></samp>’
(‘<samp>--newer=<var>date</var></samp>’,
+‘<samp>-N <var>date</var></samp>’) option causes <code>tar</code>
to only work on
+files whose data modification or status change times are newer than
+the <var>date</var> given. If <var>date</var> starts with
‘<samp>/</samp>’ or ‘<samp>.</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
+‘<samp>--after-date</samp>’ when extracting an archive,
<code>tar</code> will
+only extract files newer than the <var>date</var> you specify.
+</p>
+<p>If you only want <code>tar</code> to make the date comparison based on
+modification of the file's data (rather than status
+changes), then use the
‘<samp>--newer-mtime=<var>date</var></samp>’ option.
+</p>
+<p>You may use these options with any operation. Note that these options
+differ from the ‘<samp>--update</samp>’
(‘<samp>-u</samp>’) operation in that they
+allow you to specify a particular date against which <code>tar</code> can
+compare when deciding whether or not to archive the files.
+</p>
+<dl compact="compact">
+<dd><a name="IDX334"></a>
+<a name="IDX335"></a>
+</dd>
+<dt> ‘<samp>--after-date=<var>date</var></samp>’</dt>
+<dt> ‘<samp>--newer=<var>date</var></samp>’</dt>
+<dt> ‘<samp>-N <var>date</var></samp>’</dt>
+<dd><p>Only store files newer than <var>date</var>.
+</p>
+<p>Acts on files only if their data modification or status change times are
+later than <var>date</var>. Use in conjunction with any operation.
+</p>
+<p>If <var>date</var> starts with ‘<samp>/</samp>’ or
‘<samp>.</samp>’, it is taken to be a file
+name; the data modification time of that file is used as the date.
+</p>
+<a name="IDX336"></a>
+</dd>
+<dt> ‘<samp>--newer-mtime=<var>date</var></samp>’</dt>
+<dd><p>Acts like ‘<samp>--after-date</samp>’, but only looks at
data modification times.
+</p></dd>
+</dl>
+
+<p>These options limit <code>tar</code> 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 <a href="#SEC113">Date input formats</a>; remember
that the
+entire date argument must be quoted if it contains any spaces.)
+</p>
+<p>Gurus would say that ‘<samp>--after-date</samp>’ tests both the
data
+modification time (<code>mtime</code>, the time the contents of the file
+were last modified) and the status change time (<code>ctime</code>, the time
+the file's status was last changed: owner, permissions, etc.)
+fields, while ‘<samp>--newer-mtime</samp>’ tests only the
<code>mtime</code>
+field.
+</p>
+<p>To be precise, ‘<samp>--after-date</samp>’ checks <em>both</em>
<code>mtime</code> and
+<code>ctime</code> and processes the file if either one is more recent than
+<var>date</var>, while ‘<samp>--newer-mtime</samp>’ only checks
<code>mtime</code> and
+disregards <code>ctime</code>. Neither does it use <code>atime</code> (the
last time the
+contents of the file were looked at).
+</p>
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cf foo.tar
--newer-mtime '2 days ago'</kbd>
+</pre></td></tr></table>
+
+<p>When any of these options is used with the option
‘<samp>--verbose</samp>’
+(see section <a href="#SEC15">The ‘<samp>--verbose</samp>’
Option</a>) <acronym>GNU</acronym> <code>tar</code> 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, <code>tar</code> will
+print a warning saying what date it will use. This is to help user
+ensure he is using the right date. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
archive.tar --after-date='10 days ago' .</kbd>
+tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
+13:19:37.232434
+</pre></td></tr></table>
+
+<blockquote><p><strong>Please Note:</strong>
‘<samp>--after-date</samp>’ and
‘<samp>--newer-mtime</samp>’
+should not be used for incremental backups. See section <a
href="#SEC88">Using <code>tar</code> to Perform Incremental Dumps</a>,
+for proper way of creating incremental backups.
+</p></blockquote>
+
+<hr size="6">
+<a name="recurse"></a>
+<a name="SEC109"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC108" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC110" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.9 Descending into Directories </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+<a name="IDX337"></a>
+<a name="IDX338"></a>
+<a name="IDX339"></a>
+<a name="IDX340"></a>
+
+
+
+
+
+<p>Usually, <code>tar</code> will recursively explore all directories (either
+those given on the command line or through the
‘<samp>--files-from</samp>’
+option) for the various files they contain. However, you may not always
+want <code>tar</code> to act this way.
+</p>
+<a name="IDX341"></a>
+<p>The ‘<samp>--no-recursion</samp>’ option inhibits
<code>tar</code>'s recursive descent
+into specified directories. If you specify
‘<samp>--no-recursion</samp>’, you can
+use the <code>find</code> utility for hunting through levels of directories to
+construct a list of file names which you could then pass to <code>tar</code>.
+<code>find</code> allows you to be more selective when choosing which files to
+archive; see <a href="#SEC100">Reading Names from a File</a>, for more
information on using <code>find</code> with
+<code>tar</code>, or look.
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--no-recursion</samp>’</dt>
+<dd><p>Prevents <code>tar</code> from recursively descending directories.
+</p>
+<a name="IDX342"></a>
+</dd>
+<dt> ‘<samp>--recursion</samp>’</dt>
+<dd><p>Requires <code>tar</code> to recursively descend directories.
+This is the default.
+</p></dd>
+</dl>
+
+<p>When you use ‘<samp>--no-recursion</samp>’,
<acronym>GNU</acronym> <code>tar</code> grabs
+directory entries themselves, but does not descend on them
+recursively. Many people use <code>find</code> for locating files they
+want to back up, and since <code>tar</code> <em>usually</em> recursively
+descends on directories, they have to use the ‘<samp>-not -type
d</samp>’
+test in their <code>find</code> invocation (see <a href="find.html#Type">Type:
(find)Type</a> section `Type test' in <cite>Finding Files</cite>), as they
usually do not want all the files in a
+directory. They then use the ‘<samp>--files-from</samp>’ option to
archive
+the files located via <code>find</code>.
+</p>
+<p>The problem when restoring files archived in this manner is that the
+directories themselves are not in the archive; so the
+‘<samp>--same-permissions</samp>’
(‘<samp>--preserve-permissions</samp>’,
+‘<samp>-p</samp>’) option does not affect them—while users
might really
+like it to. Specifying ‘<samp>--no-recursion</samp>’ is a way to
tell
+<code>tar</code> to grab only the directory entries given to it, adding
+no new files on its own. To summarize, if you use <code>find</code> to
+create a list of files to be stored in an archive, use it as follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>find
<var>dir</var> <var>tests</var> | \
+ tar -cf <var>archive</var> -T - --no-recursion</kbd>
+</pre></td></tr></table>
+
+<p>The ‘<samp>--no-recursion</samp>’ option also applies when
extracting: it
+causes <code>tar</code> to extract only the matched directory entries, not
+the files under those directories.
+</p>
+<p>The ‘<samp>--no-recursion</samp>’ option also affects how
globbing patterns
+are interpreted (see section <a href="#SEC105">Controlling
Pattern-Matching</a>).
+</p>
+<p>The ‘<samp>--no-recursion</samp>’ and
‘<samp>--recursion</samp>’ options apply to
+later options and operands, and can be overridden by later occurrences
+of ‘<samp>--no-recursion</samp>’ and
‘<samp>--recursion</samp>’. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cf
jams.tar --no-recursion grape --recursion grape/concord</kbd>
+</pre></td></tr></table>
+
+<p>creates an archive with one entry for ‘<tt>grape</tt>’, and the
recursive
+contents of ‘<tt>grape/concord</tt>’, but no entries under
‘<tt>grape</tt>’
+other than ‘<tt>grape/concord</tt>’.
+</p>
+<hr size="6">
+<a name="one"></a>
+<a name="SEC110"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC109" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC111" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 6.10 Crossing File System Boundaries </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p><code>tar</code> 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 <code>tar</code> and specifying
+‘<samp>--one-file-system</samp>’. This option only affects files
that are
+archived because they are in a directory that is being archived;
+<code>tar</code> will still archive files explicitly named on the command line
+or through ‘<samp>--files-from</samp>’, regardless of where they
reside.
+</p>
+<dl compact="compact">
+<dd><a name="IDX343"></a>
+</dd>
+<dt> ‘<samp>--one-file-system</samp>’</dt>
+<dd><p>Prevents <code>tar</code> from crossing file system boundaries when
+archiving. Use in conjunction with any write operation.
+</p></dd>
+</dl>
+
+<p>The ‘<samp>--one-file-system</samp>’ option causes
<code>tar</code> 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
+<code>tar</code> will not archive that file. If the file is a directory
+itself, <code>tar</code> will not archive anything beneath it; in other words,
+<code>tar</code> will not cross mount points.
+</p>
+<p>This option is useful for making full or incremental archival backups of
+a file system. If this option is used in conjunction with
+‘<samp>--verbose</samp>’ (‘<samp>-v</samp>’), files
that are excluded are
+mentioned by name on the standard error.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC111">6.10.1 Changing the
Working Directory</a></td><td> </td><td align="left" valign="top">
Changing Directory
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC112">6.10.2 Absolute File
Names</a></td><td> </td><td align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="directory"></a>
+<a name="SEC111"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC110" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC112" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC110" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 6.10.1 Changing the Working Directory </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+
+
+
+
+<a name="IDX344"></a>
+<a name="IDX345"></a>
+<a name="IDX346"></a>
+<p>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
+‘<samp>--files-from</samp>’ (‘<samp>-T</samp>’), use
‘<samp>--directory</samp>’ (‘<samp>-C</samp>’).
+This will change the working directory to the specified directory
+after that point in the list.
+</p>
+<dl compact="compact">
+<dd><a name="IDX347"></a>
+</dd>
+<dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
+<dt> ‘<samp>-C <var>directory</var></samp>’</dt>
+<dd><p>Changes the working directory in the middle of a command line.
+</p></dd>
+</dl>
+
+<p>For example,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
jams.tar grape prune -C food cherry</kbd>
+</pre></td></tr></table>
+
+<p>will place the files ‘<tt>grape</tt>’ and
‘<tt>prune</tt>’ from the current
+directory into the archive ‘<tt>jams.tar</tt>’, followed by the
file
+‘<tt>cherry</tt>’ from the directory ‘<tt>food</tt>’.
This option is especially
+useful when you have several widely separated files that you want to
+store in the same archive.
+</p>
+<p>Note that the file ‘<tt>cherry</tt>’ is recorded in the archive
under the
+precise name ‘<tt>cherry</tt>’, <em>not</em>
‘<tt>food/cherry</tt>’. 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</samp>’, all three files will be written in the current
directory.
+</p>
+<p>Contrast this with the command,
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
jams.tar grape prune -C food red/cherry</kbd>
+</pre></td></tr></table>
+
+<p>which records the third file in the archive under the name
+‘<tt>red/cherry</tt>’ so that, if the archive is extracted using
+‘<samp>tar --extract</samp>’, the third file will be written in a
subdirectory
+named ‘<tt>orange-colored</tt>’.
+</p>
+<p>You can use the ‘<samp>--directory</samp>’ option to make the
archive
+independent of the original name of the directory holding the files.
+The following command places the files ‘<tt>/etc/passwd</tt>’,
+‘<tt>/etc/hosts</tt>’, and ‘<tt>/lib/libc.a</tt>’ into
the archive
+‘<tt>foo.tar</tt>’:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
foo.tar -C /etc passwd hosts -C /lib libc.a</kbd>
+</pre></td></tr></table>
+
+<p>However, the names of the archive members will be exactly what they were
+on the command line: ‘<tt>passwd</tt>’,
‘<tt>hosts</tt>’, and ‘<tt>libc.a</tt>’.
+They will not appear to be related by file name to the original
+directories where those files were located.
+</p>
+<p>Note that ‘<samp>--directory</samp>’ options are interpreted
consecutively. If
+‘<samp>--directory</samp>’ 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 <code>tar</code>, due to a previous
+‘<samp>--directory</samp>’ option.
+</p>
+<p>When using ‘<samp>--files-from</samp>’ (see section <a
href="#SEC100">Reading Names from a File</a>), you can put various
+<code>tar</code> options (including ‘<samp>-C</samp>’) 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.
+</p>
+<p>For instance, the file list for the above example will be:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">-C
+/etc
+passwd
+hosts
+-C
+/lib
+libc.a
+</pre></td></tr></table>
+
+<p>To use it, you would invoke <code>tar</code> as follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
foo.tar --files-from list</kbd>
+</pre></td></tr></table>
+
+<p>Notice also that you can only use the short option variant in the file
+list, i.e., always use ‘<samp>-C</samp>’, not
‘<samp>--directory</samp>’.
+</p>
+<p>The interpretation of ‘<samp>--directory</samp>’ is disabled by
+‘<samp>--null</samp>’ option.
+</p>
+<hr size="6">
+<a name="absolute"></a>
+<a name="SEC112"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC111" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC110" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 6.10.2 Absolute File Names </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<dl compact="compact">
+<dd><a name="IDX348"></a>
+</dd>
+<dt> ‘<samp>--absolute-names</samp>’</dt>
+<dt> ‘<samp>-P</samp>’</dt>
+<dd><p>Do not strip leading slashes from file names, and permit file names
+containing a ‘<tt>..</tt>’ file name component.
+</p></dd>
+</dl>
+
+<p>By default, <acronym>GNU</acronym> <code>tar</code> drops a leading
‘<samp>/</samp>’ on
+input or output, and complains about file names containing a
‘<tt>..</tt>’
+component. This option turns off this behavior.
+</p>
+<p>When <code>tar</code> extracts archive members from an archive, it strips
any
+leading slashes (‘<samp>/</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
+‘<tt>/etc/passwd</tt>’, <code>tar</code> will extract it as if the
name were
+really ‘<tt>etc/passwd</tt>’.
+</p>
+<p>File names containing ‘<tt>..</tt>’ can cause problems when
extracting, so
+<code>tar</code> normally warns you about such files when creating an
+archive, and rejects attempts to extracts such files.
+</p>
+<p>Other <code>tar</code> 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 non-<acronym>GNU</acronym> <code>tar</code>
+program to use. Therefore, <acronym>GNU</acronym> <code>tar</code> also strips
+leading slashes from member names when putting members into the
+archive. For example, if you ask <code>tar</code> to add the file
+‘<tt>/bin/ls</tt>’ to an archive, it will do so, but the member
name will
+be ‘<tt>bin/ls</tt>’.<a name="DOCF17" href="#FOOT17">(17)</a>
+</p>
+<p>If you use the ‘<samp>--absolute-names</samp>’
(‘<samp>-P</samp>’) option,
+<code>tar</code> will do none of these transformations.
+</p>
+<p>To archive or extract files relative to the root directory, specify
+the ‘<samp>--absolute-names</samp>’
(‘<samp>-P</samp>’) option.
+</p>
+<p>Normally, <code>tar</code> acts on files relative to the working
+directory—ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+</p>
+<p>When you specify ‘<samp>--absolute-names</samp>’
(‘<samp>-P</samp>’),
+<code>tar</code> stores file names including all superior directory
+names, and preserves leading slashes. If you only invoked
+<code>tar</code> from the root directory you would never need the
+‘<samp>--absolute-names</samp>’ option, but using this option
+may be more convenient than switching to root.
+</p>
+
+
+
+
+
+
+
+
+<dl compact="compact">
+<dt> ‘<samp>--absolute-names</samp>’</dt>
+<dd><p>Preserves full file names (including superior directory names) when
+archiving files. Preserves leading slash when extracting files.
+</p>
+</dd>
+</dl>
+
+
+
+
+
+<p><code>tar</code> prints out a message about removing the
‘<samp>/</samp>’ from
+file names. This message appears once per <acronym>GNU</acronym>
<code>tar</code>
+invocation. It represents something which ought to be told; ignoring
+what it means can cause very serious surprises, later.
+</p>
+<p>Some people, nevertheless, do not want to see this message. Wanting to
+play really dangerously, one may of course redirect <code>tar</code> standard
+error to the sink. For example, under <code>sh</code>:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -c -f
archive.tar /home 2> /dev/null</kbd>
+</pre></td></tr></table>
+
+<p>Another solution, both nicer and simpler, would be to change to
+the ‘<tt>/</tt>’ directory first, and then avoid absolute notation.
+For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>(cd /
&& tar -c -f archive.tar home)</kbd>
+# <i>or</i>:
+$ <kbd>tar -c -f archive.tar -C / home</kbd>
+</pre></td></tr></table>
+
+
+
+
+<hr size="6">
+<a name="Date-input-formats"></a>
+<a name="SEC113"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC112" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC114" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 7. Date input formats </h1>
+
+
+<p>First, a quote:
+</p>
+<blockquote><p>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.
+</p>
+<p>… 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. …
+</p>
+<p>— Robert Grudin, <cite>Time and the Art of Living</cite>.
+</p></blockquote>
+
+<p>This section describes the textual date representations that
<small>GNU</small>
+programs accept. These are the strings you, as a user, can supply as
+arguments to the various programs. The C interface (via the
+<code>get_date</code> function) is not described here.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC114">7.1 General date
syntax</a></td><td> </td><td align="left" valign="top">
Common rules.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC115">7.2 Calendar date
items</a></td><td> </td><td align="left" valign="top"> 19
Dec 1994.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC116">7.3 Time of day
items</a></td><td> </td><td align="left" valign="top">
9:20pm.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC117">7.4 Time zone
items</a></td><td> </td><td align="left" valign="top">
<small>EST</small>, <small>PDT</small>, <small>GMT</small>.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC118">7.5 Day of week
items</a></td><td> </td><td align="left" valign="top">
Monday and others.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC119">7.6 Relative items in date
strings</a></td><td> </td><td align="left" valign="top"> next
tuesday, 2 years ago.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC120">7.7 Pure numbers in date
strings</a></td><td> </td><td align="left" valign="top"> 19931219,
1440.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC121">7.8 Seconds since the
Epoch</a></td><td> </td><td align="left" valign="top">
@1078100502.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC122">7.9 Specifying time zone
rules</a></td><td> </td><td align="left" valign="top">
TZ="America/New_York", TZ="UTC0".
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td><td> </td><td align="left"
valign="top"> Bellovin, Eggert, Salz, Berets, et al.
+</td></tr>
+</table>
+
+
+<hr size="6">
+<a name="General-date-syntax"></a>
+<a name="SEC114"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC113" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC115" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.1 General date syntax </h2>
+
+
+<p>A <em>date</em> 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:
+</p>
+<ul>
+<li> calendar date items
+</li><li> time of day items
+</li><li> time zone items
+</li><li> day of the week items
+</li><li> relative items
+</li><li> pure numbers.
+</li></ul>
+
+<p>We describe each of these item types in turn, below.
+</p>
+<a name="IDX349"></a>
+<a name="IDX350"></a>
+<a name="IDX351"></a>
+<a name="IDX352"></a>
+<a name="IDX353"></a>
+<p>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
+‘<samp>last</samp>’ stands for <em>-1</em>,
‘<samp>this</samp>’ stands for 0, and
+‘<samp>first</samp>’ and ‘<samp>next</samp>’ both
stand for 1. Because the word
+‘<samp>second</samp>’ stands for the unit of time there is no way
to write the
+ordinal number 2, but for convenience ‘<samp>third</samp>’ stands
for 3,
+‘<samp>fourth</samp>’ for 4, ‘<samp>fifth</samp>’ for
5,
+‘<samp>sixth</samp>’ for 6, ‘<samp>seventh</samp>’ for
7, ‘<samp>eighth</samp>’ for 8,
+‘<samp>ninth</samp>’ for 9, ‘<samp>tenth</samp>’ for
10, ‘<samp>eleventh</samp>’ for 11 and
+‘<samp>twelfth</samp>’ for 12.
+</p>
+<a name="IDX354"></a>
+<p>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.
+</p>
+<a name="IDX355"></a>
+<p>In the current implementation, only English is supported for words and
+abbreviations like ‘<samp>AM</samp>’,
‘<samp>DST</samp>’, ‘<samp>EST</samp>’,
‘<samp>first</samp>’,
+‘<samp>January</samp>’, ‘<samp>Sunday</samp>’,
‘<samp>tomorrow</samp>’, and ‘<samp>year</samp>’.
+</p>
+<a name="IDX356"></a>
+<a name="IDX357"></a>
+<p>The output of the <code>date</code> 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</samp>’.
When using
+<code>date</code> 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</samp>’ and
‘<samp>Z</samp>’. Here are some
+ways to do this:
+</p>
+<table><tr><td> </td><td><pre class="example">$ 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.
address@hidden
+</pre></td></tr></table>
+
+<a name="IDX358"></a>
+<a name="IDX359"></a>
+<p>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.
+</p>
+<p>Invalid dates like ‘<samp>2005-02-29</samp>’ or times like
‘<samp>24:00</samp>’ are
+rejected. In the typical case of a host that does not support leap
+seconds, a time like ‘<samp>23:59:60</samp>’ is rejected even if it
+corresponds to a valid leap second.
+</p>
+
+<hr size="6">
+<a name="Calendar-date-items"></a>
+<a name="SEC115"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC114" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC116" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.2 Calendar date items </h2>
+
+
+<p>A <em>calendar date item</em> 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:
+</p>
+<table><tr><td> </td><td><pre class="example">1972-09-24 # 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
+</pre></td></tr></table>
+
+<p>The year can also be omitted. In this case, the last specified year is
+used, or the current year if none. For example:
+</p>
+<table><tr><td> </td><td><pre class="example">9/24
+sep 24
+</pre></td></tr></table>
+
+<p>Here are the rules.
+</p>
+<a name="IDX360"></a>
+<a name="IDX361"></a>
+<p>For numeric months, the <small>ISO</small> 8601 format
+‘<samp><var>year</var>-<var>month</var>-<var>day</var></samp>’ is
allowed, where <var>year</var> is
+any positive number, <var>month</var> is a number between 01 and 12, and
+<var>day</var> is a number between 01 and 31. A leading zero must be present
+if a number is less than ten. If <var>year</var> is 68 or smaller, then 2000
+is added to it; otherwise, if <var>year</var> is less than 100,
+then 1900 is added to it. The construct
+‘<samp><var>month</var>/<var>day</var>/<var>year</var></samp>’,
popular in the United States,
+is accepted. Also ‘<samp><var>month</var>/<var>day</var></samp>’,
omitting the year.
+</p>
+<a name="IDX362"></a>
+<a name="IDX363"></a>
+<p>Literal months may be spelled out in full:
‘<samp>January</samp>’,
+‘<samp>February</samp>’, ‘<samp>March</samp>’,
‘<samp>April</samp>’, ‘<samp>May</samp>’,
‘<samp>June</samp>’,
+‘<samp>July</samp>’, ‘<samp>August</samp>’,
‘<samp>September</samp>’, ‘<samp>October</samp>’,
+‘<samp>November</samp>’ or ‘<samp>December</samp>’.
Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write ‘<samp>Sept</samp>’ instead of
‘<samp>September</samp>’.
+</p>
+<p>When months are written literally, the calendar date may be given as any
+of the following:
+</p>
+<table><tr><td> </td><td><pre class="example"><var>day</var>
<var>month</var> <var>year</var>
+<var>day</var> <var>month</var>
+<var>month</var> <var>day</var> <var>year</var>
+<var>day</var>-<var>month</var>-<var>year</var>
+</pre></td></tr></table>
+
+<p>Or, omitting the year:
+</p>
+<table><tr><td> </td><td><pre class="example"><var>month</var>
<var>day</var>
+</pre></td></tr></table>
+
+
+<hr size="6">
+<a name="Time-of-day-items"></a>
+<a name="SEC116"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC115" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC117" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.3 Time of day items </h2>
+
+
+<p>A <em>time of day item</em> in date strings specifies the time on a given
+day. Here are some examples, all of which represent the same time:
+</p>
+<table><tr><td> </td><td><pre class="example">20:02:00.000000
+20:02
+8:02pm
+20:02-0500 # In EST (U.S. Eastern Standard Time).
+</pre></td></tr></table>
+
+<p>More generally, the time of day may be given as
+‘<samp><var>hour</var>:<var>minute</var>:<var>second</var></samp>’,
where <var>hour</var> is
+a number between 0 and 23, <var>minute</var> is a number between 0 and
+59, and <var>second</var> is a number between 0 and 59 possibly followed by
+‘<samp>.</samp>’ or ‘<samp>,</samp>’ and a fraction
containing one or more digits.
+Alternatively,
+‘<samp>:<var>second</var></samp>’ can be omitted, in which case it
is taken to
+be zero. On the rare hosts that support leap seconds, <var>second</var>
+may be 60.
+</p>
+<a name="IDX364"></a>
+<a name="IDX365"></a>
+<a name="IDX366"></a>
+<a name="IDX367"></a>
+<p>If the time is followed by ‘<samp>am</samp>’ or
‘<samp>pm</samp>’ (or ‘<samp>a.m.</samp>’
+or ‘<samp>p.m.</samp>’), <var>hour</var> is restricted to run from
1 to 12, and
+‘<samp>:<var>minute</var></samp>’ may be omitted (taken to be
zero). ‘<samp>am</samp>’
+indicates the first half of the day, ‘<samp>pm</samp>’ indicates
the second
+half of the day. In this notation, 12 is the predecessor of 1:
+midnight is ‘<samp>12am</samp>’ while noon is
‘<samp>12pm</samp>’.
+(This is the zero-oriented interpretation of ‘<samp>12am</samp>’
and ‘<samp>12pm</samp>’,
+as opposed to the old tradition derived from Latin
+which uses ‘<samp>12m</samp>’ for noon and
‘<samp>12pm</samp>’ for midnight.)
+</p>
+<a name="IDX368"></a>
+<a name="IDX369"></a>
+<p>The time may alternatively be followed by a time zone correction,
+expressed as
‘<samp><var>s</var><var>hh</var><var>mm</var></samp>’, where
<var>s</var> is ‘<samp>+</samp>’
+or ‘<samp>-</samp>’, <var>hh</var> is a number of zone hours and
<var>mm</var> is a number
+of zone minutes. You can also separate <var>hh</var> from <var>mm</var> with
a colon.
+When a time zone correction is given this way, it
+forces interpretation of the time relative to
+Coordinated Universal Time (<small>UTC</small>), overriding any previous
+specification for the time zone or the local time zone. For example,
+‘<samp>+0530</samp>’ and ‘<samp>+05:30</samp>’ both
stand for the time zone 5.5 hours
+ahead of <small>UTC</small> (e.g., India). The <var>minute</var>
+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.
+</p>
+<p>Either ‘<samp>am</samp>’/‘<samp>pm</samp>’ or a
time zone correction may be specified,
+but not both.
+</p>
+
+<hr size="6">
+<a name="Time-zone-items"></a>
+<a name="SEC117"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC116" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC118" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.4 Time zone items </h2>
+
+
+<p>A <em>time zone item</em> specifies an international time zone, indicated
+by a small set of letters, e.g., ‘<samp>UTC</samp>’ or
‘<samp>Z</samp>’
+for Coordinated Universal
+Time. Any included periods are ignored. By following a
+non-daylight-saving time zone by the string ‘<samp>DST</samp>’ 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</samp>’; for example,
‘<samp>UTC+05:30</samp>’ is equivalent to
+‘<samp>+05:30</samp>’.
+</p>
+<p>Time zone items other than ‘<samp>UTC</samp>’ and
‘<samp>Z</samp>’
+are obsolescent and are not recommended, because they
+are ambiguous; for example, ‘<samp>EST</samp>’ 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</samp>’, as
+described in the previous section.
+</p>
+<p>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
+(see section <a href="#SEC122">Specifying time zone rules</a>).
+</p>
+
+<hr size="6">
+<a name="Day-of-week-items"></a>
+<a name="SEC118"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC117" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC119" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.5 Day of week items </h2>
+
+
+<p>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.
+</p>
+<p>Days of the week may be spelled out in full:
‘<samp>Sunday</samp>’,
+‘<samp>Monday</samp>’, ‘<samp>Tuesday</samp>’,
‘<samp>Wednesday</samp>’, ‘<samp>Thursday</samp>’,
+‘<samp>Friday</samp>’ or ‘<samp>Saturday</samp>’.
Days may be abbreviated to their
+first three letters, optionally followed by a period. The special
+abbreviations ‘<samp>Tues</samp>’ for
‘<samp>Tuesday</samp>’, ‘<samp>Wednes</samp>’ for
+‘<samp>Wednesday</samp>’ and ‘<samp>Thur</samp>’ or
‘<samp>Thurs</samp>’ for ‘<samp>Thursday</samp>’ are
+also allowed.
+</p>
+<a name="IDX370"></a>
+<a name="IDX371"></a>
+<p>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</samp>’. In this context, ‘<samp>last
<var>day</var></samp>’ or ‘<samp>next
+<var>day</var></samp>’ is also acceptable; they move one week before or
after
+the day that <var>day</var> by itself would represent.
+</p>
+<p>A comma following a day of the week item is ignored.
+</p>
+
+<hr size="6">
+<a name="Relative-items-in-date-strings"></a>
+<a name="SEC119"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC118" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC120" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.6 Relative items in date strings </h2>
+
+
+<p><em>Relative items</em> adjust a date (or the current date if none) forward
+or backward. The effects of relative items accumulate. Here are some
+examples:
+</p>
+<table><tr><td> </td><td><pre class="example">1 year
+1 year ago
+3 years
+2 days
+</pre></td></tr></table>
+
+<a name="IDX372"></a>
+<a name="IDX373"></a>
+<a name="IDX374"></a>
+<a name="IDX375"></a>
+<a name="IDX376"></a>
+<a name="IDX377"></a>
+<a name="IDX378"></a>
+<p>The unit of time displacement may be selected by the string
‘<samp>year</samp>’
+or ‘<samp>month</samp>’ 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</samp>’ which is worth 14 days,
‘<samp>week</samp>’ worth 7
+days, ‘<samp>day</samp>’ worth 24 hours,
‘<samp>hour</samp>’ worth 60 minutes,
+‘<samp>minute</samp>’ or ‘<samp>min</samp>’ worth 60
seconds, and ‘<samp>second</samp>’ or
+‘<samp>sec</samp>’ worth one second. An
‘<samp>s</samp>’ suffix on these units is
+accepted and ignored.
+</p>
+<a name="IDX379"></a>
+<p>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</samp>’ is equivalent to preceding the unit
by a
+multiplier with value <em>-1</em>.
+</p>
+<a name="IDX380"></a>
+<a name="IDX381"></a>
+<a name="IDX382"></a>
+<p>The string ‘<samp>tomorrow</samp>’ is worth one day in the
future (equivalent
+to ‘<samp>day</samp>’), the string
‘<samp>yesterday</samp>’ is worth
+one day in the past (equivalent to ‘<samp>day ago</samp>’).
+</p>
+<a name="IDX383"></a>
+<a name="IDX384"></a>
+<a name="IDX385"></a>
+<p>The strings ‘<samp>now</samp>’ or
‘<samp>today</samp>’ 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</samp>’. The string
‘<samp>this</samp>’ also has
+the meaning of a zero-valued time displacement, but is preferred in
+date strings like ‘<samp>this thursday</samp>’.
+</p>
+<p>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.
+</p>
+<p>The fuzz in units can cause problems with relative items. For
+example, ‘<samp>2003-07-31 -1 month</samp>’ 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:
+</p>
+<table><tr><td> </td><td><pre class="example">$ 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!
+</pre></td></tr></table>
+
+<p>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 <code>TZ</code> environment variable to
+‘<samp>UTC0</samp>’ before embarking on calendrical calculations.
+</p>
+<hr size="6">
+<a name="Pure-numbers-in-date-strings"></a>
+<a name="SEC120"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC119" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC121" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.7 Pure numbers in date strings </h2>
+
+
+<p>The precise interpretation of a pure decimal number depends
+on the context in the date string.
+</p>
+<p>If the decimal number is of the form
<var>yyyy</var><var>mm</var><var>dd</var> and no
+other calendar date item (see section <a href="#SEC115">Calendar date
items</a>) appears before it
+in the date string, then <var>yyyy</var> is read as the year, <var>mm</var> as
the
+month number and <var>dd</var> as the day of the month, for the specified
+calendar date.
+</p>
+<p>If the decimal number is of the form <var>hh</var><var>mm</var> and no
other time
+of day item appears before it in the date string, then <var>hh</var> is read
+as the hour of the day and <var>mm</var> as the minute of the hour, for the
+specified time of day. <var>mm</var> can also be omitted.
+</p>
+<p>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.
+</p>
+
+<hr size="6">
+<a name="Seconds-since-the-Epoch"></a>
+<a name="SEC121"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC120" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC122" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.8 Seconds since the Epoch </h2>
+
+<p>If you precede a number with ‘<samp>@</samp>’, it represents an
internal time
+stamp as a count of seconds. The number can contain an internal
+decimal point (either ‘<samp>.</samp>’ or
‘<samp>,</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.
+</p>
+<a name="IDX386"></a>
+<a name="IDX387"></a>
+<p>Internally, computer times are represented as a count of seconds since
+an epoch—a well-defined point of time. On <acronym>GNU</acronym> and
+<acronym>POSIX</acronym> systems, the epoch is 1970-01-01 00:00:00
<small>UTC</small>, so
+‘<samp>@0</samp>’ represents this time,
‘<samp>@1</samp>’ represents 1970-01-01
+00:00:01 <small>UTC</small>, and so forth. <acronym>GNU</acronym> and most
other
+<acronym>POSIX</acronym>-compliant systems support such times as an extension
+to <acronym>POSIX</acronym>, using negative counts, so that
‘<samp>@-1</samp>’
+represents 1969-12-31 23:59:59 <small>UTC</small>.
+</p>
+<p>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 <small>UTC</small>. 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.
+</p>
+<p>On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts ‘<samp>@915148799</samp>’ represents
1998-12-31
+23:59:59 <small>UTC</small>, ‘<samp>@915148800</samp>’ represents
1999-01-01 00:00:00
+<small>UTC</small>, and there is no way to represent the intervening leap
second
+1998-12-31 23:59:60 <small>UTC</small>.
+</p>
+<hr size="6">
+<a name="Specifying-time-zone-rules"></a>
+<a name="SEC122"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC121" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC123" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.9 Specifying time zone rules </h2>
+
+<p>Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the <code>TZ</code> environment
+variable, or by a system default if <code>TZ</code> 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</var>"</samp>’. The
+two quote characters (‘<samp>"</samp>’) must be present in
the date, and any
+quotes or backslashes within <var>rule</var> must be escaped by a
+backslash.
+</p>
+<p>For example, with the <acronym>GNU</acronym> <code>date</code> 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
+‘<samp>TZ="Europe/Paris"</samp>’ as shown in the
following shell transcript:
+</p>
+<table><tr><td> </td><td><pre class="example">$ export
TZ="America/New_York"
+$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+Sun Oct 31 01:30:00 EDT 2004
+</pre></td></tr></table>
+
+<p>In this example, the ‘<samp>--date</samp>’ operand begins with
its own
+<code>TZ</code> setting, so the rest of that operand is processed according
+to ‘<samp>Europe/Paris</samp>’ rules, treating the string
‘<samp>2004-10-31
+06:30</samp>’ as if it were in Paris. However, since the output of the
+<code>date</code> 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.)
+</p>
+<p>A <code>TZ</code> value is a rule that typically names a location in the
+<a href="http://www.twinsun.com/tz/tz-link.htm";>‘<samp>tz</samp>’
database</a>.
+A recent catalog of location names appears in the
+<a href="http://twiki.org/cgi-bin/xtra/tzdate";>TWiki Date and Time
Gateway</a>. A few non-<acronym>GNU</acronym> hosts require a colon before a
+location name in a <code>TZ</code> setting, e.g.,
+‘<samp>TZ=":America/New_York"</samp>’.
+</p>
+<p>The ‘<samp>tz</samp>’ database includes a wide variety of
locations ranging
+from ‘<samp>Arctic/Longyearbyen</samp>’ to
‘<samp>Antarctica/South_Pole</samp>’, but
+if you are at sea and have your own private time zone, or if you are
+using a non-<acronym>GNU</acronym> host that does not support the
‘<samp>tz</samp>’
+database, you may need to use a <acronym>POSIX</acronym> rule instead. Simple
+<acronym>POSIX</acronym> rules like ‘<samp>UTC0</samp>’ specify a
time zone without
+daylight saving time; other rules can specify simple daylight saving
+regimes. See <a href="libc.html#TZ-Variable">(libc)TZ Variable</a> section
`Specifying the Time Zone with <code>TZ</code>' in <cite>The GNU C
Library</cite>.
+</p>
+<hr size="6">
+<a name="Authors-of-get_005fdate"></a>
+<a name="SEC123"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC122" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 7.10 Authors of <code>get_date</code> </h2>
+
+
+<p><code>get_date</code> was originally implemented by Steven M. Bellovin
+(<a href="mailto:address@hidden";>address@hidden</a>) 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 (<a
href="mailto:address@hidden";>address@hidden</a>)
+and Jim Berets (<a href="mailto:address@hidden";>address@hidden</a>) in August,
1990. Various
+revisions for the <small>GNU</small> system were made by David MacKenzie, Jim
Meyering,
+Paul Eggert and others.
+</p>
+<a name="IDX388"></a>
+<a name="IDX389"></a>
+<p>This chapter was originally produced by François Pinard
+(<a href="mailto:address@hidden";>address@hidden</a>) from the
‘<tt>getdate.y</tt>’ source code,
+and then edited by K. Berry (<a
href="mailto:address@hidden";>address@hidden</a>).
+</p>
+<hr size="6">
+<a name="Formats"></a>
+<a name="SEC124"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC123" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC125" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 8. Controlling the Archive Format </h1>
+
+<p>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.
+</p>
+<p>GNU tar is able to create and handle archives in a variety of formats.
+The most frequently used formats are (in alphabetical order):
+</p>
+<dl compact="compact">
+<dt> gnu</dt>
+<dd><p>Format used by <acronym>GNU</acronym> <code>tar</code> versions up to
1.13.25. This format derived
+from an early <acronym>POSIX</acronym> 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.
+</p>
+<p>Archives in ‘<samp>gnu</samp>’ format are able to hold
pathnames of unlimited
+length.
+</p>
+</dd>
+<dt> oldgnu</dt>
+<dd><p>Format used by <acronym>GNU</acronym> <code>tar</code> of versions
prior to 1.12.
+</p>
+</dd>
+<dt> v7</dt>
+<dd><p>Archive format, compatible with the V7 implementation of tar. This
+format imposes a number of limitations. The most important of them
+are:
+</p>
+<ol>
+<li> The maximum length of a file name is limited to 99 characters.
+</li><li> The maximum length of a symbolic link is limited to 99 characters.
+</li><li> It is impossible to store special files (block and character
+devices, fifos etc.)
+</li><li> Maximum value of user or group ID is limited to 2097151 (7777777
+octal)
+</li><li> V7 archives do not contain symbolic ownership information (user
+and group name of the file owner).
+</li></ol>
+
+<p>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</acronym>
<code>tar</code> 1.15.92 and
+Automake prior to 1.9.
+</p>
+</dd>
+<dt> ustar</dt>
+<dd><p>Archive format defined by <acronym>POSIX.1-1988</acronym>
specification. It stores
+symbolic ownership information. It is also able to store
+special files. However, it imposes several restrictions as well:
+</p>
+<ol>
+<li> 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.
+</li><li> The maximum length of a symbolic link name is limited to
+100 characters.
+</li><li> Maximum size of a file the archive is able to accomodate
+is 8GB
+</li><li> Maximum value of UID/GID is 2097151.
+</li><li> Maximum number of bits in device major and minor numbers is 21.
+</li></ol>
+
+</dd>
+<dt> star</dt>
+<dd><p>Format used by Jörg Schilling <code>star</code>
+implementation. <acronym>GNU</acronym> <code>tar</code> is able to read
‘<samp>star</samp>’ archives but
+currently does not produce them.
+</p>
+</dd>
+<dt> posix</dt>
+<dd><p>Archive format defined by <acronym>POSIX.1-2001</acronym>
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</samp>’ archives will be
able to read
+most ‘<samp>posix</samp>’ 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.
+</p>
+<p>This archive format will be the default format for future versions
+of <acronym>GNU</acronym> <code>tar</code>.
+</p>
+</dd>
+</dl>
+
+<p>The following table summarizes the limitations of each of these
+formats:
+</p>
+<table>
+<thead><tr><th><p> Format </p></th><th><p> UID </p></th><th><p> File Size
</p></th><th><p> Path Name </p></th><th><p> Devn
+</p></th></tr></thead>
+<tr><td><p> gnu </p></td><td><p> 1.8e19 </p></td><td><p> Unlimited
</p></td><td><p> Unlimited </p></td><td><p> 63
+</p></td></tr>
+<tr><td><p> oldgnu </p></td><td><p> 1.8e19 </p></td><td><p> Unlimited
</p></td><td><p> Unlimited </p></td><td><p> 63
+</p></td></tr>
+<tr><td><p> v7 </p></td><td><p> 2097151 </p></td><td><p> 8GB
</p></td><td><p> 99 </p></td><td><p> n/a
+</p></td></tr>
+<tr><td><p> ustar </p></td><td><p> 2097151 </p></td><td><p> 8GB
</p></td><td><p> 256 </p></td><td><p> 21
+</p></td></tr>
+<tr><td><p> posix </p></td><td><p> Unlimited </p></td><td><p> Unlimited
</p></td><td><p> Unlimited </p></td><td><p> Unlimited
+</p></td></tr>
+</table>
+
+<p>The default format for <acronym>GNU</acronym> <code>tar</code> is defined
at compilation
+time. You may check it by running <code>tar --help</code>, and examining
+the last lines of its output. Usually, <acronym>GNU</acronym>
<code>tar</code> is configured
+to create archives in ‘<samp>gnu</samp>’ format, however, future
version will
+switch to ‘<samp>posix</samp>’.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC125">8.1 Using Less Space
through Compression</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC128">8.2 Handling File
Attributes</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC129">8.3 Making
<code>tar</code> Archives More Portable</a></td><td> </td><td
align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC142">8.4 Comparison of
<code>tar</code> and <code>cpio</code></a></td><td> </td><td
align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Compression"></a>
+<a name="SEC125"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC124" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC126" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 8.1 Using Less Space through Compression </h2>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC126">8.1.1 Creating and Reading
Compressed Archives</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC127">8.1.2 Archiving Sparse
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="gzip"></a>
+<a name="SEC126"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC125" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC127" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC125" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.1.1 Creating and Reading Compressed Archives </h3>
+
+<p><acronym>GNU</acronym> <code>tar</code> is able to create and read
compressed archives. It supports
+<code>gzip</code> and <code>bzip2</code> compression programs. For backward
+compatibilty, it also supports <code>compress</code> 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 <code>compress</code>! Besides, it is less
+effective than <code>gzip</code> and <code>bzip2</code>.
+</p>
+<p>Creating a compressed archive is simple: you just specify a
+<em>compression option</em> along with the usual archive creation
+commands. The compression option is ‘<samp>-z</samp>’
(‘<samp>--gzip</samp>’) to
+create a <code>gzip</code> compressed archive, ‘<samp>-j</samp>’
+(‘<samp>--bzip2</samp>’) to create a <code>bzip2</code> compressed
archive, and
+‘<samp>-Z</samp>’ (‘<samp>--compress</samp>’) to use
<code>compress</code> program.
+For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cfz
archive.tar.gz .</kbd>
+</pre></td></tr></table>
+
+<p>Reading compressed archive is even simpler: you don't need to specify
+any additional options as <acronym>GNU</acronym> <code>tar</code> recognizes
its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"># List the compressed
archive
+$ <kbd>tar tf archive.tar.gz</kbd>
+# Extract the compressed archive
+$ <kbd>tar xf archive.tar.gz</kbd>
+</pre></td></tr></table>
+
+<p>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</acronym> <code>tar</code>
+will indicate which option you should use. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>cat
archive.tar.gz | tar tf -</kbd>
+tar: Archive is compressed. Use -z option
+tar: Error is not recoverable: exiting now
+</pre></td></tr></table>
+
+<p>If you see such diagnostics, just add the suggested option to the
+invocation of <acronym>GNU</acronym> <code>tar</code>:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>cat
archive.tar.gz | tar tfz -</kbd>
+</pre></td></tr></table>
+
+<p>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 (‘<samp>--update</samp>’
(‘<samp>-u</samp>’)) them or delete
+(‘<samp>--delete</samp>’) members from them. Likewise, you cannot
append
+another <code>tar</code> archive to a compressed archive using
+‘<samp>--append</samp>’ (‘<samp>-r</samp>’)).
Secondly, multi-volume archives cannot be
+compressed.
+</p>
+<p>The following table summarizes compression options used by
<acronym>GNU</acronym> <code>tar</code>.
+</p>
+<dl compact="compact">
+<dd><a name="IDX390"></a>
+<a name="IDX391"></a>
+</dd>
+<dt> ‘<samp>-z</samp>’</dt>
+<dt> ‘<samp>--gzip</samp>’</dt>
+<dt> ‘<samp>--ungzip</samp>’</dt>
+<dd><p>Filter the archive through <code>gzip</code>.
+</p>
+<p>You can use ‘<samp>--gzip</samp>’ and
‘<samp>--gunzip</samp>’ 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 <code>tar</code> program to enforce the specified (or default) record
+size. The default compression parameters are used; if you need to
+override them, set <code>GZIP</code> environment variable, e.g.:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>GZIP=--best tar
cfz archive.tar.gz subdir</kbd>
+</pre></td></tr></table>
+
+<p>Another way would be to avoid the ‘<samp>--gzip</samp>’
(‘<samp>--gunzip</samp>’, ‘<samp>--ungzip</samp>’,
‘<samp>-z</samp>’) option and run
+<code>gzip</code> explicitly:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cf - subdir
| gzip --best -c - > archive.tar.gz</kbd>
+</pre></td></tr></table>
+
+<a name="IDX392"></a>
+<p>About corrupted compressed archives: <code>gzip</code>'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.
+</p>
+<p>There are pending suggestions for having a per-volume or per-file
+compression in <acronym>GNU</acronym> <code>tar</code>. 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!
+</p>
+<a name="IDX393"></a>
+</dd>
+<dt> ‘<samp>-j</samp>’</dt>
+<dt> ‘<samp>--bzip2</samp>’</dt>
+<dd><p>Filter the archive through <code>bzip2</code>. Otherwise like
‘<samp>--gzip</samp>’.
+</p>
+<a name="IDX394"></a>
+<a name="IDX395"></a>
+</dd>
+<dt> ‘<samp>-Z</samp>’</dt>
+<dt> ‘<samp>--compress</samp>’</dt>
+<dt> ‘<samp>--uncompress</samp>’</dt>
+<dd><p>Filter the archive through <code>compress</code>. Otherwise like
‘<samp>--gzip</samp>’.
+</p>
+<p>The <acronym>GNU</acronym> Project recommends you not use
+<code>compress</code>, because there is a patent covering the algorithm it
+uses. You could be sued for patent infringement merely by running
+<code>compress</code>.
+</p>
+<a name="IDX396"></a>
+</dd>
+<dt> ‘<samp>--use-compress-program=<var>prog</var></samp>’</dt>
+<dd><p>Use external compression program <var>prog</var>. Use this option if
you
+have a compression program that <acronym>GNU</acronym> <code>tar</code> does
not support. There
+are two requirements to which <var>prog</var> should comply:
+</p>
+<p>First, when called without options, it should read data from standard
+input, compress it and output it on standard output.
+</p>
+<p>Secondly, if called with ‘<samp>-d</samp>’ 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.
+</p></dd>
+</dl>
+
+<a name="IDX397"></a>
+<a name="IDX398"></a>
+<a name="IDX399"></a>
+<p>The ‘<samp>--use-compress-program</samp>’ 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 <code>gpg</code> (see <a
href="gpg.html#Top">gpg: (gpg)Top</a> section `gpg —- encryption and
signing tool' in <cite>GNU Privacy Guard Manual</cite>). The following script
does that:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">#! /bin/sh
+case $1 in
+-d) gpg --decrypt - | gzip -d -c;;
+'') gzip -c | gpg -s ;;
+*) echo "Unknown option $1">&2; exit 1;;
+esac
+</pre></td></tr></table>
+
+<p>Suppose you name it ‘<tt>gpgz</tt>’ and save it somewhere in
your
+<code>PATH</code>. Then the following command will create a commpressed
+archive signed with your private key:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -cf
foo.tar.gpgz --use-compress=gpgz .</kbd>
+</pre></td></tr></table>
+
+<p>Likewise, the following command will list its contents:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -tf
foo.tar.gpgz --use-compress=gpgz .</kbd>
+</pre></td></tr></table>
+
+
+<hr size="6">
+<a name="sparse"></a>
+<a name="SEC127"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC126" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC125" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.1.2 Archiving Sparse Files </h3>
+
+<p>Files in the file system occasionally have <em>holes</em>. A <em>hole</em>
+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, <code>tar</code>
+could create an archive longer than the original. To have <code>tar</code>
+attempt to recognize the holes in a file, use
‘<samp>--sparse</samp>’
+(‘<samp>-S</samp>’). When you use this option, then, for any file
using
+less disk space than would be expected from its length, <code>tar</code>
+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 ‘<samp>--sparse</samp>’ is not needed on
extraction) any
+such files have holes created wherever the continuous stretches of zeros
+were found. Thus, if you use ‘<samp>--sparse</samp>’,
<code>tar</code> archives
+won't take more space than the original.
+</p>
+<dl compact="compact">
+<dd><a name="IDX400"></a>
+</dd>
+<dt> ‘<samp>-S</samp>’</dt>
+<dt> ‘<samp>--sparse</samp>’</dt>
+<dd><p>This option istructs <code>tar</code> 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.
+</p>
+<p>This option is meaningful only when creating or updating archives. It
+has no effect on extraction.
+</p></dd>
+</dl>
+
+<p>Consider using ‘<samp>--sparse</samp>’ when performing file
system backups,
+to avoid archiving the expanded forms of files stored sparsely in the
+system.
+</p>
+<p>Even if your system has no sparse files currently, some may be
+created in the future. If you use ‘<samp>--sparse</samp>’ 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). See section <a href="#SEC88">Using <code>tar</code> to
Perform Incremental Dumps</a>.
+</p>
+<p>However, be aware that ‘<samp>--sparse</samp>’ option presents
a serious
+drawback. Namely, in order to determine if the file is sparse
+<code>tar</code> has to read it before trying to archive it, so in total
+the file is read <strong>twice</strong>. 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.
+
+
+</p>
+
+<a name="IDX401"></a>
+<p>When using ‘<samp>POSIX</samp>’ archive format,
<acronym>GNU</acronym> <code>tar</code> is able to store
+sparse files using in three distinct ways, called <em>sparse
+formats</em>. A sparse format is identified by its <em>number</em>,
+consisting, as usual of two decimal numbers, delimited by a dot. By
+default, format ‘<samp>1.0</samp>’ is used. If, for some reason,
you wish to
+use an earlier format, you can select it using
+‘<samp>--sparse-version</samp>’ option.
+</p>
+<dl compact="compact">
+<dd><a name="IDX402"></a>
+</dd>
+<dt> ‘<samp>--sparse-version=<var>version</var></samp>’</dt>
+<dd>
+<p>Select the format to store sparse files in. Valid <var>version</var> values
+are: ‘<samp>0.0</samp>’, ‘<samp>0.1</samp>’ and
‘<samp>1.0</samp>’. See section <a href="#SEC165">Storing Sparse
Files</a>,
+for a detailed description of each format.
+</p></dd>
+</dl>
+
+<p>Using ‘<samp>--sparse-format</samp>’ option implies
‘<samp>--sparse</samp>’.
+</p>
+<hr size="6">
+<a name="Attributes"></a>
+<a name="SEC128"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC127" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 8.2 Handling File Attributes </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>When <code>tar</code> reads files, it updates their access times. To
+avoid this, use the ‘<samp>--atime-preserve[=METHOD]</samp>’
option, which can either
+reset the access time retroactively or avoid changing it in the first
+place.
+</p>
+<p>Handling of file attributes
+</p>
+<dl compact="compact">
+<dd><a name="IDX403"></a>
+</dd>
+<dt> ‘<samp>--atime-preserve</samp>’</dt>
+<dt> ‘<samp>--atime-preserve=replace</samp>’</dt>
+<dt> ‘<samp>--atime-preserve=system</samp>’</dt>
+<dd><p>Preserve the access times of files that are read. This works only for
+files that you own, unless you have superuser privileges.
+</p>
+<p>‘<samp>--atime-preserve=replace</samp>’ 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
+(see section <a href="#SEC88">Using <code>tar</code> to Perform Incremental
Dumps</a>), and it can set access or data modification times
+incorrectly if other programs access the file while <code>tar</code> is
+running.
+</p>
+<p>‘<samp>--atime-preserve=system</samp>’ 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 <code>tar</code> knows for sure it won't work, it
+complains right away.
+</p>
+<p>Currently ‘<samp>--atime-preserve</samp>’ with no operand
defaults to
+‘<samp>--atime-preserve=replace</samp>’, but this is intended to
change to
+‘<samp>--atime-preserve=system</samp>’ when the latter is
better-supported.
+</p>
+<a name="IDX404"></a>
+</dd>
+<dt> ‘<samp>-m</samp>’</dt>
+<dt> ‘<samp>--touch</samp>’</dt>
+<dd><p>Do not extract data modification time.
+</p>
+<p>When this option is used, <code>tar</code> 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.
+</p>
+<p>This option is meaningless with ‘<samp>--list</samp>’
(‘<samp>-t</samp>’).
+</p>
+<a name="IDX405"></a>
+</dd>
+<dt> ‘<samp>--same-owner</samp>’</dt>
+<dd><p>Create extracted files with the same ownership they have in the
+archive.
+</p>
+<p>This is the default behavior for the superuser,
+so this option is meaningful only for non-root users, when <code>tar</code>
+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</code> or <code>sgid</code> attributes of
+files are easily and silently lost when files are given away.
+</p>
+<p>When writing an archive, <code>tar</code> writes the user id and user name
+separately. If it can't find a user name (because the user id is not
+in ‘<tt>/etc/passwd</tt>’), then it does not write one. When
restoring,
+it tries to look the name (if one was written) up in
+‘<tt>/etc/passwd</tt>’. If it fails, then it uses the user id
stored in
+the archive instead.
+</p>
+<a name="IDX406"></a>
+</dd>
+<dt> ‘<samp>--no-same-owner</samp>’</dt>
+<dt> ‘<samp>-o</samp>’</dt>
+<dd><p>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.
+</p>
+<a name="IDX407"></a>
+</dd>
+<dt> ‘<samp>--numeric-owner</samp>’</dt>
+<dd><p>The ‘<samp>--numeric-owner</samp>’ 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.
+</p>
+<p>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.
+</p>
+<p>The numeric ids are <em>always</em> saved into <code>tar</code> archives.
+The identifying names are added at create time when provided by the
+system, unless ‘<samp>--old-archive</samp>’
(‘<samp>-o</samp>’) 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.
+</p>
+<p>When making a <code>tar</code> 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
+<code>tar</code> archive out of this directory, before cleaning
+everything out. Of course, we could add a lot of options to
+<acronym>GNU</acronym> <code>tar</code> for fine tuning permissions and
ownership.
+This is not the good way, I think. <acronym>GNU</acronym> <code>tar</code> is
+already crowded with options and moreover, the approach just explained
+gives you a great deal of control already.
+</p>
+<a name="IDX408"></a>
+<a name="IDX409"></a>
+</dd>
+<dt> ‘<samp>-p</samp>’</dt>
+<dt> ‘<samp>--same-permissions</samp>’</dt>
+<dt> ‘<samp>--preserve-permissions</samp>’</dt>
+<dd><p>Extract all protection information.
+</p>
+<p>This option causes <code>tar</code> 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</code> setting limits the permissions
+on extracted files. This option is by default enabled when
+<code>tar</code> is executed by a superuser.
+</p>
+
+<p>This option is meaningless with ‘<samp>--list</samp>’
(‘<samp>-t</samp>’).
+</p>
+<a name="IDX410"></a>
+</dd>
+<dt> ‘<samp>--preserve</samp>’</dt>
+<dd><p>Same as both ‘<samp>--same-permissions</samp>’ and
‘<samp>--same-order</samp>’.
+</p>
+<p>The ‘<samp>--preserve</samp>’ option has no equivalent short
option name.
+It is equivalent to ‘<samp>--same-permissions</samp>’ plus
‘<samp>--same-order</samp>’.
+</p>
+
+
+
+
+</dd>
+</dl>
+
+<hr size="6">
+<a name="Portability"></a>
+<a name="SEC129"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC128" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC130" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 8.3 Making <code>tar</code> Archives More Portable </h2>
+
+<p>Creating a <code>tar</code> archive on a particular system that is meant to
be
+useful later on many other machines and with other versions of <code>tar</code>
+is more challenging than you might think. <code>tar</code> 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 <code>tar</code>
+archives more portable.
+</p>
+<p>One golden rule is simplicity. For example, limit your <code>tar</code>
+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.
+</p>
+
+
+
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC130">8.3.1 Portable
Names</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC131">8.3.2 Symbolic
Links</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC132">8.3.3 Old V7
Archives</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC133">8.3.4 Ustar Archive
Format</a></td><td> </td><td align="left" valign="top">
Ustar Archives
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC134">8.3.5
<acronym>GNU</acronym> and old <acronym>GNU</acronym> <code>tar</code>
format</a></td><td> </td><td align="left" valign="top">
GNU and old GNU format archives.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC135">8.3.6
<acronym>GNU</acronym> <code>tar</code> and <acronym>POSIX</acronym>
<code>tar</code></a></td><td> </td><td align="left" valign="top">
<acronym>POSIX</acronym> archives
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC137">8.3.7 Checksumming
Problems</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC138">8.3.8 Large or Negative
Values</a></td><td> </td><td align="left" valign="top"> Large
files, negative time stamps, etc.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC139">8.3.9 How to Extract
GNU-Specific Data Using Other <code>tar</code>
Implementations</a></td><td> </td><td align="left"
valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Portable-Names"></a>
+<a name="SEC130"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC129" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC131" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.1 Portable Names </h3>
+
+<p>Use portable file and member names. A name is portable if it contains
+only ASCII letters and digits, ‘<samp>/</samp>’,
‘<samp>.</samp>’, ‘<samp>_</samp>’, and
+‘<samp>-</samp>’; it cannot be empty, start with
‘<samp>-</samp>’ or ‘<samp>//</samp>’, or
+contain ‘<samp>/-</samp>’. Avoid deep directory nesting. For
portability to
+old Unix hosts, limit your file name components to 14 characters or
+less.
+</p>
+<p>If you intend to have your <code>tar</code> archives to be read under
+MSDOS, you should not rely on case distinction for file names, and you
+might use the <acronym>GNU</acronym> <code>doschk</code> program for helping
you
+further diagnosing illegal MSDOS names, which are even more limited
+than System V's.
+</p>
+<hr size="6">
+<a name="dereference"></a>
+<a name="SEC131"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC130" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC132" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.2 Symbolic Links </h3>
+
+<p>Normally, when <code>tar</code> archives a symbolic link, it writes a
+block to the archive naming the target of the link. In that way, the
+<code>tar</code> archive is a faithful record of the file system contents.
+‘<samp>--dereference</samp>’ (‘<samp>-h</samp>’) is
used with ‘<samp>--create</samp>’ (‘<samp>-c</samp>’),
and causes
+<code>tar</code> to archive the files symbolic links point to, instead of
+the links themselves. When this option is used, when <code>tar</code>
+encounters a symbolic link, it will archive the linked-to file,
+instead of simply recording the presence of a symbolic link.
+</p>
+<p>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 <code>tar</code>, an extracted file
+might be linked to a file name that no longer exists in the file
+system.
+</p>
+<p>If a linked-to file is encountered again by <code>tar</code> while creating
+the same archive, an entire second copy of it will be stored. (This
+<em>might</em> be considered a bug.)
+</p>
+<p>So, for portable archives, do not archive symbolic links as such,
+and use ‘<samp>--dereference</samp>’
(‘<samp>-h</samp>’): many systems do not support
+symbolic links, and moreover, your distribution might be unusable if
+it contains unresolved symbolic links.
+</p>
+<hr size="6">
+<a name="old"></a>
+<a name="SEC132"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC131" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC133" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.3 Old V7 Archives </h3>
+
+<p>Certain old versions of <code>tar</code> cannot handle additional
+information recorded by newer <code>tar</code> programs. To create an
+archive in V7 format (not ANSI), which can be read by these old
+versions, specify the ‘<samp>--format=v7</samp>’ option in
+conjunction with the ‘<samp>--create</samp>’
(‘<samp>-c</samp>’) (<code>tar</code> also
+accepts ‘<samp>--portability</samp>’ or
‘<samp>--old-archive</samp>’ for this
+option). When you specify it,
+<code>tar</code> 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.
+</p>
+<p>When updating an archive, do not use ‘<samp>--format=v7</samp>’
+unless the archive was created using this option.
+</p>
+<p>In most cases, a <em>new</em> format archive can be read by an <em>old</em>
+<code>tar</code> program without serious trouble, so this option should
+seldom be needed. On the other hand, most modern <code>tar</code>s are
+able to read old format archives, so it might be safer for you to
+always use ‘<samp>--format=v7</samp>’ for your distributions.
Notice,
+however, that ‘<samp>ustar</samp>’ format is a better alternative,
as it is
+free from many of ‘<samp>v7</samp>’'s drawbacks.
+</p>
+<hr size="6">
+<a name="ustar"></a>
+<a name="SEC133"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC132" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC134" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.4 Ustar Archive Format </h3>
+
+<p>Archive format defined by <acronym>POSIX</acronym>.1-1988 specification is
called
+<code>ustar</code>. Although it is more flexible than the V7 format, it
+still has many restrictions (See section <a href="#SEC124">ustar</a>, for the
detailed
+description of <code>ustar</code> format). Along with V7 format,
+<code>ustar</code> format is a good choice for archives intended to be read
+with other implementations of <code>tar</code>.
+</p>
+<p>To create archive in <code>ustar</code> format, use
‘<samp>--format=ustar</samp>’
+option in conjunction with the ‘<samp>--create</samp>’
(‘<samp>-c</samp>’).
+</p>
+<hr size="6">
+<a name="gnu"></a>
+<a name="SEC134"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC133" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC135" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.5 <acronym>GNU</acronym> and old
<acronym>GNU</acronym> <code>tar</code> format </h3>
+
+<p><acronym>GNU</acronym> <code>tar</code> was based on an early draft of the
+<acronym>POSIX</acronym> 1003.1 <code>ustar</code> standard.
<acronym>GNU</acronym> extensions to
+<code>tar</code>, such as the support for file names longer than 100
+characters, use portions of the <code>tar</code> header record which were
+specified in that <acronym>POSIX</acronym> draft as unused. Subsequent
changes in
+<acronym>POSIX</acronym> have allocated the same parts of the header record for
+other purposes. As a result, <acronym>GNU</acronym> <code>tar</code> format is
+incompatible with the current <acronym>POSIX</acronym> specification, and with
+<code>tar</code> programs that follow it.
+</p>
+<p>In the majority of cases, <code>tar</code> will be configured to create
+this format by default. This will change in the future releases, since
+we plan to make ‘<samp>POSIX</samp>’ format the default.
+</p>
+<p>To force creation a <acronym>GNU</acronym> <code>tar</code> archive, use
option
+‘<samp>--format=gnu</samp>’.
+</p>
+<hr size="6">
+<a name="posix"></a>
+<a name="SEC135"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC134" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC136" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.6 <acronym>GNU</acronym> <code>tar</code> and
<acronym>POSIX</acronym> <code>tar</code> </h3>
+
+<p>Starting from version 1.14 <acronym>GNU</acronym> <code>tar</code> features
full support for
+<acronym>POSIX.1-2001</acronym> archives.
+</p>
+<p>A <acronym>POSIX</acronym> conformant archive will be created if
<code>tar</code>
+was given ‘<samp>--format=posix</samp>’
(‘<samp>--format=pax</samp>’) option. No
+special option is required to read and extract from a <acronym>POSIX</acronym>
+archive.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC136">8.3.6.1 Controlling
Extended Header Keywords</a></td><td> </td><td align="left"
valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="PAX-keywords"></a>
+<a name="SEC136"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC135" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC137" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC135" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="subsubsection"> 8.3.6.1 Controlling Extended Header Keywords </h4>
+
+<dl compact="compact">
+<dd><a name="IDX411"></a>
+</dd>
+<dt> ‘<samp>--pax-option=<var>keyword-list</var></samp>’</dt>
+<dd><p>Handle keywords in <acronym>PAX</acronym> extended headers. This
option is
+equivalent to ‘<samp>-o</samp>’ option of the <code>pax</code>
utility.
+</p></dd>
+</dl>
+
+<p><var>Keyword-list</var> is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+</p>
+<dl compact="compact">
+<dt> <code>delete=<var>pattern</var></code></dt>
+<dd><p>When used with one of archive-creation commands,
+this option instructs <code>tar</code> to omit from extended header records
+that it produces any keywords matching the string <var>pattern</var>.
+</p>
+<p>When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given <var>pattern</var> in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in <acronym>POSIX 1003.2</acronym>, 3.13
+(see section <a href="#SEC104">Wildcards Patterns and Matching</a>). For
example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">--pax-option
delete=security.*
+</pre></td></tr></table>
+
+<p>would suppress security-related information.
+</p>
+</dd>
+<dt> <code>exthdr.name=<var>string</var></code></dt>
+<dd>
+<p>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</var> after making the following substitutions:
+</p>
+<table>
+<thead><tr><th><p> Meta-character </p></th><th><p> Replaced By
+</p></th></tr></thead>
+<tr><td><p> %d </p></td><td><p> The directory name of the file, equivalent to
the
+result of the <code>dirname</code> utility on the translated pathname.
+</p></td></tr>
+<tr><td><p> %f </p></td><td><p> The filename of the file, equivalent to the
result
+of the <code>basename</code> utility on the translated pathname.
+</p></td></tr>
+<tr><td><p> %p </p></td><td><p> The process ID of the <code>tar</code>
process.
+</p></td></tr>
+<tr><td><p> %% </p></td><td><p> A ‘<samp>%</samp>’ character.
+</p></td></tr>
+</table>
+
+<p>Any other ‘<samp>%</samp>’ characters in <var>string</var>
produce undefined
+results.
+</p>
+<p>If no option ‘<samp>exthdr.name=string</samp>’ is specified,
<code>tar</code>
+will use the following default value:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">%d/PaxHeaders.%p/%f
+</pre></td></tr></table>
+
+</dd>
+<dt> <code>globexthdr.name=<var>string</var></code></dt>
+<dd><p>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</var>, after making
+the following substitutions:
+</p>
+<table>
+<thead><tr><th><p> Meta-character </p></th><th><p> Replaced By
+</p></th></tr></thead>
+<tr><td><p> %n </p></td><td><p> An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
+</p></td></tr>
+<tr><td><p> %p </p></td><td><p> The process ID of the <code>tar</code> process.
+</p></td></tr>
+<tr><td><p> %% </p></td><td><p> A ‘<samp>%</samp>’ character.
+</p></td></tr>
+</table>
+
+<p>Any other ‘<samp>%</samp>’ characters in <var>string</var>
produce undefined results.
+</p>
+<p>If no option ‘<samp>globexthdr.name=string</samp>’ is
specified, <code>tar</code>
+will use the following default value:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">$TMPDIR/GlobalHead.%p.%n
+</pre></td></tr></table>
+
+<p>where ‘<samp>$TMPDIR</samp>’ represents the value of the
<var>TMPDIR</var>
+environment variable. If <var>TMPDIR</var> is not set, <code>tar</code>
+uses ‘<samp>/tmp</samp>’.
+</p>
+</dd>
+<dt> <code><var>keyword</var>=<var>value</var></code></dt>
+<dd><p>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,
+<code>tar</code> will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+</p>
+</dd>
+<dt> <code><var>keyword</var>:=<var>value</var></code></dt>
+<dd><p>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
<var>keyword</var>=<var>value</var>
+form except that it creates no global extended header records.
+</p>
+<p>When used with one of archive-reading commands, <code>tar</code> 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">tar --format=posix
--create \
+ --file archive --pax-option gname:=user .
+</pre></td></tr></table>
+
+<p>the group name will be forced to a new value for all files
+stored in the archive.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Checksumming"></a>
+<a name="SEC137"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC136" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC138" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.7 Checksumming Problems </h3>
+
+<p>SunOS and HP-UX <code>tar</code> fail to accept archives created using
+<acronym>GNU</acronym> <code>tar</code> 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</acronym> <code>tar</code> uses
unsigned
+checksums while creating archives, as per <acronym>POSIX</acronym> standards.
On
+reading, <acronym>GNU</acronym> <code>tar</code> 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.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> compute checksums both ways, and
accept
+any on read, so <acronym>GNU</acronym> tar can read Sun tapes even with their
+wrong checksums. <acronym>GNU</acronym> <code>tar</code> produces the standard
+checksum, however, raising incompatibilities with Sun. That is to
+say, <acronym>GNU</acronym> <code>tar</code> has not been modified to
+<em>produce</em> incorrect archives to be read by buggy <code>tar</code>'s.
+I've been told that more recent Sun <code>tar</code> now read standard
+archives, so maybe Sun did a similar patch, after all?
+</p>
+<p>The story seems to be that when Sun first imported <code>tar</code>
+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</code>'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 <code>tar</code> archives to be compatible with Sun's.
+The current standards do not favor Sun <code>tar</code> format. In any
+case, it now falls on the shoulders of SunOS and HP-UX users to get
+a <code>tar</code> able to read the good archives they receive.
+</p>
+<hr size="6">
+<a name="Large-or-Negative-Values"></a>
+<a name="SEC138"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC137" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC139" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.8 Large or Negative Values </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>The above sections suggest to use ‘<samp>oldest
possible</samp>’ 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</acronym> <code>tar</code> 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 (see section <a
href="#SEC124">Controlling the Archive Format</a>) will
+help you to do so.
+</p>
+<p>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 <small>UTC</small>, you will have to chose between
<acronym>GNU</acronym> and
+<acronym>POSIX</acronym> archive formats. When considering which format to
+choose, bear in mind that the <acronym>GNU</acronym> format uses
+two's-complement base-256 notation to store values that do not fit
+into standard <acronym>ustar</acronym> range. Such archives can generally be
+read only by a <acronym>GNU</acronym> <code>tar</code> implementation.
Moreover, they sometimes
+cannot be correctly restored on another hosts even by <acronym>GNU</acronym>
<code>tar</code>. For
+example, using two's complement representation for negative time
+stamps that assumes a signed 32-bit <code>time_t</code> generates archives
+that are not portable to hosts with differing <code>time_t</code>
+representations.
+</p>
+<p>On the other hand, <acronym>POSIX</acronym> archives, generally speaking,
can
+be extracted by any tar implementation that understands older
+<acronym>ustar</acronym> format. The only exception are files larger than 8GB.
+</p>
+
+
+
+
+<hr size="6">
+<a name="Other-Tars"></a>
+<a name="SEC139"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC138" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC140" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 8.3.9 How to Extract GNU-Specific Data Using Other
<code>tar</code> Implementations </h3>
+
+<p>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 <code>tar</code> implementation or an older version of
+<acronym>GNU</acronym> <code>tar</code>. Of course your best bet is to have
<acronym>GNU</acronym> <code>tar</code> installed,
+but if it is for some reason impossible, this section will explain
+how to cope without it.
+</p>
+<p>When we speak about <em>GNU-specific</em> 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.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC140">8.3.9.1 Extracting Members
Split Between Volumes</a></td><td> </td><td align="left"
valign="top"> Members Split Between Volumes
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC141">8.3.9.2 Extracting Sparse
Members</a></td><td> </td><td align="left" valign="top"> Sparse
Members
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Split-Recovery"></a>
+<a name="SEC140"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC139" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC141" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC139" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="subsubsection"> 8.3.9.1 Extracting Members Split Between Volumes
</h4>
+
+<p>If a member is split between several volumes of an old GNU format archive
+most third party <code>tar</code> implementation will fail to extract
+it. To extract it, use <code>tarcat</code> program (see section <a
href="#SEC156">Concatenate Volumes into a Single Archive</a>).
+This program is available from
+<a
href="http://www.gnu.org/software/tar/utils/tarcat.html";><acronym>GNU</acronym>
<code>tar</code> home page</a>. It concatenates several archive volumes into a
single
+valid archive. For example, if you have three volumes named from
+‘<tt>vol-1.tar</tt>’ to ‘<tt>vol-2.tar</tt>’, you can
do the following to
+extract them using a third-party <code>tar</code>:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tarcat
vol-1.tar vol-2.tar vol-3.tar | tar xf -</kbd>
+</pre></td></tr></table>
+
+<a name="IDX412"></a>
+<p>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 <code>tar</code> 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:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">%d/GNUFileParts.%p/%f.%n
+</pre></td></tr></table>
+
+<p>where symbols preceeded by ‘<samp>%</samp>’ are <em>macro
characters</em> that
+have the following meaning:
+</p>
+<table>
+<thead><tr><th><p> Meta-character </p></th><th><p> Replaced By
+</p></th></tr></thead>
+<tr><td><p> %d </p></td><td><p> The directory name of the file, equivalent to
the
+result of the <code>dirname</code> utility on its full name.
+</p></td></tr>
+<tr><td><p> %f </p></td><td><p> The file name of the file, equivalent to the
result
+of the <code>basename</code> utility on its full name.
+</p></td></tr>
+<tr><td><p> %p </p></td><td><p> The process ID of the <code>tar</code>
process that
+created the archive.
+</p></td></tr>
+<tr><td><p> %n </p></td><td><p> Ordinal number of this particular part.
+</p></td></tr>
+</table>
+
+<p>For example, if, a file ‘<tt>var/longfile</tt>’ was split
during archive
+creation between three volumes, and the creator <code>tar</code> process
+had process ID ‘<samp>27962</samp>’, then the member names will be:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">var/longfile
+var/GNUFileParts.27962/longfile.1
+var/GNUFileParts.27962/longfile.2
+</pre></td></tr></table>
+
+<p>When you extract your archive using a third-party <code>tar</code>, 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>cd var</kbd>
+$ <kbd>cat GNUFileParts.27962/longfile.1 \
+ GNUFileParts.27962/longfile.2 >> longfile</kbd>
+$ rm -f GNUFileParts.27962
+</pre></td></tr></table>
+
+<p>Notice, that if the <code>tar</code> implementation you use supports PAX
+format archives, it will probably emit warnings about unknown keywords
+during extraction. They will lool like this:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">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.
+</pre></td></tr></table>
+
+<p>You can safely ignore these warnings.
+</p>
+<p>If your <code>tar</code> implementation is not PAX-aware, you will get
+more warnigns and more files generated on your disk, e.g.:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar xf
vol-1.tar</kbd>
+var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
+normal file
+Unexpected EOF in archive
+$ <kbd>tar xf vol-2.tar</kbd>
+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
+</pre></td></tr></table>
+
+<p>Ignore these warnings. The ‘<tt>PaxHeaders.*</tt>’ directories
created
+will contain files with <em>extended header keywords</em> describing the
+extracted files. You can delete them, unless they describe sparse
+members. Read further to learn more about them.
+</p>
+<hr size="6">
+<a name="Sparse-Recovery"></a>
+<a name="SEC141"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC140" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC142" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC139" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h4 class="subsubsection"> 8.3.9.2 Extracting Sparse Members </h4>
+
+<p>Any <code>tar</code> implementation will be able to extract sparse members
from a
+PAX archive. However, the extracted files will be <em>condensed</em>,
+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
+<em>holes</em>) back to their original locations, we call this process
+<em>expanding</em> a compressed sparse file.
+</p>
+<a name="IDX413"></a>
+<p>To expand a file, you will need a simple auxiliary program called
+<code>xsparse</code>. It is available in source form from
+<a
href="http://www.gnu.org/software/tar/utils/xsparse.html";><acronym>GNU</acronym>
<code>tar</code> home page</a>.
+</p>
+<a name="IDX414"></a>
+<p>Let's begin with archive members in <em>sparse format
+version 1.0</em><a name="DOCF18" href="#FOOT18">(18)</a>, 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 ‘<tt><var>dir</var>/<var>name</var></tt>’, then the
condensed file will be
+named
‘<tt><var>dir</var>/GNUSparseFile.<var>n</var>/<var>name</var></tt>’,
where
+<var>n</var> is a decimal number<a name="DOCF19" href="#FOOT19">(19)</a>.
+</p>
+<p>To expand a version 1.0 file, run <code>xsparse</code> as follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>xsparse
‘<tt>cond-file</tt>’</kbd>
+</pre></td></tr></table>
+
+<p>where ‘<tt>cond-file</tt>’ is the name of the condensed file.
The utility
+will deduce the name for the resulting expanded file using the
+following algorithm:
+</p>
+<ol>
+<li> If ‘<tt>cond-file</tt>’ does not contain any directories,
+‘<tt>../cond-file</tt>’ will be used;
+
+</li><li> If ‘<tt>cond-file</tt>’ has the form
+‘<tt><var>dir</var>/<var>t</var>/<var>name</var></tt>’, where both
<var>t</var> and <var>name</var>
+are simple names, with no ‘<samp>/</samp>’ characters in them, the
output file
+name will be ‘<tt><var>dir</var>/<var>name</var></tt>’.
+
+</li><li> Otherwise, if ‘<tt>cond-file</tt>’ has the form
+‘<tt><var>dir</var>/<var>name</var></tt>’, the output file name
will be
+‘<tt><var>name</var></tt>’.
+</li></ol>
+
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>xsparse
‘<tt>cond-file</tt>’</kbd>
+</pre></td></tr></table>
+
+<p>It is often a good idea to run <code>xsparse</code> in <em>dry run</em> 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 ‘<samp>-n</samp>’ command line argument:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>xsparse -n
/home/gray/GNUSparseFile.6058/sparsefile</kbd>
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Finished dry run
+</pre></td></tr></table>
+
+<p>To actually expand the file, you would run:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>xsparse
/home/gray/GNUSparseFile.6058/sparsefile</kbd>
+</pre></td></tr></table>
+
+<p>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 ‘<samp>-v</samp>’
option:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>xsparse -v
/home/gray/GNUSparseFile.6058/sparsefile</kbd>
+Reading v.1.0 sparse map
+Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
+`/home/gray/sparsefile'
+Done
+</pre></td></tr></table>
+
+<p>Additionally, if your <code>tar</code> implementation has extracted the
+<em>extended headers</em> for this file, you can instruct <code>xstar</code>
+to use them in order to verify the integrity of the expanded file.
+The option ‘<samp>-x</samp>’ sets the name of the extended header
file to
+use. Continuing our example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>xsparse -v -x
/home/gray/PaxHeaders.6058/sparsefile \
+ /home/gray/GNUSparseFile.6058/sparsefile</kbd>
+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
+</pre></td></tr></table>
+
+<p><a name="extracting-sparse-v_002e0_002ex"></a>
+<a name="IDX415"></a>
+<a name="IDX416"></a>
+An <em>extended header</em> is a special <code>tar</code> archive header
+that precedes an archive member and contains a set of
+<em>variables</em>, describing the member properties that cannot be
+stored in the standard <code>ustar</code> 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 see section <a
href="#SEC165">Storing Sparse Files</a>). So, for this format, the question
is: how to obtain
+extended headers from the archive?
+</p>
+<p>If you use a <code>tar</code> 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
+‘<tt><var>dir</var>/<var>name</var></tt>’, then the extended
header file will be
+named
‘<tt><var>dir</var>/PaxHeaders.<var>n</var>/<var>name</var></tt>’,
where
+<var>n</var> is an integer number.
+</p>
+<p>Things become more difficult if your <code>tar</code> implementation
+does support PAX headers, because in this case you will have to
+manually extract the headers. We recommend the following algorithm:
+</p>
+<ol>
+<li>
+Consult the documentation for your <code>tar</code> implementation for an
+option that will print <em>block numbers</em> along with the archive
+listing (analogous to <acronym>GNU</acronym> <code>tar</code>'s
‘<samp>-R</samp>’ option). For example,
+<code>star</code> has ‘<samp>-block-number</samp>’.
+
+</li><li>
+Obtain the verbose listing using the ‘<samp>block number</samp>’
option, and
+find the position of the sparse member in question and the member
+immediately following it. For example, running <code>star</code> on our
+archive we obtain:
+
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>star -t -v
-block-number -f arc.tar</kbd>
+…
+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
+…
+</pre></td></tr></table>
+
+<p>(as usual, ignore the warnings about unknown keywords.)
+</p>
+</li><li>
+Let <var>size</var> be the size of the sparse member, <var>Bs</var> be its
block number
+and <var>Bn</var> be the block number of the next member.
+Compute:
+
+<table><tr><td> </td><td><pre class="smallexample"><var>N</var> =
<var>Bs</var> - <var>Bn</var> - <var>size</var>/512 - 2
+</pre></td></tr></table>
+
+<p>This number gives the size of the extended header part in tar
<em>blocks</em>.
+In our example, this formula gives: <code>897 - 56 - 425984 / 512 - 2
+= 7</code>.
+</p>
+</li><li>
+Use <code>dd</code> to extract the headers:
+
+<table><tr><td> </td><td><pre class="smallexample"><kbd>dd
if=<var>archive</var> of=<var>hname</var> bs=512 skip=<var>Bs</var>
count=<var>N</var></kbd>
+</pre></td></tr></table>
+
+<p>where <var>archive</var> is the archive name, <var>hname</var> is a name of
the
+file to store the extended header in, <var>Bs</var> and <var>N</var> are
+computed in previous steps.
+</p>
+<p>In our example, this command will be
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>dd if=arc.tar
of=xhdr bs=512 skip=56 count=7</kbd>
+</pre></td></tr></table>
+</li></ol>
+
+<p>Finally, you can expand the condensed file, using the obtained header:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>xsparse -v -x
xhdr GNUSparseFile.6058/sparsefile</kbd>
+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,…
+Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
+Done
+</pre></td></tr></table>
+
+<hr size="6">
+<a name="cpio"></a>
+<a name="SEC142"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC141" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 8.4 Comparison of <code>tar</code> and <code>cpio</code>
</h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+
+
+
+
+<p>The <code>cpio</code> archive formats, like <code>tar</code>, 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</acronym> <code>cpio</code> can read and
write archives
+with arbitrary pathname lengths, but other <code>cpio</code> implementations
+may crash unexplainedly trying to read them.
+</p>
+<p><code>tar</code> handles symbolic links in the form in which it comes in
BSD;
+<code>cpio</code> 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 <code>cpio</code> 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 <code>cpio</code> that Berkeley picked up from AT&T and put
+into a later BSD release—I think I gave them my changes).
+</p>
+<p>(SVR4 does some funny stuff with <code>tar</code>; basically, its
<code>cpio</code>
+can handle <code>tar</code> format input, and write it on output, and it
+probably handles symbolic links. They may not have bothered doing
+anything to enhance <code>tar</code> as a result.)
+</p>
+<p><code>cpio</code> handles special files; traditional <code>tar</code>
doesn't.
+</p>
+<p><code>tar</code> comes with V7, System III, System V, and BSD source;
+<code>cpio</code> comes only with System III, System V, and later BSD
+(4.3-tahoe and later).
+</p>
+<p><code>tar</code>'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);
+<code>cpio</code>s 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
+<code>cpio</code>s, 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.
+</p>
+<p><code>tar</code>s 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 <em>only</em> one you can use to retrieve the file; <code>cpio</code>s
+way puts one copy for every link, but you can retrieve it using any
+of the names.
+</p>
+<blockquote><p>What type of check sum (if any) is used, and how is this
calculated.
+</p></blockquote>
+
+<p>See the attached manual pages for <code>tar</code> and <code>cpio</code>
format.
+<code>tar</code> uses a checksum which is the sum of all the bytes in the
+<code>tar</code> header for a file; <code>cpio</code> uses no checksum.
+</p>
+<blockquote><p>If anyone knows why <code>cpio</code> was made when
<code>tar</code> was present
+at the unix scene,
+</p></blockquote>
+
+<p>It wasn't. <code>cpio</code> first showed up in PWB/UNIX 1.0; no
+generally-available version of UNIX had <code>tar</code> at the time. I don't
+know whether any version that was generally available <em>within AT&T</em>
+had <code>tar</code>, or, if so, whether the people within AT&T who did
+<code>cpio</code> knew about it.
+</p>
+<p>On restore, if there is a corruption on a tape <code>tar</code> will stop at
+that point, while <code>cpio</code> will skip over it and try to restore the
+rest of the files.
+</p>
+<p>The main difference is just in the command syntax and header format.
+</p>
+<p><code>tar</code> is a little more tape-oriented in that everything is
blocked
+to start on a record boundary.
+</p>
+<blockquote><p>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.)
+</p></blockquote>
+
+<p>Theoretically it should be easier under <code>tar</code> since the blocking
+lets you find a header with some variation of ‘<samp>dd
skip=<var>nn</var></samp>’.
+However, modern <code>cpio</code>'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.
+</p>
+<blockquote><p>If anyone knows why <code>cpio</code> was made when
<code>tar</code> was present
+at the unix scene, please tell me about this too.
+</p></blockquote>
+
+<p>Probably because it is more media efficient (by not blocking everything
+and using only the space needed for the headers where <code>tar</code>
+always uses 512 bytes per file header) and it knows how to archive
+special files.
+</p>
+<p>You might want to look at the freely available alternatives. The
+major ones are <code>afio</code>, <acronym>GNU</acronym> <code>tar</code>, and
+<code>pax</code>, each of which have their own extensions with some
+backwards compatibility.
+</p>
+<p>Sparse files were <code>tar</code>red as sparse files (which you can
+easily test, because the resulting archive gets smaller, and
+<acronym>GNU</acronym> <code>cpio</code> can no longer read it).
+</p>
+<hr size="6">
+<a name="Media"></a>
+<a name="SEC143"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC142" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC144" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="chapter"> 9. Tapes and Other Archive Media </h1>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>A few special cases about tape handling warrant more detailed
+description. These special cases are discussed below.
+</p>
+<p>Many complexities surround the use of <code>tar</code> on tape drives.
Since
+the creation and manipulation of archives located on magnetic tape was
+the original purpose of <code>tar</code>, it contains many features making
+such manipulation easier.
+</p>
+<p>Archives are usually written on dismountable media—tape cartridges,
+mag tapes, or floppy disks.
+</p>
+<p>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.
+</p>
+<p>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 <em>error
+count</em> (number of non-usable bits) of more than 10k.
+</p>
+<p>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.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC144">9.1 Device Selection and
Switching</a></td><td> </td><td align="left" valign="top">
Device selection and switching
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC145">9.2 The Remote Tape
Server</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC146">9.3 Some Common Problems
and their Solutions</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC147">9.4
Blocking</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC150">9.5 Many Archives on One
Tape</a></td><td> </td><td align="left" valign="top">
Many archives on one tape
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC153">9.6 Using Multiple
Tapes</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC157">9.7 Including a Label in
the Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC158">9.8 Verifying Data as It
is Stored</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC159">9.9 Write
Protection</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Device"></a>
+<a name="SEC144"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC143" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC145" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.1 Device Selection and Switching </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<dl compact="compact">
+<dt> ‘<samp>-f [<var>hostname</var>:]<var>file</var></samp>’</dt>
+<dt>
‘<samp>--file=[<var>hostname</var>:]<var>file</var></samp>’</dt>
+<dd><p>Use archive file or device <var>file</var> on <var>hostname</var>.
+</p></dd>
+</dl>
+
+<p>This option is used to specify the file name of the archive <code>tar</code>
+works on.
+</p>
+<p>If the file name is ‘<samp>-</samp>’, <code>tar</code> reads
the archive from standard
+input (when listing or extracting), or writes it to standard output
+(when creating). If the ‘<samp>-</samp>’ file name is given when
updating an
+archive, <code>tar</code> will read the original archive from its standard
+input, and will write the entire new archive to its standard output.
+</p>
+<p>If the file name contains a ‘<samp>:</samp>’, it is interpreted
as
+‘<samp>hostname:file name</samp>’. If the <var>hostname</var>
contains an <em>at</em>
+sign (‘<samp>@</samp>’), it is treated as
‘<samp>address@hidden:file name</samp>’. In
+either case, <code>tar</code> will invoke the command <code>rsh</code> (or
+<code>remsh</code>) to start up an <code>/usr/libexec/rmt</code> on the remote
+machine. If you give an alternate login name, it will be given to the
+<code>rsh</code>.
+Naturally, the remote machine must have an executable
+<code>/usr/libexec/rmt</code>. This program is free software from the
+University of California, and a copy of the source code can be found
+with the sources for <code>tar</code>; it's compiled and installed by default.
+The exact path to this utility is determined when configuring the package.
+It is ‘<tt><var>prefix</var>/libexec/rmt</tt>’, where
<var>prefix</var> stands for
+your installation prefix. This location may also be overridden at
+runtime by using ‘<samp>rmt-command=<var>command</var></samp>’
option (See section <a href="#SEC42">—rmt-command</a>, for detailed
description of this option. See section <a href="#SEC145">The Remote Tape
Server</a>, for the description of <code>rmt</code> command).
+</p>
+<p>If this option is not given, but the environment variable <code>TAPE</code>
+is set, its value is used; otherwise, old versions of <code>tar</code>
+used a default archive name (which was picked when <code>tar</code> was
+compiled). The default is normally set up to be the <em>first</em> tape
+drive or other transportable I/O medium on the system.
+</p>
+<p>Starting with version 1.11.5, <acronym>GNU</acronym> <code>tar</code> 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 <em>most</em> actual usages of
+<code>tar</code> are done with pipes or disks, not really tapes,
+cartridges or diskettes.
+</p>
+<p>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</samp>’ as a
default, but this
+is <em>also</em> 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.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> 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</samp>’ in
+‘<tt><sys/mtio.h></tt>’.
+</p>
+<dl compact="compact">
+<dd><a name="IDX417"></a>
+</dd>
+<dt> ‘<samp>--force-local</samp>’</dt>
+<dd><p>Archive file is local even if it contains a colon.
+</p>
+<a name="IDX418"></a>
+</dd>
+<dt> ‘<samp>--rsh-command=<var>command</var></samp>’</dt>
+<dd><p>Use remote <var>command</var> instead of <code>rsh</code>. This option
exists
+so that people who use something other than the standard <code>rsh</code>
+(e.g., a Kerberized <code>rsh</code>) can access a remote device.
+</p>
+<p>When this command is not used, the shell command found when
+the <code>tar</code> program was installed is used instead. This is
+the first found of ‘<tt>/usr/ucb/rsh</tt>’,
‘<tt>/usr/bin/remsh</tt>’,
+‘<tt>/usr/bin/rsh</tt>’, ‘<tt>/usr/bsd/rsh</tt>’ or
‘<tt>/usr/bin/nsh</tt>’.
+The installer may have overridden this by defining the environment
+variable <code>RSH</code> <em>at installation time</em>.
+</p>
+</dd>
+<dt> ‘<samp>-[0-7][lmh]</samp>’</dt>
+<dd><p>Specify drive and density.
+</p>
+<a name="IDX419"></a>
+</dd>
+<dt> ‘<samp>-M</samp>’</dt>
+<dt> ‘<samp>--multi-volume</samp>’</dt>
+<dd><p>Create/list/extract multi-volume archive.
+</p>
+<p>This option causes <code>tar</code> to write a <em>multi-volume</em>
archive—one
+that may be larger than will fit on the medium used to hold it.
+See section <a href="#SEC154">Archives Longer than One Tape or Disk</a>.
+</p>
+<a name="IDX420"></a>
+</dd>
+<dt> ‘<samp>-L <var>num</var></samp>’</dt>
+<dt> ‘<samp>--tape-length=<var>num</var></samp>’</dt>
+<dd><p>Change tape after writing <var>num</var> x 1024 bytes.
+</p>
+<p>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.
+</p>
+<a name="IDX421"></a>
+<a name="IDX422"></a>
+</dd>
+<dt> ‘<samp>-F <var>file</var></samp>’</dt>
+<dt> ‘<samp>--info-script=<var>file</var></samp>’</dt>
+<dt> ‘<samp>--new-volume-script=<var>file</var></samp>’</dt>
+<dd><p>Execute ‘<tt>file</tt>’ at end of each tape. This implies
+‘<samp>--multi-volume</samp>’ (‘<samp>-M</samp>’).
See <a href="#info_002dscript">info-script</a>, for a detailed
+description of this option.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Remote-Tape-Server"></a>
+<a name="SEC145"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC144" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC146" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.2 The Remote Tape Server </h2>
+
+<p>In order to access the tape drive on a remote machine, <code>tar</code>
+uses the remote tape server written at the University of California at
+Berkeley. The remote tape server must be installed as
+‘<tt><var>prefix</var>/libexec/rmt</tt>’ on any machine whose tape
drive you
+want to use. <code>tar</code> calls <code>rmt</code> by running an
+<code>rsh</code> or <code>remsh</code> to the remote machine, optionally
+using a different login name if one is supplied.
+</p>
+<p>A copy of the source for the remote tape server is provided. It is
+Copyright © 1983 by the Regents of the University of
+California, but can be freely distributed. It is compiled and
+installed by default.
+</p>
+<a name="IDX423"></a>
+<p>Unless you use the ‘<samp>--absolute-names</samp>’
(‘<samp>-P</samp>’) option,
+<acronym>GNU</acronym> <code>tar</code> will not allow you to create an
archive that contains
+absolute file names (a file name beginning with ‘<samp>/</samp>’.)
If you try,
+<code>tar</code> will automatically remove the leading
‘<samp>/</samp>’ from the
+file names it stores in the archive. It will also type a warning
+message telling you what it is doing.
+</p>
+<p>When reading an archive that was created with a different
+<code>tar</code> program, <acronym>GNU</acronym> <code>tar</code> 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 <code>tar</code> tape to an operator to restore;
+the operator used Sun <code>tar</code> instead of <acronym>GNU</acronym>
<code>tar</code>,
+and the result was that it replaced large portions of
+our ‘<tt>/bin</tt>’ and friends with versions from the tape;
needless to
+say, we were unhappy about having to recover the file system from
+backup tapes.
+</p>
+<p>For example, if the archive contained a file
‘<tt>/usr/bin/computoy</tt>’,
+<acronym>GNU</acronym> <code>tar</code> would extract the file to
‘<tt>usr/bin/computoy</tt>’,
+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 /</samp>’ before extracting
the files
+from the archive, or you should either use the
‘<samp>--absolute-names</samp>’
+option, or use the command ‘<samp>tar -C / …</samp>’.
+</p>
+<a name="IDX424"></a>
+<p>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.
+</p>
+<p>In order to update an archive, <code>tar</code> 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</samp>’),
+and industry-standard 9-track magnetic tape (or any other kind of tape
+that can be backspaced with the <code>MTIOCTOP</code> <code>ioctl</code>.
+</p>
+<p>This means that the ‘<samp>--append</samp>’,
‘<samp>--concatenate</samp>’, and
+‘<samp>--delete</samp>’ 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.
+</p>
+<p>Some other media can be backspaced, and <code>tar</code> will work on them
+once <code>tar</code> is modified to do so.
+</p>
+<p>Archives created with the ‘<samp>--multi-volume</samp>’,
‘<samp>--label</samp>’, and
+‘<samp>--incremental</samp>’ (‘<samp>-G</samp>’)
options may not be readable by other version
+of <code>tar</code>. In particular, restoring a file that was split over
+a volume boundary will require some careful work with <code>dd</code>, if
+it can be done at all. Other versions of <code>tar</code> may also create
+an empty file whose name is that of the volume header. Some versions
+of <code>tar</code> may create normal files instead of directories archived
+with the ‘<samp>--incremental</samp>’
(‘<samp>-G</samp>’) option.
+</p>
+<hr size="6">
+<a name="Common-Problems-and-Solutions"></a>
+<a name="SEC146"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC145" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC147" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.3 Some Common Problems and their Solutions </h2>
+
+
+<table><tr><td> </td><td><pre class="format">errors from system:
+permission denied
+no such file or directory
+not owner
+
+errors from <code>tar</code>:
+directory checksum error
+header format error
+
+errors from media/system:
+i/o error
+device busy
+</pre></td></tr></table>
+
+
+<hr size="6">
+<a name="Blocking"></a>
+<a name="SEC147"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC146" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC148" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.4 Blocking </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p><em>Block</em> and <em>record</em> 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.
+</p>
+<p>John Gilmore, the writer of the public domain <code>tar</code> from which
+<acronym>GNU</acronym> <code>tar</code> was originally derived, wrote (June
1995):
+</p>
+<blockquote><p>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</code> (fixed sized records), <code>V</code>
(variable
+sized records), <code>FB</code> (fixed blocked: fixed size records,
<var>n</var>
+to a block), <code>VB</code> (variable size records, <var>n</var> to a block),
+<code>VSB</code> (variable spanned blocked: variable sized records that can
+occupy more than one block), etc. The <code>JCL</code> ‘<samp>DD
RECFORM=</samp>’
+parameter specified this to the operating system.
+</p>
+<p>The Unix man page on <code>tar</code> was totally confused about this.
+When I wrote <code>PD TAR</code>, I used the historically correct terminology
+(<code>tar</code> writes data records, which are grouped into blocks).
+It appears that the bogus terminology made it into <acronym>POSIX</acronym>
(no surprise
+here), and now François has migrated that terminology back
+into the source code too.
+</p></blockquote>
+
+<p>The term <em>physical block</em> 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 <em>block</em> usually refers to
+a disk physical block, <em>assuming</em> that each disk block is 512
+bytes in length. It is true that some disk devices have different
+physical blocks, but <code>tar</code> ignore these differences in its own
+format, which is meant to be portable, so a <code>tar</code> block is always
+512 bytes in length, and <em>block</em> always mean a <code>tar</code> block.
+The term <em>logical block</em> 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</acronym> <code>tar</code>.
+</p>
+<p>The term <em>physical record</em> is another way to speak of a physical
+block, those two terms are somewhat interchangeable. In this manual,
+the term <em>record</em> usually refers to a tape physical block,
+<em>assuming</em> that the <code>tar</code> archive is kept on magnetic tape.
+It is true that archives may be put on disk or used with pipes,
+but nevertheless, <code>tar</code> tries to read and write the archive one
+<em>record</em> 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 <em>reblocking</em>, or
+more simply, <em>blocking</em>. The term <em>logical record</em> refers to
+the logical organization of many characters into something meaningful
+to the application. The term <em>unit record</em> 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 <em>record</em> in <acronym>GNU</acronym> <code>tar</code>.
+</p>
+<p>When writing to tapes, <code>tar</code> writes the contents of the archive
+in chunks known as <em>records</em>. To change the default blocking
+factor, use the
‘<samp>--blocking-factor=<var>512-size</var></samp>’
(‘<samp>-b
+<var>512-size</var></samp>’) option. Each record will then be composed
of
+<var>512-size</var> blocks. (Each <code>tar</code> block is 512 bytes.
+See section <a href="#SEC163">Basic Tar Format</a>.) 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.
+</p>
+<p>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.
+</p>
+<p>When reading an archive, <code>tar</code> 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, <code>tar</code> will
+print a message about a non-standard blocking factor, and then operate
+normally. On some tape devices, however, <code>tar</code> cannot figure
+out the record size itself. On most of those, you can specify a
+blocking factor (with ‘<samp>--blocking-factor</samp>’) larger
than the
+actual blocking factor, and then use the
‘<samp>--read-full-records</samp>’
+(‘<samp>-B</samp>’) option. (If you specify a blocking factor with
+‘<samp>--blocking-factor</samp>’ and don't use the
+‘<samp>--read-full-records</samp>’ option, then <code>tar</code>
will not
+attempt to figure out the recording size itself.) On some devices,
+you must always specify the record size exactly with
+‘<samp>--blocking-factor</samp>’ when reading, because
<code>tar</code> cannot
+figure it out. In any case, use ‘<samp>--list</samp>’
(‘<samp>-t</samp>’) before
+doing any extractions to see whether <code>tar</code> is reading the archive
+correctly.
+</p>
+<p><code>tar</code> 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. <code>tar</code> 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.
+</p>
+<p>In a standard <code>tar</code> file (no options), the block size is 512
+and the record size is 10240, for a blocking factor of 20. What the
+‘<samp>--blocking-factor</samp>’ 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.
+</p>
+<p>If you use a blocking factor larger than 20, older <code>tar</code>
+programs might not be able to read the archive, so we recommend this
+as a limit to use in practice. <acronym>GNU</acronym> <code>tar</code>,
however,
+will support arbitrarily large record sizes, limited only by the
+amount of virtual memory or the physical characteristics of the tape
+device.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC148">9.4.1 Format
Variations</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC149">9.4.2 The Blocking Factor
of an Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Format-Variations"></a>
+<a name="SEC148"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC147" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC149" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC147" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 9.4.1 Format Variations </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>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.
+</p>
+<p>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, <code>tar</code> uses
+default parameters. You cannot modify a compressed archive.
+If you create an archive with the ‘<samp>--blocking-factor</samp>’
option
+specified (see section <a href="#SEC149">The Blocking Factor of an
Archive</a>), you must specify that
+blocking-factor when operating on the archive. See section <a
href="#SEC124">Controlling the Archive Format</a>, for other
+examples of format parameter considerations.
+</p>
+<hr size="6">
+<a name="Blocking-Factor"></a>
+<a name="SEC149"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC148" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC150" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC147" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 9.4.2 The Blocking Factor of an Archive </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX425"></a>
+<p>The data in an archive is grouped into blocks, which are 512 bytes.
+Blocks are read and written in whole number multiples called
+<em>records</em>. The number of blocks in a record (i.e. the size of a
+record in units of 512 bytes) is called the <em>blocking factor</em>.
+The ‘<samp>--blocking-factor=<var>512-size</var></samp>’
(‘<samp>-b
+<var>512-size</var></samp>’) 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
--file=<var>archive-name</var></samp>’.
+This may not work on some devices.
+</p>
+<p>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 <code>tar</code> 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. See section <a href="#SEC17">How to Create
Archives</a>, for information on
+writing archives.
+</p>
+
+
+
+
+<p>Archives with blocking factors larger than 20 cannot be read
+by very old versions of <code>tar</code>, or by some newer versions
+of <code>tar</code> running on old machines with small address spaces.
+With <acronym>GNU</acronym> <code>tar</code>, 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.
+</p>
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">Cannot write to
/dev/dlt: Invalid argument
+</pre></td></tr></table>
+
+<p>In such cases, it sometimes happen that the <code>tar</code> bundled by
+the system is aware of block size idiosyncrasies, while <acronym>GNU</acronym>
<code>tar</code>
+requires an explicit specification for the block size,
+which it cannot guess. This yields some people to consider
+<acronym>GNU</acronym> <code>tar</code> is misbehaving, because by comparison,
+<cite>the bundle <code>tar</code> works OK</cite>. Adding <kbd>-b 256</kbd>,
+for example, might resolve the problem.
+</p>
+<p>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 ‘<samp>--list</samp>’ (‘<samp>-t</samp>’)
without specifying a blocking factor—<code>tar</code>
+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 ‘<samp>--read-full-records</samp>’
(‘<samp>-B</samp>’) 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</samp>’.
+See section <a href="#SEC23">How to List Archives</a>, for more information on
the ‘<samp>--list</samp>’ (‘<samp>-t</samp>’)
+operation. See section <a href="#SEC64">Options to Help Read Archives</a>,
for a more detailed explanation of that option.
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--blocking-factor=<var>number</var></samp>’</dt>
+<dt> ‘<samp>-b <var>number</var></samp>’</dt>
+<dd><p>Specifies the blocking factor of an archive. Can be used with any
+operation, but is usually not necessary with ‘<samp>--list</samp>’
(‘<samp>-t</samp>’).
+</p></dd>
+</dl>
+
+<p>Device blocking
+</p>
+<dl compact="compact">
+<dt> ‘<samp>-b <var>blocks</var></samp>’</dt>
+<dt> ‘<samp>--blocking-factor=<var>blocks</var></samp>’</dt>
+<dd><p>Set record size to <em><var>blocks</var> * 512</em> bytes.
+</p>
+<p>This option is used to specify a <em>blocking factor</em> for the archive.
+When reading or writing the archive, <code>tar</code>, will do reads and writes
+of the archive in records of <em><var>block</var>*512</em> 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, <code>tar</code>
+pads the archive out to the next record boundary.
+</p>
+<p>The default blocking factor is set when <code>tar</code> is compiled, and is
+typically 20. Blocking factors larger than 20 cannot be read by very
+old versions of <code>tar</code>, or by some newer versions of <code>tar</code>
+running on old machines with small address spaces.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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 switched…
+</p>
+<p>With <acronym>GNU</acronym> <code>tar</code> 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.
+</p>
+<p>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:
+</p><ul>
+<li>
+the archive is subject to a compression option,
+</li><li>
+the archive is not handled through standard input or output, nor
+redirected nor piped,
+</li><li>
+the archive is directly handled to a local disk, instead of any special
+device,
+</li><li>
+‘<samp>--blocking-factor</samp>’ is not explicitly specified on
the <code>tar</code>
+invocation.
+</li></ul>
+
+<p>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:
+</p>
+<ul>
+<li>
+<code>gzip</code> 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
+‘<samp><var>prog</var> -d</samp>’ 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.
+
+</li><li>
+<code>compress</code> does not show this problem, but as Jean-loup pointed
+out to Michael, ‘<samp>compress -d</samp>’ 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.
+
+</li><li>
+‘<samp>gzip -d -q</samp>’ will be silent about the trailing zeros
indeed,
+but will still return an exit status of 2 which tar reports in turn.
+<code>tar</code> might ignore the exit status returned, but I hate doing
+that, as it weakens the protection <code>tar</code> offers users against
+other possible problems at decompression time. If <code>gzip</code> was
+silently skipping trailing zeros <em>and</em> also avoiding setting the
+exit status in this innocuous case, that would solve this situation.
+
+</li><li>
+<code>tar</code> should become more solid at not stopping to read a pipe at
+the first null block encountered. This inelegantly breaks the pipe.
+<code>tar</code> should rather drain the pipe out before exiting itself.
+</li></ul>
+
+<a name="IDX426"></a>
+</dd>
+<dt> ‘<samp>-i</samp>’</dt>
+<dt> ‘<samp>--ignore-zeros</samp>’</dt>
+<dd><p>Ignore blocks of zeros in archive (means EOF).
+</p>
+<p>The ‘<samp>--ignore-zeros</samp>’
(‘<samp>-i</samp>’) option causes <code>tar</code> 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 <code>tar</code> to read the entire archive. This option is not on
+by default because many versions of <code>tar</code> write garbage after
+the zeroed blocks.
+</p>
+<p>Note that this option causes <code>tar</code> to read to the end of the
+archive file, which may sometimes avoid problems when multiple files
+are stored on a single physical tape.
+</p>
+<a name="IDX427"></a>
+</dd>
+<dt> ‘<samp>-B</samp>’</dt>
+<dt> ‘<samp>--read-full-records</samp>’</dt>
+<dd><p>Reblock as we read (for reading 4.2BSD pipes).
+</p>
+<p>If ‘<samp>--read-full-records</samp>’ is used, <code>tar</code>
+will not panic if an attempt to read a record from the archive does
+not return a full record. Instead, <code>tar</code> will keep reading
+until it has obtained a full
+record.
+</p>
+<p>This option is turned on by default when <code>tar</code> 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 <code>tar</code>
+requested. If this option was not used, <code>tar</code> would fail as
+soon as it read an incomplete record from the pipe.
+</p>
+<p>This option is also useful with the commands for updating an archive.
+</p>
+</dd>
+</dl>
+
+<p>Tape blocking
+</p>
+
+
+
+
+<a name="IDX428"></a>
+<a name="IDX429"></a>
+
+<p>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 <em>tape gap</em> 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.
+</p>
+<a name="IDX430"></a>
+<a name="IDX431"></a>
+<p>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. <code>tar</code> 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 (<kbd>-b 128</kbd>) 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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>I might also use ‘<samp>--number-blocks</samp>’ instead of
+‘<samp>--block-number</samp>’, so
‘<samp>--block</samp>’ will then expand to
+‘<samp>--blocking-factor</samp>’ unambiguously.
+</p>
+<hr size="6">
+<a name="Many"></a>
+<a name="SEC150"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC149" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC151" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.5 Many Archives on One Tape </h2>
+
+
+
+
+
+<p>Most tape devices have two entries in the ‘<tt>/dev</tt>’
directory, or
+entries that come in pairs, which differ only in the minor number for
+this device. Let's take for example ‘<tt>/dev/tape</tt>’, which
often
+points to the only or usual tape device of a given system. There might
+be a corresponding ‘<tt>/dev/nrtape</tt>’ or
‘<tt>/dev/ntape</tt>’. The simpler
+name is the <em>rewinding</em> version of the device, while the name
+having ‘<samp>nr</samp>’ in it is the <em>no rewinding</em>
version of the same
+device.
+</p>
+<p>A rewinding tape device will bring back the tape to its beginning point
+automatically when this device is opened or closed. Since <code>tar</code>
+opens the archive file before using it and closes it afterwards, this
+means that a simple:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cf
/dev/tape <var>directory</var></kbd>
+</pre></td></tr></table>
+
+<p>will reposition the tape to its beginning both prior and after saving
+<var>directory</var> contents to it, thus erasing prior tape contents and
+making it so that any subsequent write operation will destroy what has
+just been saved.
+</p>
+<a name="IDX432"></a>
+<p>So, a rewinding device is normally meant to hold one and only one file.
+If you want to put more than one <code>tar</code> 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 <em>cannot</em> be
+recovered.
+</p>
+<p>To save <var>directory-1</var> as a first archive at the beginning of a
+tape, and leave that tape ready for a second archive, you should use:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>mt -f
/dev/nrtape rewind</kbd>
+$ <kbd>tar cf /dev/nrtape <var>directory-1</var></kbd>
+</pre></td></tr></table>
+
+<a name="IDX433"></a>
+<p><em>Tape marks</em> 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 <code>tar</code> 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.
+</p>
+<p>So, you may now save <var>directory-2</var> as a second archive after the
+first on the same tape by issuing the command:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cf
/dev/nrtape <var>directory-2</var></kbd>
+</pre></td></tr></table>
+
+<p>and so on for all the archives you want to put on the same tape.
+</p>
+<p>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</var>, say, by using
+these commands:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>mt -f
/dev/nrtape rewind</kbd>
+$ <kbd>mt -f /dev/nrtape fsf 16</kbd>
+$ <kbd>tar cf /dev/nrtape <var>directory-17</var></kbd>
+</pre></td></tr></table>
+
+<p>In all the previous examples, we put aside blocking considerations, but
+you should do the proper things for that as well. See section <a
href="#SEC147">Blocking</a>.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC151">9.5.1 Tape Positions and
Tape Marks</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC152">9.5.2 The <code>mt</code>
Utility</a></td><td> </td><td align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Tape-Positioning"></a>
+<a name="SEC151"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC150" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC152" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC150" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 9.5.1 Tape Positions and Tape Marks </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>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 <em>tape marks</em> on the
+archive media. Tape drives write one tape mark between files,
+two at the end of all the file entries.
+</p>
+<p>If you think of data as a series of records "rrrr"'s, and tape
marks as
+"*"'s, a tape might look like the following:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
+</pre></td></tr></table>
+
+<p>Tape devices read and write tapes using a read/write <em>tape
+head</em>—a physical part of the device which can only access one
+point on the tape at a time. When you use <code>tar</code> 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</code> utility (see section <a href="#SEC152">The <code>mt</code>
Utility</a>). The <code>restore</code> script does
+that automatically (see section <a href="#SEC96">Using the Restore Script</a>).
+</p>
+<p>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:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
+</pre></td></tr></table>
+
+<hr size="6">
+<a name="mt"></a>
+<a name="SEC152"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC151" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC153" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC150" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 9.5.2 The <code>mt</code> Utility </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+
+
+
+<p>See section <a href="#SEC149">The Blocking Factor of an Archive</a>.
+</p>
+<p>You can use the <code>mt</code> 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.
+
+
+</p>
+
+<p>The syntax of the <code>mt</code> command is:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>mt [-f
<var>tapename</var>] <var>operation</var> [<var>number</var>]</kbd>
+</pre></td></tr></table>
+
+<p>where <var>tapename</var> is the name of the tape device, <var>number</var>
is
+the number of times an operation is performed (with a default of one),
+and <var>operation</var> is one of the following:
+</p>
+
+
+
+
+<dl compact="compact">
+<dt> ‘<samp>eof</samp>’</dt>
+<dt> ‘<samp>weof</samp>’</dt>
+<dd><p>Writes <var>number</var> tape marks at the current position on the tape.
+</p>
+</dd>
+<dt> ‘<samp>fsf</samp>’</dt>
+<dd><p>Moves tape position forward <var>number</var> files.
+</p>
+</dd>
+<dt> ‘<samp>bsf</samp>’</dt>
+<dd><p>Moves tape position back <var>number</var> files.
+</p>
+</dd>
+<dt> ‘<samp>rewind</samp>’</dt>
+<dd><p>Rewinds the tape. (Ignores <var>number</var>).
+</p>
+</dd>
+<dt> ‘<samp>offline</samp>’</dt>
+<dt> ‘<samp>rewoff1</samp>’</dt>
+<dd><p>Rewinds the tape and takes the tape device off-line. (Ignores
<var>number</var>).
+</p>
+</dd>
+<dt> ‘<samp>status</samp>’</dt>
+<dd><p>Prints status information about the tape unit.
+</p>
+</dd>
+</dl>
+
+
+
+
+
+<p>If you don't specify a <var>tapename</var>, <code>mt</code> uses the
environment
+variable <code>TAPE</code>; if <code>TAPE</code> is not set, <code>mt</code>
will use
+the default device specified in your ‘<tt>sys/mtio.h</tt>’ file
+(<code>DEFTAPE</code> variable). If this is not defined, the program will
+display a descriptive error message and exit with code 1.
+</p>
+<p><code>mt</code> returns a 0 exit status when the operation(s) were
+successful, 1 if the command was unrecognized, and 2 if an operation
+failed.
+</p>
+<hr size="6">
+<a name="Using-Multiple-Tapes"></a>
+<a name="SEC153"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC152" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC154" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.6 Using Multiple Tapes </h2>
+
+<p>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
+<code>tar</code> commands, but this can be inconvenient, particularly if you
+are using options like ‘<samp>--exclude=<var>pattern</var></samp>’
or dumping entire file systems.
+Therefore, <code>tar</code> provides a special mode for creating
+multi-volume archives.
+</p>
+<p><em>Multi-volume</em> archive is a single <code>tar</code> archive, stored
+on several media volumes of fixed size. Although in this section we will
+often call ‘<samp>volume</samp>’ a <em>tape</em>, 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.
+</p>
+<p>When creating a multi-volume arvhive, <acronym>GNU</acronym>
<code>tar</code> 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</acronym>
<code>tar</code> 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.
+</p>
+<p>Each volume is itself a valid <acronym>GNU</acronym> <code>tar</code>
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.
+</p>
+<p>Multi-volume archives suffer from several limitations. In particular,
+they cannot be compressed.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> is able to create multi-volume
archives of two formats
+(see section <a href="#SEC124">Controlling the Archive Format</a>):
‘<samp>GNU</samp>’ and ‘<samp>POSIX</samp>’.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC154">9.6.1 Archives Longer than
One Tape or Disk</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC155">9.6.2 Tape
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC156">9.6.3 Concatenate Volumes
into a Single Archive</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+</pre></th></tr></table>
+
+<hr size="6">
+<a name="Multi_002dVolume-Archives"></a>
+<a name="SEC154"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC153" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC155" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC153" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 9.6.1 Archives Longer than One Tape or Disk </h3>
+
+<p>To create an archive that is larger than will fit on a single unit of
+the media, use the ‘<samp>--multi-volume</samp>’
(‘<samp>-M</samp>’) option in conjunction with
+the ‘<samp>--create</samp>’ option (see section <a
href="#SEC17">How to Create Archives</a>). A <em>multi-volume</em>
+archive can be manipulated like any other archive (provided the
+‘<samp>--multi-volume</samp>’ option is specified), but is stored
on more
+than one tape or disk.
+</p>
+<p>When you specify ‘<samp>--multi-volume</samp>’,
<code>tar</code> 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.
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--multi-volume</samp>’</dt>
+<dt> ‘<samp>-M</samp>’</dt>
+<dd><p>Creates a multi-volume archive, when used in conjunction with
+‘<samp>--create</samp>’ (‘<samp>-c</samp>’). To
perform any other operation on a multi-volume
+archive, specify ‘<samp>--multi-volume</samp>’ in conjunction with
that
+operation.
+For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--multi-volume --file=/dev/tape <var>files</var></kbd>
+</pre></td></tr></table>
+</dd>
+</dl>
+
+<p>The method <code>tar</code> uses to detect end of tape is not perfect, and
+fails on some operating systems or on some devices. If <code>tar</code>
+cannot detect the end of the tape itself, you can use
+‘<samp>--tape-length</samp>’ option to inform it about the
capacity of the
+tape:
+</p>
+<p><a name="tape_002dlength"></a>
+</p><dl compact="compact">
+<dd><a name="IDX434"></a>
+</dd>
+<dt> ‘<samp>--tape-length=<var>size</var></samp>’</dt>
+<dt> ‘<samp>-L <var>size</var></samp>’</dt>
+<dd><p>Set maximum length of a volume. The <var>size</var> argument should
then
+be the usable size of the tape in units of 1024 bytes. This option
+selects ‘<samp>--multi-volume</samp>’ automatically. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--tape-length=41943040 --file=/dev/tape <var>files</var></kbd>
+</pre></td></tr></table>
+</dd>
+</dl>
+
+<p><a name="change-volume-prompt"></a>
+When <acronym>GNU</acronym> <code>tar</code> comes to the end of a storage
media, it asks you to
+change the volume. The built-in prompt for POSIX locale
+is<a name="DOCF20" href="#FOOT20">(20)</a>:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">Prepare volume
#<var>n</var> for `<var>archive</var>' and hit return:
+</pre></td></tr></table>
+
+<p>where <var>n</var> is the ordinal number of the volume to be created and
+<var>archive</var> is archive file or device name.
+</p>
+<p>When prompting for a new tape, <code>tar</code> accepts any of the following
+responses:
+</p>
+<dl compact="compact">
+<dt> <kbd>?</kbd></dt>
+<dd><p>Request <code>tar</code> to explain possible responses
+</p></dd>
+<dt> <kbd>q</kbd></dt>
+<dd><p>Request <code>tar</code> to exit immediately.
+</p></dd>
+<dt> <kbd>n <var>file-name</var></kbd></dt>
+<dd><p>Request <code>tar</code> to write the next volume on the file
<var>file-name</var>.
+</p></dd>
+<dt> <kbd>!</kbd></dt>
+<dd><p>Request <code>tar</code> to run a subshell. This option can be disabled
+by giving ‘<samp>--restrict</samp>’ command line option to
+<code>tar</code><a name="DOCF21" href="#FOOT21">(21)</a>.
+</p></dd>
+<dt> <kbd>y</kbd></dt>
+<dd><p>Request <code>tar</code> to begin writing the next volume.
+</p></dd>
+</dl>
+
+<p>(You should only type ‘<samp>y</samp>’ after you have changed
the tape;
+otherwise <code>tar</code> will write over the volume it just finished.)
+</p>
+<a name="IDX435"></a>
+<a name="IDX436"></a>
+<p><a name="volno_002dfile"></a>
+<a name="IDX437"></a>
+The volume number used by <code>tar</code> in its tape-changing prompt
+can be changed; if you give the
+‘<samp>--volno-file=<var>file-of-number</var></samp>’ option, then
+<var>file-of-number</var> 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
+<code>tar</code> 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 <a href="#SEC157">Including a Label in the
Archive</a>, it <em>only</em> affects
+the number used in the prompt.)
+</p>
+<a name="IDX438"></a>
+<a name="IDX439"></a>
+<p><a name="info_002dscript"></a>
+<a name="IDX440"></a>
+<a name="IDX441"></a>
+If you want more elaborate behavior than this, you can write a special
+<em>new volume script</em>, that will be responsible for changing the
+volume, and instruct <code>tar</code> to use it instead of its normal
+prompting procedure:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--info-script=<var>script-name</var></samp>’</dt>
+<dt> ‘<samp>--new-volume-script=<var>script-name</var></samp>’</dt>
+<dt> ‘<samp>-F <var>script-name</var></samp>’</dt>
+<dd><p>Specify the full name of the volume script to use. The script can be
+used to eject cassettes, or to broadcast messages such as
+‘<samp>Someone please come change my tape</samp>’ when performing
unattended
+backups.
+</p></dd>
+</dl>
+
+<p>The <var>script-name</var> is executed without any command line
+arguments. It inherits <code>tar</code>'s shell environment.
+Additional data is passed to it via the following
+environment variables:
+</p>
+<dl compact="compact">
+<dd><a name="IDX442"></a>
+</dd>
+<dt> <code>TAR_VERSION</code></dt>
+<dd><p><acronym>GNU</acronym> <code>tar</code> version number.
+</p>
+<a name="IDX443"></a>
+</dd>
+<dt> <code>TAR_ARCHIVE</code></dt>
+<dd><p>The name of the archive <code>tar</code> is processing.
+</p>
+<a name="IDX444"></a>
+</dd>
+<dt> <code>TAR_VOLUME</code></dt>
+<dd><p>Ordinal number of the volume <code>tar</code> is about to start.
+</p>
+<a name="IDX445"></a>
+</dd>
+<dt> <code>TAR_SUBCOMMAND</code></dt>
+<dd><p>Short option describing the operation <code>tar</code> is executing
+See section <a href="#SEC51">The Five Advanced <code>tar</code>
Operations</a>, for a complete list of subcommand options.
+</p>
+<a name="IDX446"></a>
+</dd>
+<dt> <code>TAR_FORMAT</code></dt>
+<dd><p>Format of the archive being processed. See section <a
href="#SEC124">Controlling the Archive Format</a>, for a complete
+list of archive format names.
+</p></dd>
+</dl>
+
+<p>The volume script can instruct <code>tar</code> to use new archive name,
+by writing in to file descriptor 3 (see below for an example).
+</p>
+<p>If the info script fails, <code>tar</code> exits; otherwise, it begins
+writing the next volume.
+</p>
+<p>If you want <code>tar</code> to cycle through a series of files or tape
+drives, there are three approaches to choose from. First of all, you
+can give <code>tar</code> multiple ‘<samp>--file</samp>’ 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 <code>tar</code> prompt for a tape change (or run
+the info script). For example, suppose someone has two tape drives on
+a system named ‘<tt>/dev/tape0</tt>’ and
‘<tt>/dev/tape1</tt>’. For having
+<acronym>GNU</acronym> <code>tar</code> 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --create
--multi-volume --file=/dev/tape0 --file=/dev/tape1 <var>files</var></kbd>
+$ <kbd>tar cMff /dev/tape0 /dev/tape1 <var>files</var></kbd>
+</pre></td></tr></table>
+
+<p>The second method is to use the ‘<samp>n</samp>’ response to
the tape-change
+prompt.
+</p>
+<p>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
+‘<tt><var>archive</var>-<var>vol</var></tt>’, where
<var>archive</var> is the name of the
+archive being created (as given by ‘<samp>--file</samp>’ option)
and
+<var>vol</var> is the ordinal number of the archive being created:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">#! /bin/sh
+echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+
+name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+case $TAR_SUBCOMMAND in
+-c) ;;
+-d|-x|-t) test -r ${name:-$TAR_ARCHIVE}-$TAR_VOLUME || exit 1
+ ;;
+*) exit 1
+esac
+
+echo ${name:-$TAR_ARCHIVE}-$TAR_VOLUME >&3
+</pre></td></tr></table>
+
+<p>The same script cant be used while listing, comparing or extracting
+from the created archive. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"># <span
class="roman">Create a multi-volume archive:</span>
+$ <kbd>tar -c -L1024 -f archive.tar -F new-volume .</kbd>
+# <span class="roman">Extract from the created archive:</span>
+$ <kbd>tar -x -f archive.tar -F new-volume .</kbd>
+</pre></td></tr></table>
+
+<p>Notice, that the first command had to use ‘<samp>-L</samp>’
option, since
+otherwise <acronym>GNU</acronym> <code>tar</code> will end up writing
everything to file
+‘<tt>archive.tar</tt>’.
+</p>
+<p>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 ‘<samp>--list</samp>’, without
‘<samp>--multi-volume</samp>’ specified.
+To extract an archive member from one volume (assuming it is described
+that volume), use ‘<samp>--extract</samp>’, again without
+‘<samp>--multi-volume</samp>’.
+</p>
+<p>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
+‘<samp>--multi-volume</samp>’ to extract it successfully. In this
case, you
+should load the volume where the archive member starts, and use
+‘<samp>tar --extract --multi-volume</samp>’—<code>tar</code>
will prompt for later
+volumes as it needs them. See section <a href="#SEC26">Extracting an Entire
Archive</a>, for more
+information about extracting archives.
+</p>
+<p>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.
+</p>
+<p>If a multi-volume archive was labeled using
+‘<samp>--label=<var>archive-label</var></samp>’ (see section <a
href="#SEC157">Including a Label in the Archive</a>) when it was
+created, <code>tar</code> will not automatically label volumes which are
+added later. To label subsequent volumes, specify
+‘<samp>--label=<var>archive-label</var></samp>’ again in
conjunction with the
+‘<samp>--append</samp>’, ‘<samp>--update</samp>’ or
‘<samp>--concatenate</samp>’ operation.
+</p>
+<p>Notice that multi-volume support is a GNU extension and the archives
+created in this mode should be read only using <acronym>GNU</acronym>
<code>tar</code>. If you
+absolutely have to process such archives using a third-party <code>tar</code>
+implementation, read <a href="#SEC140">Extracting Members Split Between
Volumes</a>.
+</p>
+<hr size="6">
+<a name="Tape-Files"></a>
+<a name="SEC155"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC154" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC156" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC153" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 9.6.2 Tape Files </h3>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>To give the archive a name which will be recorded in it, use the
+‘<samp>--label=<var>volume-label</var></samp>’ (‘<samp>-V
<var>volume-label</var></samp>’)
+option. This will write a special block identifying
+<var>volume-label</var> as the name of the archive to the front of the
+archive which will be displayed when the archive is listed with
+‘<samp>--list</samp>’. If you are creating a multi-volume archive
with
+‘<samp>--multi-volume</samp>’ (see section <a href="#SEC153">Using
Multiple Tapes</a>), then the
+volume label will have ‘<samp>Volume <var>nnn</var></samp>’
appended to the name
+you give, where <var>nnn</var> is the number of the volume of the archive.
+(If you use the ‘<samp>--label=<var>volume-label</var></samp>’)
option when
+reading an archive, it checks to make sure the label on the tape
+matches the one you give. See section <a href="#SEC157">Including a Label in
the Archive</a>.
+</p>
+<p>When <code>tar</code> 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 <code>tar</code>. To do this, use the <code>mt</code> command.
+For more information on the <code>mt</code> command and on the organization
+of tapes into a sequence of tape files, see <a href="#SEC152">The
<code>mt</code> Utility</a>.
+</p>
+<p>People seem to often do:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample"><kbd>--label="<var>some-prefix</var> `date
+<var>some-format</var>`"</kbd>
+</pre></td></tr></table>
+
+<p>or such, for pushing a common date in all volumes or an archive set.
+</p>
+<hr size="6">
+<a name="Tarcat"></a>
+<a name="SEC156"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC155" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC157" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC153" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="subsection"> 9.6.3 Concatenate Volumes into a Single Archive </h3>
+
+<p> Sometimes it is necessary to convert existing <acronym>GNU</acronym>
<code>tar</code> multi-volume
+archive to a single <code>tar</code> archive. Simply concatenating all
+volumes into one will not work, since each volume carries an additional
+information at the beginning. <acronym>GNU</acronym> <code>tar</code> is
shipped with the shell
+script <code>tarcat</code> designed for this purpose.
+</p>
+<p> The script takes a list of files comprising a multi-volume archive
+and creates the resulting archive at the standard output. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><kbd>tarcat vol.1
vol.2 vol.3 | tar tf -</kbd>
+</pre></td></tr></table>
+
+<p> 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 <code>tar</code> archives.
+It uses <code>dd</code> and does not filter its standard error, so you
+will usually see lots of spurious messages.
+</p>
+
+
+
+
+<hr size="6">
+<a name="label"></a>
+<a name="SEC157"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC156" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC158" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.7 Including a Label in the Archive </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<a name="IDX447"></a>
+<p> To avoid problems caused by misplaced paper labels on the archive
+media, you can include a <em>label</em> entry—an archive member which
+contains the name of the archive—in the archive itself. Use the
+‘<samp>--label=<var>archive-label</var></samp>’ (‘<samp>-V
<var>archive-label</var></samp>’)
+option in conjunction with the ‘<samp>--create</samp>’ operation
to include
+a label entry in the archive as it is being created.
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--label=<var>archive-label</var></samp>’</dt>
+<dt> ‘<samp>-V <var>archive-label</var></samp>’</dt>
+<dd><p>Includes an <em>archive-label</em> at the beginning of the archive when
+the archive is being created, when used in conjunction with the
+‘<samp>--create</samp>’ operation. Checks to make sure the
archive label
+matches the one specified (when used in conjunction with any other
+operation.
+</p></dd>
+</dl>
+
+<p> If you create an archive using both
+‘<samp>--label=<var>archive-label</var></samp>’ (‘<samp>-V
<var>archive-label</var></samp>’)
+and ‘<samp>--multi-volume</samp>’ (‘<samp>-M</samp>’),
each volume of the archive
+will have an archive label of the form ‘<samp><var>archive-label</var>
+Volume <var>n</var></samp>’, where <var>n</var> is 1 for the first
volume, 2 for the
+next, and so on. See section <a href="#SEC153">Using Multiple Tapes</a>, for
information on
+creating multiple volume archives.
+</p>
+<a name="IDX448"></a>
+<a name="IDX449"></a>
+<p> The volume label will be displayed by ‘<samp>--list</samp>’
along with
+the file contents. If verbose display is requested, it will also be
+explicitely marked as in the example below:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --verbose
--list --file=iamanarchive</kbd>
+V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
+-rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
+</pre></td></tr></table>
+
+<a name="IDX450"></a>
+<p><a name="g_t_002d_002dtest_002dlabel-option"></a>
+ However, ‘<samp>--list</samp>’ 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 ‘<samp>--test-label</samp>’ option. This option
reads only the
+first block of an archive, so it can be used with slow storage
+devices. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar
--test-label --file=iamanarchive</kbd>
+iamalabel
+</pre></td></tr></table>
+
+<p> If ‘<samp>--test-label</samp>’ is used with a single command
line
+argument, <code>tar</code> 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar
--test-label --file=iamanarchive 'iamalable'</kbd>
+⇒ 0
+$ <kbd>tar --test-label --file=iamanarchive 'iamalable' alabel</kbd>
+⇒ 1
+</pre></td></tr></table>
+
+<p> If you request any operation, other than
‘<samp>--create</samp>’, along
+with using ‘<samp>--label</samp>’ option, <code>tar</code> 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 ‘<tt>archive</tt>’, presumably labelled with string
‘<samp>My volume</samp>’,
+you will get:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar -rf archive
--label 'My volume' .</kbd>
+tar: Archive not labeled to match `My volume'
+</pre></td></tr></table>
+
+<p>in case its label does not match. This will work even if
+‘<tt>archive</tt>’ is not labelled at all.
+</p>
+<p> Similarly, <code>tar</code> will refuse to list or extract the
+archive if its label doesn't match the <var>archive-label</var>
+specified. In those cases, <var>archive-label</var> argument is interpreted
+as a globbing-style pattern which must match the actual magnetic
+volume label. See section <a href="#SEC102">Excluding Some Files</a>, for a
precise description of how match
+is attempted<a name="DOCF22" href="#FOOT22">(22)</a>. If the switch
‘<samp>--multi-volume</samp>’ (‘<samp>-M</samp>’) is
being used,
+the volume label matcher will also suffix <var>archive-label</var> by
+‘<samp> Volume [1-9]*</samp>’ 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.
+</p>
+<p> The ‘<samp>--label</samp>’ was once called
‘<samp>--volume</samp>’, but is not
+available under that name anymore.
+</p>
+<p> You can also use ‘<samp>--label</samp>’ 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar cfMV
/dev/tape "Daily backup for `date +%Y-%m-%d`"</kbd>
+$ <kbd>tar --create --file=/dev/tape --multi-volume \
+ --volume="Daily backup for `date +%Y-%m-%d`"</kbd>
+</pre></td></tr></table>
+
+<p> Also note that each label has its own date and time, which corresponds
+to when <acronym>GNU</acronym> <code>tar</code> initially attempted to write
it,
+often soon after the operator launches <code>tar</code> 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.
+</p>
+<hr size="6">
+<a name="verify"></a>
+<a name="SEC158"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC157" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC159" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.8 Verifying Data as It is Stored </h2>
+
+<dl compact="compact">
+<dt> ‘<samp>-W</samp>’</dt>
+<dt> ‘<samp>--verify</samp>’</dt>
+<dd><a name="IDX451"></a>
+<p>Attempt to verify the archive after writing.
+</p></dd>
+</dl>
+
+<p>This option causes <code>tar</code> 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.
+</p>
+<p>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.
+</p>
+<p>You can insure the accuracy of an archive by comparing files in the
+system with archive members. <code>tar</code> 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.
+</p>
+<a name="IDX452"></a>
+<a name="IDX453"></a>
+<p>To check for discrepancies in an archive immediately after it is
+written, use the ‘<samp>--verify</samp>’
(‘<samp>-W</samp>’) option in conjunction with
+the ‘<samp>--create</samp>’ operation. When this option is
+specified, <code>tar</code> checks archive members against their counterparts
+in the file system, and reports discrepancies on the standard error.
+</p>
+<p>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.
+</p>
+<p>One can explicitly compare an already made archive with the file
+system by using the ‘<samp>--compare</samp>’
(‘<samp>--diff</samp>’, ‘<samp>-d</samp>’)
+option, instead of using the more automatic
‘<samp>--verify</samp>’ option.
+See section <a href="#SEC59">Comparing Archive Members with the File
System</a>.
+</p>
+<p>Note that these two options have a slightly different intent. The
+‘<samp>--compare</samp>’ option checks how identical are the
logical contents of some
+archive with what is on your disks, while the
‘<samp>--verify</samp>’ option is
+really for checking if the physical contents agree and if the recording
+media itself is of dependable quality. So, for the
‘<samp>--verify</samp>’
+operation, <code>tar</code> tries to defeat all in-memory cache pertaining to
+the archive, while it lets the speed optimization undisturbed for the
+‘<samp>--compare</samp>’ option. If you nevertheless use
‘<samp>--compare</samp>’ 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.
+</p>
+<p>The ‘<samp>--verify</samp>’ 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.
+</p>
+<p>The ‘<samp>--verify</samp>’ (‘<samp>-W</samp>’)
option will not work in
+conjunction with the ‘<samp>--multi-volume</samp>’
(‘<samp>-M</samp>’) option or
+the ‘<samp>--append</samp>’ (‘<samp>-r</samp>’),
‘<samp>--update</samp>’ (‘<samp>-u</samp>’)
+and ‘<samp>--delete</samp>’ operations. See section <a
href="#SEC51">The Five Advanced <code>tar</code> Operations</a>, for more
+information on these operations.
+</p>
+<p>Also, since <code>tar</code> normally strips leading
‘<samp>/</samp>’ from file
+names (see section <a href="#SEC112">Absolute File Names</a>), a command like
‘<samp>tar --verify -cf
+/tmp/foo.tar /etc</samp>’ will work as desired only if the working
directory is
+‘<tt>/</tt>’, as <code>tar</code> uses the archive's relative
member names
+(e.g., ‘<tt>etc/motd</tt>’) when verifying the archive.
+</p>
+<hr size="6">
+<a name="Write-Protection"></a>
+<a name="SEC159"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC158" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="section"> 9.9 Write Protection </h2>
+
+<p>Almost all tapes and diskettes, and in a few rare cases, even disks can
+be <em>write protected</em>, 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).
+</p>
+<p>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.
+</p>
+<hr size="6">
+<a name="Changes"></a>
+<a name="SEC160"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC159" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC161" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC161" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="appendix"> A. Changes </h1>
+
+<p>This appendix lists some important user-visible changes between
+version <acronym>GNU</acronym> <code>tar</code> 1.15.92 and previous versions.
An up-to-date
+version of this document is available at
+<a href="http://www.gnu.org/software/tar/manual/changes.html";>the
<acronym>GNU</acronym> <code>tar</code> documentation page</a>.
+</p>
+<dl compact="compact">
+<dt> Use of globbing patterns when listing and extracting.</dt>
+<dd>
+<p>Previous versions of GNU tar assumed shell-style globbing when
+extracting from or listing an archive. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar xf foo.tar
'*.c'</kbd>
+</pre></td></tr></table>
+
+<p>would extract all files whose names end in ‘<samp>.c</samp>’.
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 ‘<tt>*.c</tt>’.
+</p>
+<p>To facilitate transition to the new behavior for those users who got
+used to the previous incorrect one, <code>tar</code> 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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar xf foo.tar
'*.c'</kbd>
+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
+</pre></td></tr></table>
+
+<p>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 <code>TAR_OPTIONS</code> variable.
+</p>
+<p>See section <a href="#SEC104">Wildcards Patterns and Matching</a>, for the
detailed discussion of the use of globbing
+patterns by <acronym>GNU</acronym> <code>tar</code>.
+</p>
+</dd>
+<dt> Use of short option ‘<samp>-o</samp>’.</dt>
+<dd>
+<p>Earlier versions of <acronym>GNU</acronym> <code>tar</code> understood
‘<samp>-o</samp>’ command line
+option as a synonym for ‘<samp>--old-archive</samp>’.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> starting from version 1.13.90
understands this option as
+a synonym for ‘<samp>--no-same-owner</samp>’. This is compatible
with
+UNIX98 <code>tar</code> implementations.
+</p>
+<p>However, to facilitate transition, ‘<samp>-o</samp>’ option
retains its
+old semantics when it is used with one of archive-creation commands.
+Users are encouraged to use ‘<samp>--format=oldgnu</samp>’ instead.
+</p>
+<p>It is especially important, since versions of <acronym>GNU</acronym>
Automake
+up to and including 1.8.4 invoke tar with this option to produce
+distribution tarballs. See section <a href="#SEC124">v7</a>, for the detailed
discussion
+of this issue and its implications.
+</p>
+
+
+<p>.
+See <a href="automake.html#Options">tar-v7: (automake)Options</a> section
`Changing Automake's Behavior' in <cite>GNU Automake</cite>, for a description
on how to use various
+archive formats with <code>automake</code>.
+</p>
+<p>Future versions of <acronym>GNU</acronym> <code>tar</code> will understand
‘<samp>-o</samp>’ only as a
+synonym for ‘<samp>--no-same-owner</samp>’.
+</p>
+</dd>
+<dt> Use of short option ‘<samp>-l</samp>’</dt>
+<dd>
+<p>Earlier versions of <acronym>GNU</acronym> <code>tar</code> understood
‘<samp>-l</samp>’ option as a
+synonym for ‘<samp>--one-file-system</samp>’. 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 ‘<samp>-l</samp>’
as a short
+variant of ‘<samp>--check-links</samp>’ was introduced in version
1.15.91.
+</p>
+</dd>
+<dt> Use of options ‘<samp>--portability</samp>’ and
‘<samp>--old-archive</samp>’</dt>
+<dd>
+<p>These options are deprecated. Please use
‘<samp>--format=v7</samp>’ instead.
+</p>
+</dd>
+<dt> Use of option ‘<samp>--posix</samp>’</dt>
+<dd>
+<p>This option is deprecated. Please use
‘<samp>--format=posix</samp>’ instead.
+</p></dd>
+</dl>
+
+<hr size="6">
+<a name="Configuring-Help-Summary"></a>
+<a name="SEC161"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC160" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC160" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="appendix"> B. Configuring Help Summary </h1>
+
+<p>Running <kbd>tar --help</kbd> displays the short <code>tar</code> option
+summary (see section <a href="#SEC44"><acronym>GNU</acronym> <code>tar</code>
documentation</a>). This summary is organised by <em>groups</em> 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</kbd> output:
+</p>
+<pre class="verbatim"> 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
+</pre>
+<a name="IDX454"></a>
+<p>The exact visual representation of the help output is configurable via
+<code>ARGP_HELP_FMT</code> environment variable. The value of this variable
+is a comma-separated list of <em>format variable</em> assignments. There
+are two kinds of format variables. An <em>offset variable</em> keeps the
+offset of some part of help output text from the leftmost column on
+the screen. A <em>boolean</em> 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:
+</p>
+<dl compact="compact">
+<dt> Offset assignment</dt>
+<dd>
+<p>The assignment to an offset variable has the following syntax:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample"><var>variable</var>=<var>value</var>
+</pre></td></tr></table>
+
+<p>where <var>variable</var> is the variable name, and <var>value</var> is a
+numeric value to be assigned to the variable.
+</p>
+</dd>
+<dt> Boolean assignment</dt>
+<dd>
+<p>To assign <code>true</code> value to a variable, simply put this variable
name. To
+assign <code>false</code> value, prefix the variable name with
‘<samp>no-</samp>’. For
+example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"># Assign
<code>true</code> value:
+dup-args
+# Assign <code>false</code> value:
+no-dup-args
+</pre></td></tr></table>
+</dd>
+</dl>
+
+<p>Following variables are declared:
+</p>
+<dl>
+<dt><u>Help Output:</u> boolean <b>dup-args</b>
+<a name="IDX455"></a>
+</dt>
+<dd><p>If true, arguments for an option are shown with both short and long
+options, even when a given option has both forms, for example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"> -f ARCHIVE,
--file=ARCHIVE use archive file or device ARCHIVE
+</pre></td></tr></table>
+
+<p>If false, then if an option has both short and long forms, the
+argument is only shown with the long one, for example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"> -f, --file=ARCHIVE
use archive file or device ARCHIVE
+</pre></td></tr></table>
+
+<p>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</code> (see below).
+</p>
+<p>The default is false.
+</p></dd></dl>
+
+<dl>
+<dt><u>Help Output:</u> boolean <b>dup-args-note</b>
+<a name="IDX456"></a>
+</dt>
+<dd><p>If this variable is true, which is the default, the following notice
+is displayed at the end of the help output:
+</p>
+<blockquote><p>Mandatory or optional arguments to long options are also
mandatory or
+optional for any corresponding short options.
+</p></blockquote>
+
+<p>Setting <code>no-dup-args-note</code> inhibits this message. Normally, only
one of
+variables <code>dup-args</code> or <code>dup-args-note</code> should be set.
+</p></dd></dl>
+
+<dl>
+<dt><u>Help Output:</u> offset <b>short-opt-col</b>
+<a name="IDX457"></a>
+</dt>
+<dd><p>Column in which short options start. Default is 2.
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --help|grep
ARCHIVE</kbd>
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ <kbd>ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE</kbd>
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+</pre></td></tr></table>
+</dd></dl>
+
+<dl>
+<dt><u>Help Output:</u> offset <b>long-opt-col</b>
+<a name="IDX458"></a>
+</dt>
+<dd><p>Column in which long options start. Default is 6. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --help|grep
ARCHIVE</kbd>
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ <kbd>ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE</kbd>
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+</pre></td></tr></table>
+</dd></dl>
+
+<dl>
+<dt><u>Help Output:</u> offset <b>doc-opt-col</b>
+<a name="IDX459"></a>
+</dt>
+<dd><p>Column in which <em>doc options</em> 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 ‘<samp>--format</samp>’ option:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"> -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
+</pre></td></tr></table>
+
+<p>the format names are doc options. Thus, if you set
+<kbd>ARGP_HELP_FMT=doc-opt-col=6</kbd> the above part of the help output
+will look as follows:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"> -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
+</pre></td></tr></table>
+</dd></dl>
+
+<dl>
+<dt><u>Help Output:</u> offset <b>opt-doc-col</b>
+<a name="IDX460"></a>
+</dt>
+<dd><p>Column in which option description starts. Default is 29.
+</p>
+<table><tr><td> </td><td><pre class="smallexample">$ <kbd>tar --help|grep
ARCHIVE</kbd>
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ <kbd>ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE</kbd>
+ -f, --file=ARCHIVE use archive file or device ARCHIVE
+$ <kbd>ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE</kbd>
+ -f, --file=ARCHIVE
+ use archive file or device ARCHIVE
+</pre></td></tr></table>
+
+<p>Notice, that the description starts on a separate line if
+<code>opt-doc-col</code> value is too small.
+</p></dd></dl>
+
+<dl>
+<dt><u>Help Output:</u> offset <b>header-col</b>
+<a name="IDX461"></a>
+</dt>
+<dd><p>Column in which <em>group headers</em> are printed. A group header is a
+descriptive text preceding an option group. For example, in the
+following text:
+</p>
+<pre class="verbatim"> Main operation mode:
+
+ -A, --catenate, --concatenate append tar files to
+ an archive
+ -c, --create create a new archive
+</pre><p>‘<samp>Main operation mode:</samp>’ is the group header.
+</p>
+<p>The default value is 1.
+</p></dd></dl>
+
+<dl>
+<dt><u>Help Output:</u> offset <b>usage-indent</b>
+<a name="IDX462"></a>
+</dt>
+<dd><p>Indentation of wrapped usage lines. Affects
‘<samp>--usage</samp>’
+output. Default is 12.
+</p></dd></dl>
+
+<dl>
+<dt><u>Help Output:</u> offset <b>rmargin</b>
+<a name="IDX463"></a>
+</dt>
+<dd><p>Right margin of the text output. Used for wrapping.
+</p></dd></dl>
+
+<hr size="6">
+<a name="Tar-Internals"></a>
+<a name="SEC162"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC161" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC163" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC161" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="appendix"> C. Tar Internals </h1>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC163">Basic Tar
Format</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC164"><acronym>GNU</acronym>
Extensions to the Archive Format</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC165">Storing Sparse
Files</a></td><td> </td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC169">Format of the Incremental
Snapshot Files</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a
href="#SEC170">Dumpdir</a></td><td> </td><td align="left"
valign="top">
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Standard"></a>
+<a name="SEC163"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC162" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC164" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="unnumberedsec"> Basic Tar Format </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>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 <code>tar</code> utility or Tar mode in
+<acronym>GNU</acronym> Emacs.
+</p>
+<p>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
+<em>archive member</em>), and consists of a file header and the contents
+of the file. File headers contain file names and statistics, checksum
+information which <code>tar</code> uses to detect file corruption, and
+information about file types.
+</p>
+<p>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 <a
href="#SEC55">Updating an Archive</a>.
+
+</p>
+
+<p>In addition to entries describing archive members, an archive may
+contain entries which <code>tar</code> itself uses to store information.
+See section <a href="#SEC157">Including a Label in the Archive</a>, for an
example of such an archive entry.
+</p>
+<p>A <code>tar</code> archive file contains a series of blocks. Each block
+contains <code>BLOCKSIZE</code> bytes. Although this format may be thought
+of as being on magnetic tape, other media are often used.
+</p>
+<p>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</acronym> <code>tar</code> always issues a warning if
it does not encounter it.
+</p>
+<p>The blocks may be <em>blocked</em> for physical I/O operations.
+Each record of <var>n</var> blocks (where <var>n</var> is set by the
+‘<samp>--blocking-factor=<var>512-size</var></samp>’
(‘<samp>-b <var>512-size</var></samp>’) option to <code>tar</code>)
is written with a single
+‘<samp>write ()</samp>’ 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.
+</p>
+<p>The header block is defined in C as follows. In the <acronym>GNU</acronym>
<code>tar</code>
+distribution, this is part of file ‘<tt>src/tar.h</tt>’:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">
+/*<span class="roman"> tar Header Block, from POSIX 1003.1-1990. </span>*/
+
+/*<span class="roman"> POSIX header. </span>*/
+
+struct posix_header
+{ /*<span class="roman"> byte offset </span>*/
+ char name[100]; /*<span class="roman"> 0 </span>*/
+ char mode[8]; /*<span class="roman"> 100 </span>*/
+ char uid[8]; /*<span class="roman"> 108 </span>*/
+ char gid[8]; /*<span class="roman"> 116 </span>*/
+ char size[12]; /*<span class="roman"> 124 </span>*/
+ char mtime[12]; /*<span class="roman"> 136 </span>*/
+ char chksum[8]; /*<span class="roman"> 148 </span>*/
+ char typeflag; /*<span class="roman"> 156 </span>*/
+ char linkname[100]; /*<span class="roman"> 157 </span>*/
+ char magic[6]; /*<span class="roman"> 257 </span>*/
+ char version[2]; /*<span class="roman"> 263 </span>*/
+ char uname[32]; /*<span class="roman"> 265 </span>*/
+ char gname[32]; /*<span class="roman"> 297 </span>*/
+ char devmajor[8]; /*<span class="roman"> 329 </span>*/
+ char devminor[8]; /*<span class="roman"> 337 </span>*/
+ char prefix[155]; /*<span class="roman"> 345 </span>*/
+ /*<span class="roman"> 500 </span>*/
+};
+
+#define TMAGIC "ustar" /*<span class="roman"> ustar and a
null </span>*/
+#define TMAGLEN 6
+#define TVERSION "00" /*<span class="roman"> 00 and no
null </span>*/
+#define TVERSLEN 2
+
+/*<span class="roman"> Values used in typeflag field. </span>*/
+#define REGTYPE '0' /*<span class="roman"> regular file </span>*/
+#define AREGTYPE '\0' /*<span class="roman"> regular file </span>*/
+#define LNKTYPE '1' /*<span class="roman"> link </span>*/
+#define SYMTYPE '2' /*<span class="roman"> reserved </span>*/
+#define CHRTYPE '3' /*<span class="roman"> character special
</span>*/
+#define BLKTYPE '4' /*<span class="roman"> block special </span>*/
+#define DIRTYPE '5' /*<span class="roman"> directory </span>*/
+#define FIFOTYPE '6' /*<span class="roman"> FIFO special </span>*/
+#define CONTTYPE '7' /*<span class="roman"> reserved </span>*/
+
+#define XHDTYPE 'x' /*<span class="roman"> Extended header
referring to the
+ next file in the archive </span>*/
+#define XGLTYPE 'g' /*<span class="roman"> Global extended header
</span>*/
+
+/*<span class="roman"> Bits used in the mode field, values in octal. </span>*/
+#define TSUID 04000 /*<span class="roman"> set UID on execution
</span>*/
+#define TSGID 02000 /*<span class="roman"> set GID on execution
</span>*/
+#define TSVTX 01000 /*<span class="roman"> reserved </span>*/
+ /*<span class="roman"> file permissions
</span>*/
+#define TUREAD 00400 /*<span class="roman"> read by owner </span>*/
+#define TUWRITE 00200 /*<span class="roman"> write by owner </span>*/
+#define TUEXEC 00100 /*<span class="roman"> execute/search by owner
</span>*/
+#define TGREAD 00040 /*<span class="roman"> read by group </span>*/
+#define TGWRITE 00020 /*<span class="roman"> write by group </span>*/
+#define TGEXEC 00010 /*<span class="roman"> execute/search by group
</span>*/
+#define TOREAD 00004 /*<span class="roman"> read by other </span>*/
+#define TOWRITE 00002 /*<span class="roman"> write by other </span>*/
+#define TOEXEC 00001 /*<span class="roman"> execute/search by other
</span>*/
+
+/*<span class="roman"> tar Header Block, GNU extensions. </span>*/
+
+/*<span class="roman"> 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.
</span>*/
+
+/*<span class="roman"> *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.
</span>*/
+
+/*<span class="roman"> Descriptor for a single file hole. </span>*/
+
+struct sparse
+{ /*<span class="roman"> byte offset </span>*/
+ char offset[12]; /*<span class="roman"> 0 </span>*/
+ char numbytes[12]; /*<span class="roman"> 12 </span>*/
+ /*<span class="roman"> 24 </span>*/
+};
+
+/*<span class="roman"> 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. </span>*/
+
+#define SPARSES_IN_EXTRA_HEADER 16
+#define SPARSES_IN_OLDGNU_HEADER 4
+#define SPARSES_IN_SPARSE_HEADER 21
+
+/*<span class="roman"> 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. </span>*/
+
+struct sparse_header
+{ /*<span class="roman"> byte offset </span>*/
+ struct sparse sp[SPARSES_IN_SPARSE_HEADER];
+ /*<span class="roman"> 0 </span>*/
+ char isextended; /*<span class="roman"> 504 </span>*/
+ /*<span class="roman"> 505 </span>*/
+};
+
+/*<span class="roman"> 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. </span>*/
+
+struct oldgnu_header
+{ /*<span class="roman"> byte offset </span>*/
+ char unused_pad1[345]; /*<span class="roman"> 0 </span>*/
+ char atime[12]; /*<span class="roman"> 345 Incr. archive:
atime of the file </span>*/
+ char ctime[12]; /*<span class="roman"> 357 Incr. archive:
ctime of the file </span>*/
+ char offset[12]; /*<span class="roman"> 369 Multivolume
archive: the offset of
+ the start of this volume </span>*/
+ char longnames[4]; /*<span class="roman"> 381 Not used </span>*/
+ char unused_pad2; /*<span class="roman"> 385 </span>*/
+ struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
+ /*<span class="roman"> 386 </span>*/
+ char isextended; /*<span class="roman"> 482 Sparse file:
Extension sparse header
+ follows </span>*/
+ char realsize[12]; /*<span class="roman"> 483 Sparse file: Real
size</span>*/
+ /*<span class="roman"> 495 </span>*/
+};
+
+/*<span class="roman"> 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. </span>*/
+#define OLDGNU_MAGIC "ustar " /*<span class="roman"> 7 chars and a
null </span>*/
+
+/*<span class="roman"> 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) </span>*/
+
+/*<span class="roman"> This is a dir entry that contains the names of files
that were in the
+ dir at the time the dump was made. </span>*/
+#define GNUTYPE_DUMPDIR 'D'
+
+/*<span class="roman"> Identifies the *next* file on the tape as having a long
linkname. </span>*/
+#define GNUTYPE_LONGLINK 'K'
+
+/*<span class="roman"> Identifies the *next* file on the tape as having a long
name. </span>*/
+#define GNUTYPE_LONGNAME 'L'
+
+/*<span class="roman"> This is the continuation of a file that began on
another volume. </span>*/
+#define GNUTYPE_MULTIVOL 'M'
+
+/*<span class="roman"> For storing filenames that do not fit into the main
header. </span>*/
+#define GNUTYPE_NAMES 'N'
+
+/*<span class="roman"> This is for sparse files. </span>*/
+#define GNUTYPE_SPARSE 'S'
+
+/*<span class="roman"> This file is a tape/volume header. Ignore it on
extraction. </span>*/
+#define GNUTYPE_VOLHDR 'V'
+
+/*<span class="roman"> Solaris extended header </span>*/
+#define SOLARIS_XHDTYPE 'X'
+
+/*<span class="roman"> Jörg Schilling star header </span>*/
+
+struct star_header
+{ /*<span class="roman"> byte offset </span>*/
+ char name[100]; /*<span class="roman"> 0 </span>*/
+ char mode[8]; /*<span class="roman"> 100 </span>*/
+ char uid[8]; /*<span class="roman"> 108 </span>*/
+ char gid[8]; /*<span class="roman"> 116 </span>*/
+ char size[12]; /*<span class="roman"> 124 </span>*/
+ char mtime[12]; /*<span class="roman"> 136 </span>*/
+ char chksum[8]; /*<span class="roman"> 148 </span>*/
+ char typeflag; /*<span class="roman"> 156 </span>*/
+ char linkname[100]; /*<span class="roman"> 157 </span>*/
+ char magic[6]; /*<span class="roman"> 257 </span>*/
+ char version[2]; /*<span class="roman"> 263 </span>*/
+ char uname[32]; /*<span class="roman"> 265 </span>*/
+ char gname[32]; /*<span class="roman"> 297 </span>*/
+ char devmajor[8]; /*<span class="roman"> 329 </span>*/
+ char devminor[8]; /*<span class="roman"> 337 </span>*/
+ char prefix[131]; /*<span class="roman"> 345 </span>*/
+ char atime[12]; /*<span class="roman"> 476 </span>*/
+ char ctime[12]; /*<span class="roman"> 488 </span>*/
+ /*<span class="roman"> 500 </span>*/
+};
+
+#define SPARSES_IN_STAR_HEADER 4
+#define SPARSES_IN_STAR_EXT_HEADER 21
+
+struct star_in_header
+{
+ char fill[345]; /*<span class="roman"> 0 Everything that is before
t_prefix </span>*/
+ char prefix[1]; /*<span class="roman"> 345 t_name prefix </span>*/
+ char fill2; /*<span class="roman"> 346 </span>*/
+ char fill3[8]; /*<span class="roman"> 347 </span>*/
+ char isextended; /*<span class="roman"> 355 </span>*/
+ struct sparse sp[SPARSES_IN_STAR_HEADER]; /*<span class="roman"> 356
</span>*/
+ char realsize[12]; /*<span class="roman"> 452 Actual size of the file
</span>*/
+ char offset[12]; /*<span class="roman"> 464 Offset of multivolume
contents </span>*/
+ char atime[12]; /*<span class="roman"> 476 </span>*/
+ char ctime[12]; /*<span class="roman"> 488 </span>*/
+ char mfill[8]; /*<span class="roman"> 500 </span>*/
+ char xmagic[4]; /*<span class="roman"> 508 "tar" </span>*/
+};
+
+struct star_ext_header
+{
+ struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
+ char isextended;
+};
+
+</pre></td></tr></table>
+
+<p>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.
+</p>
+<p>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 <code>tar</code> format
+does not distinguish text files from binary files, and no translation
+of file contents is performed.
+</p>
+<p>The <code>name</code>, <code>linkname</code>, <code>magic</code>,
<code>uname</code>, and
+<code>gname</code> are null-terminated character strings. All other fields
+are zero-filled octal numbers in ASCII. Each numeric field of width
+<var>w</var> contains <var>w</var> minus 1 digits, and a null.
+</p>
+<p>The <code>name</code> field is the file name of the file, with directory
names
+(if any) preceding the file name, separated by slashes.
+</p>
+
+
+
+
+<p>The <code>mode</code> field provides nine bits specifying file permissions
+and three bits to specify the Set UID, Set GID, and Save Text
+(<em>sticky</em>) 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 <em>other</em> permission.
+</p>
+<p>The <code>uid</code> and <code>gid</code> 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.
+</p>
+<p>The <code>size</code> field is the size of the file in bytes; linked files
+are archived with this field specified as zero.
+</p>
+
+<p>The <code>mtime</code> 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.
+</p>
+<p>The <code>chksum</code> 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</code> field is treated as
+if it were all blanks.
+</p>
+<p>The <code>typeflag</code> 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, <code>tar</code> issues a warning to the standard error.
+</p>
+<p>The <code>atime</code> and <code>ctime</code> fields are used in making
incremental
+backups; they store, respectively, the particular file's access and
+status change times.
+</p>
+<p>The <code>offset</code> is used by the
‘<samp>--multi-volume</samp>’ (‘<samp>-M</samp>’)
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.
+</p>
+<p>The following fields were added to deal with sparse files. A file
+is <em>sparse</em> 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 <code>tar</code> uses to
+detect a sparse file, and once such a file is detected, it is treated
+differently from non-sparse files.
+</p>
+<p>Sparse files are often <code>dbm</code> 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</samp>’ 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 <code>tar</code> 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:
+</p>
+<p>The <code>sp</code> is an array of <code>struct sparse</code>. Each
<code>struct
+sparse</code> 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.
+</p>
+<p>The header can hold four of these <code>struct sparse</code> at the moment;
+if more are needed, they are not stored in the header.
+</p>
+<p>The <code>isextended</code> flag is set when an <code>extended_header</code>
+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.
+</p>
+<p>The <code>extended_header</code> 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</code>
+gets set and the next block is an <code>extended_header</code>.
+</p>
+<p>Each <code>extended_header</code> structure contains an array of 21
+sparse structures, along with a similar <code>isextended</code> flag
+that the header had. There can be an indeterminate number of such
+<code>extended_header</code>s to describe a sparse file.
+</p>
+<dl compact="compact">
+<dt> <code>REGTYPE</code></dt>
+<dt> <code>AREGTYPE</code></dt>
+<dd><p>These flags represent a regular file. In order to be compatible
+with older versions of <code>tar</code>, a <code>typeflag</code> value of
+<code>AREGTYPE</code> should be silently recognized as a regular file.
+New archives should be created using <code>REGTYPE</code>. Also, for
+backward compatibility, <code>tar</code> treats a regular file whose name
+ends with a slash as a directory.
+</p>
+</dd>
+<dt> <code>LNKTYPE</code></dt>
+<dd><p>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</code> field with a trailing null.
+</p>
+</dd>
+<dt> <code>SYMTYPE</code></dt>
+<dd><p>This represents a symbolic link to another file. The linked-to name
+is specified in the <code>linkname</code> field with a trailing null.
+</p>
+</dd>
+<dt> <code>CHRTYPE</code></dt>
+<dt> <code>BLKTYPE</code></dt>
+<dd><p>These represent character special files and block special files
+respectively. In this case the <code>devmajor</code> and <code>devminor</code>
+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.
+</p>
+</dd>
+<dt> <code>DIRTYPE</code></dt>
+<dd><p>This flag specifies a directory or sub-directory. The directory
+name in the <code>name</code> field should end with a slash. On systems where
+disk allocation is performed on a directory basis, the <code>size</code> 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</code> field of zero indicates no such limiting. Systems
+which do not support limiting in this manner should ignore the
+<code>size</code> field.
+</p>
+</dd>
+<dt> <code>FIFOTYPE</code></dt>
+<dd><p>This specifies a FIFO special file. Note that the archiving of a
+FIFO file archives the existence of this file and not its contents.
+</p>
+</dd>
+<dt> <code>CONTTYPE</code></dt>
+<dd><p>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.
+</p>
+</dd>
+<dt> <code>A</code> … <code>Z</code></dt>
+<dd><p>These are reserved for custom implementations. Some of these are
+used in the <acronym>GNU</acronym> modified format, as described below.
+</p>
+</dd>
+</dl>
+
+<p>Other values are reserved for specification in future revisions of
+the P1003 standard, and should not be used by any <code>tar</code> program.
+</p>
+<p>The <code>magic</code> field indicates that this archive was output in
+the P1003 archive format. If this field contains <code>TMAGIC</code>,
+the <code>uname</code> and <code>gname</code> 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</code> and <code>gid</code> fields.
+</p>
+<p>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</cite>; 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</cite>.
+</p>
+<hr size="6">
+<a name="Extensions"></a>
+<a name="SEC164"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC163" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC165" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="unnumberedsec"> <acronym>GNU</acronym> Extensions to the Archive
Format </h2>
+<blockquote><p><em>(This message will disappear, once this node revised.)</em>
+</p></blockquote>
+
+
+<p>The <acronym>GNU</acronym> format uses additional file types to describe
new types of
+files in an archive. These are listed below.
+</p>
+<dl compact="compact">
+<dt> <code>GNUTYPE_DUMPDIR</code></dt>
+<dt> <code>'D'</code></dt>
+<dd><p>This represents a directory and a list of files created by the
+‘<samp>--incremental</samp>’ (‘<samp>-G</samp>’)
option. The <code>size</code> field gives the total
+size of the associated list of files. Each file name is preceded by
+either a ‘<samp>Y</samp>’ (the file should be in this archive) or
an ‘<samp>N</samp>’.
+(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.
+</p>
+</dd>
+<dt> <code>GNUTYPE_MULTIVOL</code></dt>
+<dt> <code>'M'</code></dt>
+<dd><p>This represents a file continued from another volume of a multi-volume
+archive created with the ‘<samp>--multi-volume</samp>’
(‘<samp>-M</samp>’) option. The original
+type of the file is not given here. The <code>size</code> 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</code> field
+gives the offset from the beginning of the file where this part of
+the file begins. Thus <code>size</code> plus <code>offset</code> should equal
+the original size of the file.
+</p>
+</dd>
+<dt> <code>GNUTYPE_SPARSE</code></dt>
+<dt> <code>'S'</code></dt>
+<dd><p>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.
+</p>
+</dd>
+<dt> <code>GNUTYPE_VOLHDR</code></dt>
+<dt> <code>'V'</code></dt>
+<dd><p>This file type is used to mark the volume header that was given with
+the ‘<samp>--label=<var>archive-label</var></samp>’
(‘<samp>-V <var>archive-label</var></samp>’) option when the
archive was created. The <code>name</code>
+field contains the <code>name</code> given after the
‘<samp>--label=<var>archive-label</var></samp>’ (‘<samp>-V
<var>archive-label</var></samp>’) option.
+The <code>size</code> field is zero. Only the first file in each volume
+of an archive should have this type.
+</p>
+</dd>
+</dl>
+
+<p>You may have trouble reading a <acronym>GNU</acronym> format archive on a
+non-<acronym>GNU</acronym> system if the options
‘<samp>--incremental</samp>’ (‘<samp>-G</samp>’),
+‘<samp>--multi-volume</samp>’ (‘<samp>-M</samp>’),
‘<samp>--sparse</samp>’ (‘<samp>-S</samp>’), or
‘<samp>--label=<var>archive-label</var></samp>’ (‘<samp>-V
<var>archive-label</var></samp>’) were
+used when writing the archive. In general, if <code>tar</code> does not
+use the <acronym>GNU</acronym>-added fields of the header, other versions of
+<code>tar</code> should be able to read the archive. Otherwise, the
+<code>tar</code> program will give an error, the most likely one being a
+checksum error.
+</p>
+<hr size="6">
+<a name="Sparse-Formats"></a>
+<a name="SEC165"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC164" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC166" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="unnumberedsec"> Storing Sparse Files </h2>
+
+<p>The notion of sparse file, and the ways of handling it from the point
+of view of <acronym>GNU</acronym> <code>tar</code> user have been described in
detail in
+<a href="#SEC127">Archiving Sparse Files</a>. This chapter describes the
internal format <acronym>GNU</acronym> <code>tar</code>
+uses to store such files.
+</p>
+<p>The support for sparse files in <acronym>GNU</acronym> <code>tar</code> 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
+<em>old GNU</em> sparse format and in spite of the fact that its design
+contained many flaws, it was the only format <acronym>GNU</acronym>
<code>tar</code> supported
+until version 1.14 (May, 2004), which introduced initial support for
+sparse archives in <acronym>PAX</acronym> archives (see section <a
href="#SEC135"><acronym>GNU</acronym> <code>tar</code> and
<acronym>POSIX</acronym> <code>tar</code></a>). 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).
+</p>
+<p>In addition to GNU sparse format, <acronym>GNU</acronym> <code>tar</code>
is able to read and
+extract sparse files archived by <code>star</code>.
+</p>
+<p>The following subsections describe each format in detail.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC166">C.0.1 Old GNU
Format</a></td><td> </td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC167">C.0.2 PAX Format, Versions
0.0 and 0.1</a></td><td> </td><td align="left"
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC168">C.0.3 PAX Format, Version
1.0</a></td><td> </td><td align="left" valign="top"></td></tr>
+</table>
+
+<hr size="6">
+<a name="Old-GNU-Format"></a>
+<a name="SEC166"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC165" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC167" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC165" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="appendixsubsec"> C.0.1 Old GNU Format </h3>
+
+<p>The format introduced some time around 1990 (v. 1.09). It was
+designed on top of standard <code>ustar</code> headers in such an
+unfortunate way that some of its fields overwrote fields required by
+POSIX.
+</p>
+<p>An old GNU sparse header is designated by type ‘<samp>S</samp>’
+(<code>GNUTYPE_SPARSE</code>) and has the following layout:
+</p>
+<table>
+<thead><tr><th><p> Offset </p></th><th><p> Size </p></th><th><p> Name
</p></th><th><p> Data type </p></th><th><p> Contents
+</p></th></tr></thead>
+<tr><td><p> 0 </p></td><td><p> 345 </p></td><td> </td><td><p>
N/A </p></td><td><p> Not used.
+</p></td></tr>
+<tr><td><p> 345 </p></td><td><p> 12 </p></td><td><p> atime
</p></td><td><p> Number </p></td><td><p> <code>atime</code> of the file.
+</p></td></tr>
+<tr><td><p> 357 </p></td><td><p> 12 </p></td><td><p> ctime
</p></td><td><p> Number </p></td><td><p> <code>ctime</code> of the file .
+</p></td></tr>
+<tr><td><p> 369 </p></td><td><p> 12 </p></td><td><p> offset
</p></td><td><p> Number </p></td><td><p> For
+multivolume archives: the offset of the start of this volume.
+</p></td></tr>
+<tr><td><p> 381 </p></td><td><p> 4 </p></td><td> </td><td><p>
N/A </p></td><td><p> Not used.
+</p></td></tr>
+<tr><td><p> 385 </p></td><td><p> 1 </p></td><td> </td><td><p>
N/A </p></td><td><p> Not used.
+</p></td></tr>
+<tr><td><p> 386 </p></td><td><p> 96 </p></td><td><p> sp
</p></td><td><p> <code>sparse_header</code> </p></td><td><p> (4 entries) File
map.
+</p></td></tr>
+<tr><td><p> 482 </p></td><td><p> 1 </p></td><td><p> isextended
</p></td><td><p> Bool </p></td><td><p> <code>1</code> if an
+extension sparse header follows, <code>0</code> otherwise.
+</p></td></tr>
+<tr><td><p> 483 </p></td><td><p> 12 </p></td><td><p> realsize
</p></td><td><p> Number </p></td><td><p> Real size of the file.
+</p></td></tr>
+</table>
+
+<p>Each of <code>sparse_header</code> object at offset 386 describes a single
+data chunk. It has the following structure:
+</p>
+<table>
+<thead><tr><th><p> Offset </p></th><th><p> Size </p></th><th><p> Data type
</p></th><th><p> Contents
+</p></th></tr></thead>
+<tr><td><p> 0 </p></td><td><p> 12 </p></td><td><p> Number
</p></td><td><p> Offset of the
+beginning of the chunk.
+</p></td></tr>
+<tr><td><p> 12 </p></td><td><p> 12 </p></td><td><p> Number
</p></td><td><p> Size of the chunk.
+</p></td></tr>
+</table>
+
+<p>If the member contains more than four chunks, the <code>isextended</code>
+field of the header has the value <code>1</code> and the main header is
+followed by one or more <em>extension headers</em>. Each such header has
+the following structure:
+</p>
+<table>
+<thead><tr><th><p> Offset </p></th><th><p> Size </p></th><th><p> Name
</p></th><th><p> Data type </p></th><th><p> Contents
+</p></th></tr></thead>
+<tr><td><p> 0 </p></td><td><p> 21 </p></td><td><p> sp
</p></td><td><p> <code>sparse_header</code> </p></td><td>
+<p>(21 entires) File map.
+</p></td></tr>
+<tr><td><p> 504 </p></td><td><p> 1 </p></td><td><p> isextended
</p></td><td><p> Bool </p></td><td><p> <code>1</code> if an
+extension sparse header follows, or <code>0</code> otherwise.
+</p></td></tr>
+</table>
+
+<p>A header with <code>isextended=0</code> ends the map.
+</p>
+<hr size="6">
+<a name="PAX-0"></a>
+<a name="SEC167"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC166" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC168" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC165" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="appendixsubsec"> C.0.2 PAX Format, Versions 0.0 and 0.1 </h3>
+
+<p>There are two formats available in this branch. The version
<code>0.0</code>
+is the initial version of sparse format used by <code>tar</code>
+versions 1.14–1.15.1. The sparse file map is kept in extended
+(<code>x</code>) PAX header variables:
+</p>
+<dl compact="compact">
+<dd><a name="IDX464"></a>
+</dd>
+<dt> <code>GNU.sparse.size</code></dt>
+<dd><p>Real size of the stored file
+</p>
+</dd>
+<dt> <code>GNU.sparse.numblocks</code></dt>
+<dd><a name="IDX465"></a>
+<p>Number of blocks in the sparse map
+</p>
+</dd>
+<dt> <code>GNU.sparse.offset</code></dt>
+<dd><a name="IDX466"></a>
+<p>Offset of the data block
+</p>
+</dd>
+<dt> <code>GNU.sparse.numbytes</code></dt>
+<dd><a name="IDX467"></a>
+<p>Size of the data block
+</p></dd>
+</dl>
+
+<p>The latter two variables repeat for each data block, so the overall
+structure is like this:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">GNU.sparse.size=<var>size</var>
+GNU.sparse.numblocks=<var>numblocks</var>
+repeat <var>numblocks</var> times
+ GNU.sparse.offset=<var>offset</var>
+ GNU.sparse.numbytes=<var>numbytes</var>
+end repeat
+</pre></td></tr></table>
+
+<p>This format presented the following two problems:
+</p>
+<ol>
+<li>
+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</code> and
+<code>GNU.sparse.numbytes</code> are conficting with the POSIX specs.
+
+</li><li>
+Attempting to extract such archives using a third-party <code>tar</code>s
+results in extraction of sparse files in <em>compressed form</em>. If
+the <code>tar</code> 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 <code>tar</code>s will usually ignore the
+unknown variables, which makes restoring the file more
+difficult. See <a href="#extracting-sparse-v_002e0_002ex">Extraction of
sparse members in v.0.0 format</a>, for the detailed description of how to
+restore such members using non-GNU <code>tar</code>s.
+</li></ol>
+
+<a name="IDX468"></a>
+<p><acronym>GNU</acronym> <code>tar</code> 1.15.2 introduced sparse format
version <code>0.1</code>, which
+attempted to solve these problems. As its predecessor, this format
+stores sparse map in the extended POSIX header. It retains
+<code>GNU.sparse.size</code> and <code>GNU.sparse.numblocks</code> variables,
but
+instead of <code>GNU.sparse.offset</code>/<code>GNU.sparse.numbytes</code>
pairs
+it uses a single variable:
+</p>
+<dl compact="compact">
+<dt> <code>GNU.sparse.map</code></dt>
+<dd><a name="IDX469"></a>
+<p>Map of non-null data chunks. It is a string consisting of
+comma-separated values
"<var>offset</var>,<var>size</var>[,<var>offset-1</var>,<var>size-1</var>...]"
+</p></dd>
+</dl>
+
+<p>To address the 2nd problem, the <code>name</code> field in
<code>ustar</code>
+is replaced with a special name, constructed using the following pattern:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">%d/GNUSparseFile.%p/%f
+</pre></td></tr></table>
+
+<a name="IDX470"></a>
+<p>The real name of the sparse file is stored in the variable
+<code>GNU.sparse.name</code>. Thus, those <code>tar</code> 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. See <a href="#extracting-sparse-v_002e0_002ex">Extraction of
sparse members in v.0.1 format</a>, for the detailed description of how to
+restore such members using non-GNU <code>tar</code>s.
+</p>
+<p>The resulting <code>GNU.sparse.map</code> string can be <em>very</em> long.
+Although POSIX does not impose any limit on the length of a <code>x</code>
+header variable, this possibly can confuse some tars.
+</p>
+<hr size="6">
+<a name="PAX-1"></a>
+<a name="SEC168"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC167" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC169" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC165" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="appendixsubsec"> C.0.3 PAX Format, Version 1.0 </h3>
+
+<p>The version <code>1.0</code> of sparse format was introduced with
<acronym>GNU</acronym> <code>tar</code>
+1.15.92. Its main objective was to make the resulting file
+extractable with little effort even by non-posix aware <code>tar</code>
+implementations. Starting from this version, the extended header
+preceding a sparse member always contains the following variables that
+identify the format being used:
+</p>
+<dl compact="compact">
+<dt> <code>GNU.sparse.major</code></dt>
+<dd><a name="IDX471"></a>
+<p>Major version
+</p>
+</dd>
+<dt> <code>GNU.sparse.minor</code></dt>
+<dd><a name="IDX472"></a>
+<p>Minor version
+</p></dd>
+</dl>
+
+<p>The <code>name</code> field in <code>ustar</code> header contains a special
name,
+constructed using the following pattern:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">%d/GNUSparseFile.%p/%f
+</pre></td></tr></table>
+
+<a name="IDX473"></a>
+<a name="IDX474"></a>
+<p>The real name of the sparse file is stored in the variable
+<code>GNU.sparse.name</code>. The real size of the file is stored in the
+variable <code>GNU.sparse.realsize</code>.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>The format is designed in such a way that non-posix aware tars and tars not
+supporting <code>GNU.sparse.*</code> 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</acronym> <code>tar</code>.
+See section <a href="#SEC141">Extracting Sparse Members</a>, for the detailed
information on how to extract
+sparse members without <acronym>GNU</acronym> <code>tar</code>.
+</p>
+
+<hr size="6">
+<a name="Snapshot-Files"></a>
+<a name="SEC169"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC168" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC170" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="unnumberedsec"> Format of the Incremental Snapshot Files </h2>
+
+<p> A <em>snapshot file</em> (or <em>directory file</em>) is created during
+incremental backups (see section <a href="#SEC88">Using <code>tar</code> to
Perform Incremental Dumps</a>). 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.
+</p>
+<p> <acronym>GNU</acronym> <code>tar</code> version 1.15.92 supports two
snapshot file
+formats. The first format, called <em>format 0</em>, is the one used by
+<acronym>GNU</acronym> <code>tar</code> versions up to 1.15.1. The second
format, called <em>format
+1</em> is an extended version of this format, that contains more metadata
+and allows for further extensions.
+</p>
+<p> ‘<samp>Format 0</samp>’ 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:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">[<var>nfs</var>]<var>dev</var> <var>inode</var>
<var>name</var>
+</pre></td></tr></table>
+
+<p>where optional <var>nfs</var> is a single plus character
(‘<samp>+</samp>’) if this
+directory is located on an NFS-mounted partition, <var>dev</var> and
+<var>inode</var> are the device and inode numbers of the directory, and
+<var>name</var> is the directory name.
+</p>
+<p> ‘<samp>Format 1</samp>’ snapshot file begins with a line
specifying the
+format of the file. This line has the following structure:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">‘<samp>GNU
tar-</samp>’<var>tar-version</var>‘<samp>-</samp>’<var>incr-format-version</var>
+</pre></td></tr></table>
+
+<p>where <var>tar-version</var> is the version of <acronym>GNU</acronym>
<code>tar</code> implementation
+that created this snapshot, and <var>incr-format-version</var> is the
+version number of the snapshot format (in this case
‘<samp>1</samp>’).
+</p>
+<p> 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.
+</p>
+<p> Following lines contain directory metadate, one line per
+directory. The line format is:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">[<var>nfs</var>]<var>mtime-sec</var> <var>mtime-nsec</var>
<var>dev</var> <var>inode</var> <var>name</var>
+</pre></td></tr></table>
+
+<p>where <var>mtime-sec</var> and <var>mtime-nsec</var> represent the last
+modification time of this directory with nanosecond precision;
+<var>nfs</var>, <var>dev</var>, <var>inode</var> and <var>name</var> have the
same meaning
+as with ‘<samp>format 0</samp>’.
+</p>
+
+
+
+
+<hr size="6">
+<a name="Dumpdir"></a>
+<a name="SEC170"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC169" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="unnumberedsec"> Dumpdir </h2>
+
+<p> Incremental archives keep information about contents of each
+dumped directory in special data blocks called <em>dumpdirs</em>.
+</p>
+<p> Dumpdir is a sequence of entries of the following form:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"><var>C</var>
<var>filename</var> \0
+</pre></td></tr></table>
+
+<p>where <var>C</var> is one of the <em>control codes</em> described below,
+<var>filename</var> is the name of the file <var>C</var> operates upon, and
+‘<samp>\0</samp>’ represents a nul character (ASCII 0). The white
space
+characters were added for readability, real dumpdirs do not contain
+them.
+</p>
+<p> Each dumpdir ends with a single nul character.
+</p>
+<p> The following table describes control codes and their meanings:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>Y</samp>’</dt>
+<dd><p><var>filename</var> is contained in the archive.
+</p>
+</dd>
+<dt> ‘<samp>N</samp>’</dt>
+<dd><p><var>filename</var> 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.
+</p>
+</dd>
+<dt> ‘<samp>D</samp>’</dt>
+<dd><p><var>filename</var> is a directory.
+</p>
+</dd>
+<dt> ‘<samp>R</samp>’</dt>
+<dd><p>This code requests renaming of the <var>filename</var> to the name
+specified with the following ‘<samp>T</samp>’ command.
+</p>
+</dd>
+<dt> ‘<samp>T</samp>’</dt>
+<dd><p>Specify target file name for ‘<samp>R</samp>’ command (see
below).
+</p>
+</dd>
+<dt> ‘<samp>X</samp>’</dt>
+<dd><p>Specify <em>temporary directory</em> name for a rename operation (see
below).
+</p></dd>
+</dl>
+
+<p> Codes ‘<samp>Y</samp>’, ‘<samp>N</samp>’ and
‘<samp>D</samp>’ require <var>filename</var> argument
+to be a relative file name to the directory this dumpdir describes,
+whereas codes ‘<samp>R</samp>’, ‘<samp>T</samp>’ and
‘<samp>X</samp>’ require their argument
+to be an absolute file name.
+</p>
+<p> The three codes ‘<samp>R</samp>’, ‘<samp>T</samp>’
and ‘<samp>X</samp>’ specify a
+<em>renaming operation</em>. In the simplest case it is:
+</p>
+<table><tr><td> </td><td><pre
class="smallexample">R‘<tt>source</tt>’\0T‘<tt>dest</tt>’\0
+</pre></td></tr></table>
+
+<p>which means “rename file ‘<tt>source</tt>’ to file
‘<tt>dest</tt>’”.
+</p>
+<p> However, there are cases that require using a <em>temporary
+directory</em>. For example, consider the following scenario:
+</p>
+<ol>
+<li>
+Previous run dumped a directory ‘<tt>foo</tt>’ which contained the
+following three directories:
+
+<table><tr><td> </td><td><pre class="smallexample">a
+b
+c
+</pre></td></tr></table>
+
+</li><li>
+They were renamed <em>cyclically</em>, so that:
+
+<table><tr><td> </td><td><pre class="example">‘<tt>a</tt>’
became ‘<tt>b</tt>’
+‘<tt>b</tt>’ became ‘<tt>c</tt>’
+‘<tt>c</tt>’ became ‘<tt>a</tt>’
+</pre></td></tr></table>
+
+</li><li>
+New incremental dump was made.
+</li></ol>
+
+<p> This case cannot be handled by three successive renames, since
+renaming ‘<tt>a</tt>’ to ‘<tt>b</tt>’ will destroy
existing directory.
+To handle such case a temporary directory is required. <acronym>GNU</acronym>
<code>tar</code>
+will create the following dumpdir (newlines have been added for
+readability):
+</p>
+<table><tr><td> </td><td><pre class="smallexample">Xfoo\0
+Rfoo/a\0T\0
+Rfoo/b\0Tfoo/c\0
+Rfoo/c\0Tfoo/a\0
+R\0Tfoo/a\0
+</pre></td></tr></table>
+
+<p> The first command, ‘<samp>Xfoo\0</samp>’, instructs the
extractor to create a
+temporary directory in the directory ‘<tt>foo</tt>’. Second
command,
+‘<samp>Rfoo/aT\0</samp>’, says “rename file
‘<tt>foo/a</tt>’ 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</samp>’
+tells tar to rename the temporary directory to ‘<tt>foo/a</tt>’.
+</p>
+<p> The exact placement of a dumpdir in the archive depends on the
+archive format (see section <a href="#SEC124">Controlling the Archive
Format</a>):
+</p>
+<ul class="toc">
+<li> PAX archives
+
+<p>In PAX archives, dumpdir is stored in the extended header of the
+corresponding directory, in variable <code>GNU.dumpdir</code>.
+</p>
+</li><li> GNU and old GNU archives
+
+<p>These formats implement special header type ‘<samp>D</samp>’,
which is similar
+to ustar header ‘<samp>5</samp>’ (directory), except that it
preceeds a data
+block containing the dumpdir.
+</p></li></ul>
+
+
+
+<hr size="6">
+<a name="Genfile"></a>
+<a name="SEC171"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC170" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC172" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC175" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="appendix"> D. Genfile </h1>
+
+<p> This appendix describes <code>genfile</code>, an auxiliary program
+used in the GNU tar testsuite. If you are not interested in developing
+GNU tar, skip this appendix.
+</p>
+<p> Initially, <code>genfile</code> 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
+<code>genfile</code> is a multi-purpose instrument.
+</p>
+<p> There are three basic operation modes:
+</p>
+<dl compact="compact">
+<dt> File Generation</dt>
+<dd><p> This is the default mode. In this mode, <code>genfile</code>
+generates data files.
+</p>
+</dd>
+<dt> File Status</dt>
+<dd><p> In this mode <code>genfile</code> displays status of specified
files.
+</p>
+</dd>
+<dt> Synchronous Execution.</dt>
+<dd><p> In this mode <code>genfile</code> executes the given program with
+‘<samp>--checkpoint</samp>’ option and executes a set of actions
when
+specified checkpoints are reached.
+</p></dd>
+</dl>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC172">D.1 Generate
Mode</a></td><td> </td><td align="left" valign="top"> File
Generation Mode.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC173">D.2 Status
Mode</a></td><td> </td><td align="left" valign="top"> File
Status Mode.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC174">D.3 Exec
Mode</a></td><td> </td><td align="left" valign="top">
Synchronous Execution mode.
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Generate-Mode"></a>
+<a name="SEC172"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC171" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC173" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC175" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="appendixsec"> D.1 Generate Mode </h2>
+
+<p> In this mode <code>genfile</code> creates a data file for the test
+suite. The size of the file is given with the
‘<samp>--length</samp>’
+(‘<samp>-l</samp>’) option. By default the file contents is
written to the
+standard output, this can be changed using ‘<samp>--file</samp>’
+(‘<samp>-f</samp>’) command line option. Thus, the following two
commands
+are equivalent:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">genfile --length 100
> outfile
+genfile --length 100 --file outfile
+</pre></td></tr></table>
+
+<p> If ‘<samp>--length</samp>’ is not given,
<code>genfile</code> will
+generate an empty (zero-length) file.
+</p>
+<a name="IDX475"></a>
+<p> You can instruct <code>genfile</code> to create several files at one
+go, by giving it ‘<samp>--files-from</samp>’
(‘<samp>-T</samp>’) option followed
+by a name of file containing a list of file names. Using dash
+(‘<samp>-</samp>’) instead of the file name causes
<code>genfile</code> to read
+file list from the standard input. For example:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"># Read file names from
file ‘<tt>file.list</tt>’
+genfile --files-from file.list
+# Read file names from standard input
+genfile --files-from -
+</pre></td></tr></table>
+
+<a name="IDX476"></a>
+<p> The list file is supposed to contain one file name per line. To
+use file lists separated by ASCII NUL character, use
‘<samp>--null</samp>’
+(‘<samp>-0</samp>’) command line option:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">genfile --null
--files-from file.list
+</pre></td></tr></table>
+
+<a name="IDX477"></a>
+<p> 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
‘<samp>--pattern</samp>’
+option. This option takes a mandatory argument, specifying pattern
+name to use. Currently two patterns are implemented:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--pattern=default</samp>’</dt>
+<dd><p> The default pattern as described above.
+</p>
+</dd>
+<dt> ‘<samp>--pattern=zero</samp>’</dt>
+<dd><p> Fills the file with zeroes.
+</p></dd>
+</dl>
+
+<p> If no file name was given, the program exits with the code
+<code>0</code>. Otherwise, it exits with <code>0</code> only if it was able to
+create a file of the specified length.
+</p>
+<a name="IDX478"></a>
+<a name="IDX479"></a>
+<p> Special option ‘<samp>--sparse</samp>’
(‘<samp>-s</samp>’) instructs
+<code>genfile</code> to create a sparse file. Sparse files consist of
+<em>data fragments</em>, separated by <em>holes</em> 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, <code>genfile</code> should know where to put data fragments,
+and what data to use to fill them. So, when
‘<samp>--sparse</samp>’ is given
+the rest of the command line specifies a so-called <em>file map</em>.
+</p>
+<p> The file map consists of any number of <em>fragment
+descriptors</em>. 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
+<em>contents string</em>, i.e. a string of characters, specifying the
+pattern to fill the fragment with. File offset can be suffixed with
+the following quantifiers:
+</p>
+<dl compact="compact">
+<dt> ‘<samp>k</samp>’</dt>
+<dt> ‘<samp>K</samp>’</dt>
+<dd><p>The number is expressed in kilobytes.
+</p></dd>
+<dt> ‘<samp>m</samp>’</dt>
+<dt> ‘<samp>M</samp>’</dt>
+<dd><p>The number is expressed in megabytes.
+</p></dd>
+<dt> ‘<samp>g</samp>’</dt>
+<dt> ‘<samp>G</samp>’</dt>
+<dd><p>The number is expressed in gigabytes.
+</p></dd>
+</dl>
+
+<p> For each letter in contents string <code>genfile</code> will generate
+a <em>block</em> of data, filled with this letter and will write it to
+the fragment. The size of block is given by
‘<samp>--block-size</samp>’
+option. It defaults to 512. Thus, if the string consists of <var>n</var>
+characters, the resulting file fragment will contain
+<code><var>n</var>*<var>block-size</var></code> of data.
+</p>
+<p> Last fragment descriptor can have only file offset part. In this
+case <code>genfile</code> will create a hole at the end of the file up to
+the given offset.
+</p>
+<p> For example, consider the following invocation:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">genfile --sparse
--file sparsefile 0 ABCD 1M EFGHI 2000K
+</pre></td></tr></table>
+
+<p>It will create 3101184-bytes long file of the following structure:
+</p>
+<table>
+<tr><td><p> Offset </p></td><td><p> Length </p></td><td><p> Contents
+</p></td></tr>
+<tr><td><p> 0 </p></td><td><p> 4*512=2048 </p></td><td><p> Four
512-byte blocks, filled with
+letters ‘<samp>A</samp>’, ‘<samp>B</samp>’,
‘<samp>C</samp>’ and ‘<samp>D</samp>’.
+</p></td></tr>
+<tr><td><p> 2048 </p></td><td><p> 1046528 </p></td><td><p> Zero bytes
+</p></td></tr>
+<tr><td><p> 1050624 </p></td><td><p> 5*512=2560 </p></td><td><p> Five
blocks, filled with letters
+‘<samp>E</samp>’, ‘<samp>F</samp>’,
‘<samp>G</samp>’, ‘<samp>H</samp>’,
‘<samp>I</samp>’.
+</p></td></tr>
+<tr><td><p> 1053184 </p></td><td><p> 2048000 </p></td><td><p> Zero bytes
+</p></td></tr>
+</table>
+
+<p> The exit code of <code>genfile --status</code> command is <code>0</code>
+only if created file is actually sparse.
+</p>
+<hr size="6">
+<a name="Status-Mode"></a>
+<a name="SEC173"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC172" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC174" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC175" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="appendixsec"> D.2 Status Mode </h2>
+
+<p> In status mode, <code>genfile</code> prints file system status for
+each file specified in the command line. This mode is toggled by
+‘<samp>--stat</samp>’ (‘<samp>-S</samp>’) command line
option. An optional argument to this
+option specifies output <em>format</em>: a comma-separated list of
+<code>struct stat</code> fields to be displayed. This list can contain
+following identifiers
+
+:
+</p>
+<dl compact="compact">
+<dt> name</dt>
+<dd><p> The file name.
+</p>
+</dd>
+<dt> dev</dt>
+<dt> st_dev</dt>
+<dd><p> Device number in decimal.
+</p>
+</dd>
+<dt> ino</dt>
+<dt> st_ino</dt>
+<dd><p> Inode number.
+</p>
+</dd>
+<dt> mode[.<var>number</var>]</dt>
+<dt> st_mode[.<var>number</var>]</dt>
+<dd><p> File mode in octal. Optional <var>number</var> specifies octal
mask to
+be applied to the mode before outputting. For example, <code>--stat
+mode.777</code> will preserve lower nine bits of it. Notice, that you can
+use any punctuation caracter in place of ‘<samp>.</samp>’.
+</p>
+</dd>
+<dt> nlink</dt>
+<dt> st_nlink</dt>
+<dd><p> Number of hard links.
+</p>
+</dd>
+<dt> uid</dt>
+<dt> st_uid</dt>
+<dd><p> User ID of owner.
+</p>
+</dd>
+<dt> gid</dt>
+<dt> st_gid</dt>
+<dd><p> Group ID of owner.
+</p>
+</dd>
+<dt> size</dt>
+<dt> st_size</dt>
+<dd><p> File size in decimal.
+</p>
+</dd>
+<dt> blksize</dt>
+<dt> st_blksize</dt>
+<dd><p> The size in bytes of each file block.
+</p>
+</dd>
+<dt> blocks</dt>
+<dt> st_blocks</dt>
+<dd><p> Number of blocks allocated.
+</p>
+</dd>
+<dt> atime</dt>
+<dt> st_atime</dt>
+<dd><p> Time of last access.
+</p>
+</dd>
+<dt> mtime</dt>
+<dt> st_mtime</dt>
+<dd><p> Time of last modification
+</p>
+</dd>
+<dt> ctime</dt>
+<dt> st_ctime</dt>
+<dd><p> Time of last status change
+</p>
+</dd>
+<dt> sparse</dt>
+<dd><p> A boolean value indicating whether the file is
‘<samp>sparse</samp>’.
+</p></dd>
+</dl>
+
+<p> Modification times are displayed in <acronym>UTC</acronym> as
+<acronym>UNIX</acronym> timestamps, unless suffixed with
‘<samp>H</samp>’ (for
+“human-readable”), as in ‘<samp>ctimeH</samp>’, in
which case usual
+<code>tar tv</code> output format is used.
+</p>
+<p> The default output format is: ‘<samp>name,dev,ino,mode,
+nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime</samp>’.
+</p>
+<p> For example, the following command will display file names and
+corresponding times of last access for each file in the current working
+directory:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">genfile
--stat=name,atime *
+</pre></td></tr></table>
+
+<hr size="6">
+<a name="Exec-Mode"></a>
+<a name="SEC174"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC173" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC175" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC175" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="appendixsec"> D.3 Exec Mode </h2>
+
+<p> This mode is designed for testing the behavior of <code>paxutils</code>
+commands when some of the files change during archiving. It is an
+experimental mode.
+</p>
+<p> The ‘<samp>Exec Mode</samp>’ is toggled by
‘<samp>--run</samp>’ command line
+option (or its alias ‘<samp>-r</samp>’). The argument to this
option gives
+the command line to be executed. The actual command line is
+constructed by inserting ‘<samp>--checkpoint</samp>’ option
between the
+command name and its first argument (if any). Due to this, the
+argument to ‘<samp>--run</samp>’ may not use traditional
<code>tar</code>
+option syntax, i.e. the following is wrong:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"># Wrong!
+genfile --run 'tar cf foo bar'
+</pre></td></tr></table>
+
+
+<p>Use the following syntax instead:
+</p>
+<table><tr><td> </td><td><pre class="smallexample">genfile --run 'tar -cf
foo bar'
+</pre></td></tr></table>
+
+<p> The rest of command line after ‘<samp>--run</samp>’ or its
equivalent
+specifies checkpoint values and actions to be executed upon reaching
+them. Checkpoint values are introduced with
‘<samp>--checkpoint</samp>’
+command line option. Argument to this option is the number of
+checkpoint in decimal.
+</p>
+<p> Any number of <em>actions</em> may be specified after a
+checkpoint. Available actions are
+</p>
+<dl compact="compact">
+<dt> ‘<samp>--cut <var>file</var></samp>’</dt>
+<dt> ‘<samp>--truncate <var>file</var></samp>’</dt>
+<dd><p> Truncate <var>file</var> to the size specified by previous
+‘<samp>--length</samp>’ option (or 0, if it is not given).
+</p>
+</dd>
+<dt> ‘<samp>--append <var>file</var></samp>’</dt>
+<dd><p> Append data to <var>file</var>. The size of data and its pattern are
+given by previous ‘<samp>--length</samp>’ and
‘<samp>pattern</samp>’ options.
+</p>
+</dd>
+<dt> ‘<samp>--touch <var>file</var></samp>’</dt>
+<dd><p> Update the access and modification times of <var>file</var>. These
+timestamps are changed to the current time, unless
‘<samp>--date</samp>’
+option was given, in which case they are changed to the specified
+time. Argument to ‘<samp>--date</samp>’ option is a date
specification in
+an almost arbitrary format (see section <a href="#SEC113">Date input
formats</a>).
+</p>
+</dd>
+<dt> ‘<samp>--exec <var>command</var></samp>’</dt>
+<dd><p> Execute given shell command.
+</p>
+</dd>
+</dl>
+
+<p> Option ‘<samp>--verbose</samp>’ instructs
<code>genfile</code> to print on
+standard output notifications about checkpoints being executed and to
+verbosely describe exit status of the command.
+</p>
+<p> 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.
+</p>
+<p> <code>Genfile</code> exits with the exit status of the executed command.
+</p>
+<hr size="6">
+<a name="Free-Software-Needs-Free-Documentation"></a>
+<a name="SEC175"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC174" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC176" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC171" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC176" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="appendix"> E. Free Software Needs Free Documentation </h1>
+
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>However, it must be possible to modify all the <em>technical</em>
+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.
+</p>
+<p>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.
+</p>
+<p>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 <a href="mailto:address@hidden";>address@hidden</a>.
+</p>
+<p>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.
+</p>
+<p>The Free Software Foundation maintains a list of free documentation
+published by other publishers, at
+<a
href="http://www.fsf.org/doc/other-free-books.html";>http://www.fsf.org/doc/other-free-books.html</a>.
+</p>
+<hr size="6">
+<a name="Copying-This-Manual"></a>
+<a name="SEC176"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC175" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC177" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC175" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="appendix"> F. Copying This Manual </h1>
+
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC177">F.1 GNU Free Documentation
License</a></td><td> </td><td align="left" valign="top"> License
for copying this manual
+</td></tr>
+</table>
+
+
+<hr size="6">
+<a name="GNU-Free-Documentation-License"></a>
+<a name="SEC177"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC176" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC178" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC176" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC176" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h2 class="appendixsec"> F.1 GNU Free Documentation License </h2>
+
+<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
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+</pre></td></tr></table>
+
+<ol>
+<li>
+PREAMBLE
+
+<p>The purpose of this License is to make a manual, textbook, or other
+functional and useful document <em>free</em> 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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+</li><li>
+APPLICABILITY AND DEFINITIONS
+
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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”.
+</p>
+<p>Examples of suitable formats for Transparent copies include plain
+<small>ASCII</small> without markup, Texinfo input format, LaTeX input
+format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly
available
+<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>,
+PostScript or <acronym>PDF</acronym> designed for human modification. Examples
+of transparent image formats include <acronym>PNG</acronym>,
<acronym>XCF</acronym> and
+<acronym>JPG</acronym>. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, <acronym>SGML</acronym> or
+<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing
tools are
+not generally available, and the machine-generated <acronym>HTML</acronym>,
+PostScript or <acronym>PDF</acronym> produced by some word processors for
+output purposes only.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+</li><li>
+VERBATIM COPYING
+
+<p>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.
+</p>
+<p>You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+</p>
+</li><li>
+COPYING IN QUANTITY
+
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+</li><li>
+MODIFICATIONS
+
+<p>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:
+</p>
+<ol>
+<li>
+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.
+
+</li><li>
+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.
+
+</li><li>
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+</li><li>
+Preserve all the copyright notices of the Document.
+
+</li><li>
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+</li><li>
+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.
+
+</li><li>
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+</li><li>
+Include an unaltered copy of this License.
+
+</li><li>
+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.
+
+</li><li>
+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.
+
+</li><li>
+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.
+
+</li><li>
+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.
+
+</li><li>
+Delete any section Entitled “Endorsements”. Such a section
+may not be included in the Modified Version.
+
+</li><li>
+Do not retitle any existing section to be Entitled “Endorsements”
or
+to conflict in title with any Invariant Section.
+
+</li><li>
+Preserve any Warranty Disclaimers.
+</li></ol>
+
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.
+</p>
+</li><li>
+COMBINING DOCUMENTS
+
+<p>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.
+</p>
+<p>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.
+</p>
+<p>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.”
+</p>
+</li><li>
+COLLECTIONS OF DOCUMENTS
+
+<p>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.
+</p>
+<p>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.
+</p>
+</li><li>
+AGGREGATION WITH INDEPENDENT WORKS
+
+<p>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.
+</p>
+<p>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.
+</p>
+</li><li>
+TRANSLATION
+
+<p>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.
+</p>
+<p>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.
+</p>
+</li><li>
+TERMINATION
+
+<p>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.
+</p>
+</li><li>
+FUTURE REVISIONS OF THIS LICENSE
+
+<p>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
+<a href="http://www.gnu.org/copyleft/";>http://www.gnu.org/copyleft/</a>.
+</p>
+<p>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.
+</p></li></ol>
+
+
+<hr size="6">
+<a name="SEC178"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC177" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC176" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC177" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h3 class="appendixsubsec"> F.1.1 ADDENDUM: How to use this License for your
documents </h3>
+
+<p>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:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"> Copyright (C)
<var>year</var> <var>your name</var>.
+ 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''.
+</pre></td></tr></table>
+
+<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the “with...Texts.” line with this:
+</p>
+<table><tr><td> </td><td><pre class="smallexample"> with the Invariant
Sections being <var>list their titles</var>, with
+ the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
+ being <var>list</var>.
+</pre></td></tr></table>
+
+<p>If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+</p>
+<p>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.
+</p>
+
+
+<hr size="6">
+<a name="Index-of-Command-Line-Options"></a>
+<a name="SEC179"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC178" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC180" title="Next section in
reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC176" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC180" title="Next chapter">
>> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="appendix"> G. Index of Command Line Options </h1>
+
+<p>This appendix contains an index of all <acronym>GNU</acronym>
<code>tar</code> long command line
+options. The options are listed without the preceeding double-dash.
+For a cross-reference of short command line options, <a href="#SEC43">Short
Options Cross Reference</a>.
+</p>
+<table><tr><th valign="top">Jump to: </th><td><a href="#SEC179_0"
class="summary-letter"><b>A</b></a>
+
+<a href="#SEC179_1" class="summary-letter"><b>B</b></a>
+
+<a href="#SEC179_2" class="summary-letter"><b>C</b></a>
+
+<a href="#SEC179_3" class="summary-letter"><b>D</b></a>
+
+<a href="#SEC179_4" class="summary-letter"><b>E</b></a>
+
+<a href="#SEC179_5" class="summary-letter"><b>F</b></a>
+
+<a href="#SEC179_6" class="summary-letter"><b>G</b></a>
+
+<a href="#SEC179_7" class="summary-letter"><b>H</b></a>
+
+<a href="#SEC179_8" class="summary-letter"><b>I</b></a>
+
+<a href="#SEC179_9" class="summary-letter"><b>K</b></a>
+
+<a href="#SEC179_10" class="summary-letter"><b>L</b></a>
+
+<a href="#SEC179_11" class="summary-letter"><b>M</b></a>
+
+<a href="#SEC179_12" class="summary-letter"><b>N</b></a>
+
+<a href="#SEC179_13" class="summary-letter"><b>O</b></a>
+
+<a href="#SEC179_14" class="summary-letter"><b>P</b></a>
+
+<a href="#SEC179_15" class="summary-letter"><b>Q</b></a>
+
+<a href="#SEC179_16" class="summary-letter"><b>R</b></a>
+
+<a href="#SEC179_17" class="summary-letter"><b>S</b></a>
+
+<a href="#SEC179_18" class="summary-letter"><b>T</b></a>
+
+<a href="#SEC179_19" class="summary-letter"><b>U</b></a>
+
+<a href="#SEC179_20" class="summary-letter"><b>V</b></a>
+
+<a href="#SEC179_21" class="summary-letter"><b>W</b></a>
+
+</td></tr></table>
+<table border="0" class="index-op">
+<tr><td></td><th align="left">Index Entry</th><th align="left">
Section</th></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_0">A</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX348"><code>absolute-names</code></a></td><td valign="top"><a
href="#SEC112">6.10.2 Absolute File Names</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX43"><code>absolute-names<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX305"><code>add-file</code></a></td><td valign="top"><a
href="#SEC100">6.3 Reading Names from a File</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX334"><code>after-date</code></a></td><td valign="top"><a
href="#SEC108">6.8 Operating Only on New Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX44"><code>after-date<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX320"><code>anchored</code></a></td><td valign="top"><a
href="#SEC105">Controlling Pattern-Matching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX45"><code>anchored<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX176"><code>append</code></a></td><td valign="top"><a
href="#SEC52">4.2.2 How to Add Files to Existing Archives:
‘<samp>--append</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX32"><code>append<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC41">3.4.1 Operations</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX403"><code>atime-preserve</code></a></td><td valign="top"><a
href="#SEC128">8.2 Handling File Attributes</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX46"><code>atime-preserve<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_1">B</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX242"><code>backup</code></a></td><td valign="top"><a
href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX47"><code>backup<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX170"><code>block-number</code></a></td><td valign="top"><a
href="#SEC46">3.7 Checking <code>tar</code> progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX48"><code>block-number<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX425"><code>blocking-factor</code></a></td><td valign="top"><a
href="#SEC149">9.4.2 The Blocking Factor of an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX49"><code>blocking-factor<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX393"><code>bzip2</code></a></td><td
valign="top"><a href="#SEC126">8.1.1 Creating and Reading Compressed
Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX50"><code>bzip2<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_2">C</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC57"><code>catenate</code></a></td><td valign="top"><a
href="#SEC57">4.2.4 Combining Archives with
‘<samp>--concatenate</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX33"><code>catenate<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC41">3.4.1 Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX52"><code>check-links<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX168"><code>checkpoint</code></a></td><td valign="top"><a
href="#SEC46">3.7 Checking <code>tar</code> progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX51"><code>checkpoint<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX191"><code>compare</code></a></td><td valign="top"><a
href="#SEC59">4.2.6 Comparing Archive Members with the File System</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX34"><code>compare<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC41">3.4.1 Operations</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX394"><code>compress</code></a></td><td valign="top"><a
href="#SEC126">8.1.1 Creating and Reading Compressed Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX53"><code>compress<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC57"><code>concatenate</code></a></td><td valign="top"><a
href="#SEC57">4.2.4 Combining Archives with
‘<samp>--concatenate</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX35"><code>concatenate<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC41">3.4.1 Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX55"><code>confirmation<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC60"><code>create<span
class="roman">, additional options</span></code></a></td><td valign="top"><a
href="#SEC60">4.3 Options Used by
‘<samp>--create</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX174"><code>create<span
class="roman">, complementary notes</span></code></a></td><td valign="top"><a
href="#SEC49">4.1 Basic <acronym>GNU</acronym> <code>tar</code>
Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC19"><code>create<span
class="roman">, introduced</span></code></a></td><td valign="top"><a
href="#SEC19">2.6.2 Creating the Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX36"><code>create<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC41">3.4.1 Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC20"><code>create<span
class="roman">, using with
‘<samp>--verbose</samp>’</span></code></a></td><td valign="top"><a
href="#SEC20">2.6.3 Running ‘<samp>--create</samp>’ with
‘<samp>--verbose</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX453"><code>create<span
class="roman">, using with
‘<samp>--verify</samp>’</span></code></a></td><td valign="top"><a
href="#SEC158">9.8 Verifying Data as It is Stored</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_3">D</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX216"><code>delay-directory-restore</code></a></td><td valign="top"><a
href="#SEC76">Directory Modification Times and Permissions</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX56"><code>delay-directory-restore<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX188"><code>delete</code></a></td><td valign="top"><a
href="#SEC58">4.2.5 Removing Archive Members Using
‘<samp>--delete</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX37"><code>delete<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC41">3.4.1 Operations</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC131"><code>dereference</code></a></td><td valign="top"><a
href="#SEC131">8.3.2 Symbolic Links</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX57"><code>dereference<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX38"><code>diff<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC41">3.4.1
Operations</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX347"><code>directory</code></a></td><td valign="top"><a
href="#SEC111">6.10.1 Changing the Working Directory</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX58"><code>directory<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX304"><code>directory<span
class="roman">, using in ‘<samp>--files-from</samp>’
argument</span></code></a></td><td valign="top"><a href="#SEC100">6.3 Reading
Names from a File</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_4">E</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX310"><code>exclude</code></a></td><td valign="top"><a
href="#SEC102">6.4 Excluding Some Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC103"><code>exclude<span
class="roman">, potential problems with</span></code></a></td><td
valign="top"><a href="#SEC103">Problems with Using the <code>exclude</code>
Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX59"><code>exclude<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX314"><code>exclude-caches</code></a></td><td valign="top"><a
href="#SEC102">6.4 Excluding Some Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX61"><code>exclude-caches<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX312"><code>exclude-from</code></a></td><td valign="top"><a
href="#SEC102">6.4 Excluding Some Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX60"><code>exclude-from<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX27"><code>extract</code></a></td><td valign="top"><a
href="#SEC25">2.8 How to Extract Members from an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX197"><code>extract<span
class="roman">, additional options</span></code></a></td><td valign="top"><a
href="#SEC63">4.4 Options Used by
‘<samp>--extract</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX175"><code>extract<span
class="roman">, complementary notes</span></code></a></td><td valign="top"><a
href="#SEC49">4.1 Basic <acronym>GNU</acronym> <code>tar</code>
Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX39"><code>extract<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC41">3.4.1 Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX258"><code>extract<span
class="roman">, using with
‘<samp>--listed-incremental</samp>’</span></code></a></td><td
valign="top"><a href="#SEC88">5.2 Using <code>tar</code> to Perform Incremental
Dumps</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_5">F</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX293"><code>file<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC98">6.1 Choosing and Naming Archive Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX62"><code>file<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX12"><code>file<span class="roman">,
tutorial</span></code></a></td><td valign="top"><a href="#SEC14">The
‘<samp>--file</samp>’ Option</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX303"><code>files-from</code></a></td><td valign="top"><a
href="#SEC100">6.3 Reading Names from a File</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX63"><code>files-from<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX417"><code>force-local<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC144">9.1 Device Selection and Switching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX64"><code>force-local<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX65"><code>format<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_6">G</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX40"><code>get<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC41">3.4.1
Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX195"><code>group</code></a></td><td
valign="top"><a href="#SEC61">4.3.1 Overriding File Metadata</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX66"><code>group<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX68"><code>gunzip<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX390"><code>gzip</code></a></td><td
valign="top"><a href="#SEC126">8.1.1 Creating and Reading Compressed
Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX67"><code>gzip<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_7">H</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX15"><code>help</code></a></td><td
valign="top"><a href="#SEC16">Getting Help: Using the
‘<samp>--help</samp>’ Option</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX161"><code>help<span
class="roman">, introduction</span></code></a></td><td valign="top"><a
href="#SEC44">3.5 <acronym>GNU</acronym> <code>tar</code>
documentation</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX70"><code>help<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_8">I</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX322"><code>ignore-case</code></a></td><td valign="top"><a
href="#SEC105">Controlling Pattern-Matching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX71"><code>ignore-case<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX232"><code>ignore-command-error</code></a></td><td valign="top"><a
href="#SEC78">Writing to an External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX72"><code>ignore-command-error<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX196"><code>ignore-failed-read</code></a></td><td valign="top"><a
href="#SEC62">4.3.2 Ignore Fail Read</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX73"><code>ignore-failed-read<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC66"><code>ignore-zeros</code></a></td><td valign="top"><a
href="#SEC66">Ignoring Blocks of Zeros</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX426"><code>ignore-zeros<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC149">9.4.2 The Blocking Factor of an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX74"><code>ignore-zeros<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX75"><code>incremental<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX259"><code>incremental<span
class="roman">, using with
‘<samp>--list</samp>’</span></code></a></td><td valign="top"><a
href="#SEC_Foot"></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX76"><code>index-file<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX440"><code>info-script</code></a></td><td valign="top"><a
href="#SEC154">9.6.1 Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX421"><code>info-script<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC144">9.1 Device Selection and Switching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX77"><code>info-script<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX173"><code>interactive</code></a></td><td valign="top"><a
href="#SEC47">3.8 Asking for Confirmation During Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX79"><code>interactive<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_9">K</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX210"><code>keep-newer-files</code></a></td><td valign="top"><a
href="#SEC71">Keep Newer Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX80"><code>keep-newer-files<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX209"><code>keep-old-files</code></a></td><td valign="top"><a
href="#SEC70">Keep Old Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX203"><code>keep-old-files<span
class="roman">, introduced</span></code></a></td><td valign="top"><a
href="#SEC68">Options Controlling the Overwriting of Existing
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX81"><code>keep-old-files<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_10">L</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX447"><code>label</code></a></td><td
valign="top"><a href="#SEC157">9.7 Including a Label in the
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX82"><code>label<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC23"><code>list</code></a></td><td
valign="top"><a href="#SEC23">2.7 How to List Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX41"><code>list<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC41">3.4.1
Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX261"><code>list<span
class="roman">, using with
‘<samp>--incremental</samp>’</span></code></a></td><td
valign="top"><a href="#SEC_Foot"></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX262"><code>list<span
class="roman">, using with
‘<samp>--listed-incremental</samp>’</span></code></a></td><td
valign="top"><a href="#SEC_Foot"></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX18"><code>list<span class="roman">,
using with ‘<samp>--verbose</samp>’</span></code></a></td><td
valign="top"><a href="#SEC23">2.7 How to List Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX23"><code>list<span class="roman">,
using with file name arguments</span></code></a></td><td valign="top"><a
href="#SEC23">2.7 How to List Archives</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX256"><code>listed-incremental</code></a></td><td valign="top"><a
href="#SEC88">5.2 Using <code>tar</code> to Perform Incremental
Dumps</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX83"><code>listed-incremental<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX257"><code>listed-incremental<span
class="roman">, using with
‘<samp>--extract</samp>’</span></code></a></td><td valign="top"><a
href="#SEC88">5.2 Using <code>tar</code> to Perform Incremental
Dumps</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX260"><code>listed-incremental<span
class="roman">, using with
‘<samp>--list</samp>’</span></code></a></td><td valign="top"><a
href="#SEC_Foot"></a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_11">M</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX192"><code>mode</code></a></td><td
valign="top"><a href="#SEC61">4.3.1 Overriding File Metadata</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX84"><code>mode<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX193"><code>mtime</code></a></td><td
valign="top"><a href="#SEC61">4.3.1 Overriding File Metadata</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX85"><code>mtime<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC154"><code>multi-volume</code></a></td><td valign="top"><a
href="#SEC154">9.6.1 Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX419"><code>multi-volume<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC144">9.1 Device Selection and Switching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX86"><code>multi-volume<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_12">N</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX441"><code>new-volume-script</code></a></td><td valign="top"><a
href="#SEC154">9.6.1 Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX422"><code>new-volume-script<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC144">9.1 Device Selection and Switching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX78"><code>new-volume-script<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX87"><code>new-volume-script<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX335"><code>newer</code></a></td><td
valign="top"><a href="#SEC108">6.8 Operating Only on New Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX89"><code>newer<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX336"><code>newer-mtime</code></a></td><td valign="top"><a
href="#SEC108">6.8 Operating Only on New Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX90"><code>newer-mtime<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX321"><code>no-anchored</code></a></td><td valign="top"><a
href="#SEC105">Controlling Pattern-Matching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX91"><code>no-anchored<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX217"><code>no-delay-directory-restore</code></a></td><td
valign="top"><a href="#SEC76">Directory Modification Times and
Permissions</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX92"><code>no-delay-directory-restore<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX323"><code>no-ignore-case</code></a></td><td valign="top"><a
href="#SEC105">Controlling Pattern-Matching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX93"><code>no-ignore-case<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX233"><code>no-ignore-command-error</code></a></td><td valign="top"><a
href="#SEC78">Writing to an External Program</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX94"><code>no-ignore-command-error<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX95"><code>no-overwrite-dir<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX96"><code>no-quote-chars<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX341"><code>no-recursion</code></a></td><td valign="top"><a
href="#SEC109">6.9 Descending into Directories</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX97"><code>no-recursion<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX406"><code>no-same-owner</code></a></td><td valign="top"><a
href="#SEC128">8.2 Handling File Attributes</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX98"><code>no-same-owner<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX99"><code>no-same-permissions<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX302"><code>no-unquote</code></a></td><td valign="top"><a
href="#SEC99">6.2 Selecting Archive Members</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX100"><code>no-unquote<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX319"><code>no-wildcards</code></a></td><td valign="top"><a
href="#SEC105">Controlling Pattern-Matching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX101"><code>no-wildcards<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX325"><code>no-wildcards-match-slash</code></a></td><td
valign="top"><a href="#SEC105">Controlling Pattern-Matching</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX102"><code>no-wildcards-match-slash<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX306"><code>null</code></a></td><td
valign="top"><a href="#SEC101">6.3.1 <code>NUL</code> Terminated File
Names</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX103"><code>null<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX407"><code>numeric-owner</code></a></td><td valign="top"><a
href="#SEC128">8.2 Handling File Attributes</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX104"><code>numeric-owner<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_13">O</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX105"><code>occurrence<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX106"><code>old-archive<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX343"><code>one-file-system</code></a></td><td valign="top"><a
href="#SEC110">6.10 Crossing File System Boundaries</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX107"><code>one-file-system<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX207"><code>overwrite</code></a></td><td valign="top"><a
href="#SEC69">Overwrite Old Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX204"><code>overwrite<span
class="roman">, introduced</span></code></a></td><td valign="top"><a
href="#SEC68">Options Controlling the Overwriting of Existing
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX108"><code>overwrite<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX208"><code>overwrite-dir</code></a></td><td valign="top"><a
href="#SEC69">Overwrite Old Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC68"><code>overwrite-dir<span
class="roman">, introduced</span></code></a></td><td valign="top"><a
href="#SEC68">Options Controlling the Overwriting of Existing
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX109"><code>overwrite-dir<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX194"><code>owner</code></a></td><td
valign="top"><a href="#SEC61">4.3.1 Overriding File Metadata</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX110"><code>owner<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_14">P</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX411"><code>pax-option</code></a></td><td valign="top"><a
href="#SEC136">8.3.6.1 Controlling Extended Header Keywords</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX114"><code>pax-option<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX115"><code>portability<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX116"><code>posix<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX410"><code>preserve</code></a></td><td valign="top"><a
href="#SEC128">8.2 Handling File Attributes</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX117"><code>preserve<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX241"><code>preserve-order</code></a></td><td valign="top"><a
href="#SEC82">Same Order</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX118"><code>preserve-order<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX214"><code>preserve-permissions</code></a></td><td valign="top"><a
href="#SEC75">Setting Access Permissions</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX409"><code>preserve-permissions<span class="roman">, short
description</span></code></a></td><td valign="top"><a href="#SEC128">8.2
Handling File Attributes</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX119"><code>preserve-permissions<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_15">Q</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX112"><code>quote-chars<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX326"><code>quoting-style</code></a></td><td valign="top"><a
href="#SEC106">6.6 Quoting Member Names</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX113"><code>quoting-style<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_16">R</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX200"><code>read-full-records</code></a></td><td valign="top"><a
href="#SEC64">4.4.1 Options to Help Read Archives</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX201"><code>read-full-records</code></a></td><td valign="top"><a
href="#SEC65">Reading Full Records</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX427"><code>read-full-records<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC149">9.4.2 The Blocking Factor of an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX121"><code>read-full-records<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX122"><code>record-size<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX342"><code>recursion</code></a></td><td valign="top"><a
href="#SEC109">6.9 Descending into Directories</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX123"><code>recursion<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX212"><code>recursive-unlink</code></a></td><td valign="top"><a
href="#SEC73">Recursive Unlink</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX124"><code>recursive-unlink<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX234"><code>remove-files</code></a></td><td valign="top"><a
href="#SEC79">Removing Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX125"><code>remove-files<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX126"><code>restrict<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX127"><code>rmt-command<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX418"><code>rsh-command</code></a></td><td valign="top"><a
href="#SEC144">9.1 Device Selection and Switching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX128"><code>rsh-command<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_17">S</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX240"><code>same-order</code></a></td><td valign="top"><a
href="#SEC82">Same Order</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX129"><code>same-order<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX405"><code>same-owner</code></a></td><td valign="top"><a
href="#SEC128">8.2 Handling File Attributes</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX130"><code>same-owner<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX215"><code>same-permissions</code></a></td><td valign="top"><a
href="#SEC75">Setting Access Permissions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX408"><code>same-permissions<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC128">8.2 Handling File Attributes</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX120"><code>same-permissions<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX131"><code>same-permissions<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX88"><code>seek<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC45"><code>show-defaults</code></a></td><td valign="top"><a
href="#SEC45">3.6 Obtaining <acronym>GNU</acronym> <code>tar</code> default
values</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX132"><code>show-defaults<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX169"><code>show-omitted-dirs</code></a></td><td valign="top"><a
href="#SEC46">3.7 Checking <code>tar</code> progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX133"><code>show-omitted-dirs<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX21"><code>show-stored-names</code></a></td><td valign="top"><a
href="#SEC23">2.7 How to List Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX135"><code>show-stored-names<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX328"><code>show-transformed-names</code></a></td><td valign="top"><a
href="#SEC107">6.7 Modifying File and Member Names</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX134"><code>show-transformed-names<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX400"><code>sparse</code></a></td><td valign="top"><a
href="#SEC127">8.1.2 Archiving Sparse Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX136"><code>sparse<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX402"><code>sparse-version</code></a></td><td valign="top"><a
href="#SEC127">8.1.2 Archiving Sparse Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX137"><code>sparse-version<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX237"><code>starting-file</code></a></td><td valign="top"><a
href="#SEC81">Starting File</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX138"><code>starting-file<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX327"><code>strip-components</code></a></td><td valign="top"><a
href="#SEC107">6.7 Modifying File and Member Names</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX139"><code>strip-components<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX249"><code>suffix</code></a></td><td valign="top"><a
href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX140"><code>suffix<span
class="roman">, summary</span>, summary</code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_18">T</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX434"><code>tape-length</code></a></td><td valign="top"><a
href="#SEC154">9.6.1 Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX420"><code>tape-length<span
class="roman">, short description</span></code></a></td><td valign="top"><a
href="#SEC144">9.1 Device Selection and Switching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX141"><code>tape-length<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX450"><code>test-label</code></a></td><td valign="top"><a
href="#SEC157">9.7 Including a Label in the Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX142"><code>test-label<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX219"><code>to-command</code></a></td><td valign="top"><a
href="#SEC78">Writing to an External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX143"><code>to-command<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX218"><code>to-stdout</code></a></td><td valign="top"><a
href="#SEC77">Writing to Standard Output</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX144"><code>to-stdout<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX166"><code>totals</code></a></td><td valign="top"><a
href="#SEC46">3.7 Checking <code>tar</code> progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX145"><code>totals<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX213"><code>touch</code></a></td><td
valign="top"><a href="#SEC74">Setting Data Modification Times</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX404"><code>touch</code></a></td><td
valign="top"><a href="#SEC128">8.2 Handling File Attributes</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX146"><code>touch<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX329"><code>transform</code></a></td><td valign="top"><a
href="#SEC107">6.7 Modifying File and Member Names</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX111"><code>transform<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_19">U</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX395"><code>uncompress</code></a></td><td valign="top"><a
href="#SEC126">8.1.1 Creating and Reading Compressed Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX54"><code>uncompress<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX147"><code>uncompress<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX391"><code>ungzip</code></a></td><td valign="top"><a
href="#SEC126">8.1.1 Creating and Reading Compressed Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX69"><code>ungzip<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX148"><code>ungzip<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX211"><code>unlink-first</code></a></td><td valign="top"><a
href="#SEC72">Unlink First</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX206"><code>unlink-first<span
class="roman">, introduced</span></code></a></td><td valign="top"><a
href="#SEC68">Options Controlling the Overwriting of Existing
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX149"><code>unlink-first<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX301"><code>unquote</code></a></td><td valign="top"><a
href="#SEC99">6.2 Selecting Archive Members</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX150"><code>unquote<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX183"><code>update</code></a></td><td valign="top"><a
href="#SEC55">4.2.3 Updating an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX42"><code>update<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC41">3.4.1 Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX162"><code>usage</code></a></td><td
valign="top"><a href="#SEC44">3.5 <acronym>GNU</acronym> <code>tar</code>
documentation</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX396"><code>use-compress-program</code></a></td><td valign="top"><a
href="#SEC126">8.1.1 Creating and Reading Compressed Archives</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX151"><code>use-compress-program<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX152"><code>utc<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_20">V</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX164"><code>verbose</code></a></td><td valign="top"><a
href="#SEC46">3.7 Checking <code>tar</code> progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX14"><code>verbose<span
class="roman">, introduced</span></code></a></td><td valign="top"><a
href="#SEC15">The ‘<samp>--verbose</samp>’ Option</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX153"><code>verbose<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC20"><code>verbose<span
class="roman">, using with
‘<samp>--create</samp>’</span></code></a></td><td valign="top"><a
href="#SEC20">2.6.3 Running ‘<samp>--create</samp>’ with
‘<samp>--verbose</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX19"><code>verbose<span
class="roman">, using with
‘<samp>--list</samp>’</span></code></a></td><td valign="top"><a
href="#SEC23">2.7 How to List Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX451"><code>verify, short
description</code></a></td><td valign="top"><a href="#SEC158">9.8 Verifying
Data as It is Stored</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX154"><code>verify<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX452"><code>verify<span
class="roman">, using with
‘<samp>--create</samp>’</span></code></a></td><td valign="top"><a
href="#SEC158">9.8 Verifying Data as It is Stored</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC44"><code>version</code></a></td><td valign="top"><a
href="#SEC44">3.5 <acronym>GNU</acronym> <code>tar</code>
documentation</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX155"><code>version<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX437"><code>volno-file</code></a></td><td valign="top"><a
href="#SEC154">9.6.1 Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX156"><code>volno-file<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC179_21">W</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX318"><code>wildcards</code></a></td><td valign="top"><a
href="#SEC105">Controlling Pattern-Matching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX157"><code>wildcards<span
class="roman">, summary</span></code></a></td><td valign="top"><a
href="#SEC42">3.4.2 <code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX324"><code>wildcards-match-slash</code></a></td><td valign="top"><a
href="#SEC105">Controlling Pattern-Matching</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX158"><code>wildcards-match-slash<span class="roman">,
summary</span></code></a></td><td valign="top"><a href="#SEC42">3.4.2
<code>tar</code> Options</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+</table>
+<table><tr><th valign="top">Jump to: </th><td><a href="#SEC179_0"
class="summary-letter"><b>A</b></a>
+
+<a href="#SEC179_1" class="summary-letter"><b>B</b></a>
+
+<a href="#SEC179_2" class="summary-letter"><b>C</b></a>
+
+<a href="#SEC179_3" class="summary-letter"><b>D</b></a>
+
+<a href="#SEC179_4" class="summary-letter"><b>E</b></a>
+
+<a href="#SEC179_5" class="summary-letter"><b>F</b></a>
+
+<a href="#SEC179_6" class="summary-letter"><b>G</b></a>
+
+<a href="#SEC179_7" class="summary-letter"><b>H</b></a>
+
+<a href="#SEC179_8" class="summary-letter"><b>I</b></a>
+
+<a href="#SEC179_9" class="summary-letter"><b>K</b></a>
+
+<a href="#SEC179_10" class="summary-letter"><b>L</b></a>
+
+<a href="#SEC179_11" class="summary-letter"><b>M</b></a>
+
+<a href="#SEC179_12" class="summary-letter"><b>N</b></a>
+
+<a href="#SEC179_13" class="summary-letter"><b>O</b></a>
+
+<a href="#SEC179_14" class="summary-letter"><b>P</b></a>
+
+<a href="#SEC179_15" class="summary-letter"><b>Q</b></a>
+
+<a href="#SEC179_16" class="summary-letter"><b>R</b></a>
+
+<a href="#SEC179_17" class="summary-letter"><b>S</b></a>
+
+<a href="#SEC179_18" class="summary-letter"><b>T</b></a>
+
+<a href="#SEC179_19" class="summary-letter"><b>U</b></a>
+
+<a href="#SEC179_20" class="summary-letter"><b>V</b></a>
+
+<a href="#SEC179_21" class="summary-letter"><b>W</b></a>
+
+</td></tr></table>
+
+<hr size="6">
+<a name="Index"></a>
+<a name="SEC180"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC179" title="Previous
section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[ > ]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC179" title="Beginning of this
chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Up section"> Up
</a>]</td>
+<td valign="middle" align="left">[ >> ]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1 class="appendix"> H. Index </h1>
+
+<table><tr><th valign="top">Jump to: </th><td><a href="#SEC180_0"
class="summary-letter"><b>A</b></a>
+
+<a href="#SEC180_1" class="summary-letter"><b>B</b></a>
+
+<a href="#SEC180_2" class="summary-letter"><b>C</b></a>
+
+<a href="#SEC180_3" class="summary-letter"><b>D</b></a>
+
+<a href="#SEC180_4" class="summary-letter"><b>E</b></a>
+
+<a href="#SEC180_5" class="summary-letter"><b>F</b></a>
+
+<a href="#SEC180_6" class="summary-letter"><b>G</b></a>
+
+<a href="#SEC180_7" class="summary-letter"><b>H</b></a>
+
+<a href="#SEC180_8" class="summary-letter"><b>I</b></a>
+
+<a href="#SEC180_9" class="summary-letter"><b>L</b></a>
+
+<a href="#SEC180_10" class="summary-letter"><b>M</b></a>
+
+<a href="#SEC180_11" class="summary-letter"><b>N</b></a>
+
+<a href="#SEC180_12" class="summary-letter"><b>O</b></a>
+
+<a href="#SEC180_13" class="summary-letter"><b>P</b></a>
+
+<a href="#SEC180_14" class="summary-letter"><b>R</b></a>
+
+<a href="#SEC180_15" class="summary-letter"><b>S</b></a>
+
+<a href="#SEC180_16" class="summary-letter"><b>T</b></a>
+
+<a href="#SEC180_17" class="summary-letter"><b>U</b></a>
+
+<a href="#SEC180_18" class="summary-letter"><b>V</b></a>
+
+<a href="#SEC180_19" class="summary-letter"><b>W</b></a>
+
+<a href="#SEC180_20" class="summary-letter"><b>X</b></a>
+
+<a href="#SEC180_21" class="summary-letter"><b>Y</b></a>
+
+</td></tr></table>
+<table border="0" class="index-cp">
+<tr><td></td><th align="left">Index Entry</th><th align="left">
Section</th></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_0">A</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX363">abbreviations for
months</a></td><td valign="top"><a href="#SEC115">7.2 Calendar date
items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX423">absolute file
names</a></td><td valign="top"><a href="#SEC145">9.2 The Remote Tape
Server</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC57">Adding archives to an
archive</a></td><td valign="top"><a href="#SEC57">4.2.4 Combining Archives with
‘<samp>--concatenate</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX179">Adding files to an
Archive</a></td><td valign="top"><a href="#SEC53">4.2.2.1 Appending Files to an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX263"><code>ADMINISTRATOR</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX333">Age, excluding files
by</a></td><td valign="top"><a href="#SEC108">6.8 Operating Only on New
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX379"><code>ago <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX364"><code>am <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC116">7.3 Time of day items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX180">Appending files to an
Archive</a></td><td valign="top"><a href="#SEC53">4.2.2.1 Appending Files to an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC3">archive</a></td><td
valign="top"><a href="#SEC3">1.2 Some Definitions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX295">Archive creation</a></td><td
valign="top"><a href="#SEC98">6.1 Choosing and Naming Archive
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX4">archive member</a></td><td
valign="top"><a href="#SEC3">1.2 Some Definitions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX290">Archive Name</a></td><td
valign="top"><a href="#SEC98">6.1 Choosing and Naming Archive
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX17">Archive, creation
of</a></td><td valign="top"><a href="#SEC17">2.6 How to Create
Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX181">Archives, Appending files
to</a></td><td valign="top"><a href="#SEC53">4.2.2.1 Appending Files to an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC22">Archiving
Directories</a></td><td valign="top"><a href="#SEC22">2.6.5 Archiving
Directories</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX2">archiving files</a></td><td
valign="top"><a href="#SEC_Top"><acronym>GNU</acronym> tar: an archiver
tool</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX454"><code>ARGP_HELP_FMT,
environment variable</code></a></td><td valign="top"><a href="#SEC161">B.
Configuring Help Summary</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC123">authors of
<code>get_date</code></a></td><td valign="top"><a href="#SEC123">7.10 Authors
of <code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX337">Avoiding recursion in
directories</a></td><td valign="top"><a href="#SEC109">6.9 Descending into
Directories</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_1">B</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC83">backup options</a></td><td
valign="top"><a href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX250">backup suffix</a></td><td
valign="top"><a href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX267"><code>BACKUP_DIRS</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX269"><code>BACKUP_FILES</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX264"><code>BACKUP_HOUR</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX244">backups</a></td><td
valign="top"><a href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX386">beginning of time, for
<acronym>POSIX</acronym></a></td><td valign="top"><a href="#SEC121">7.8 Seconds
since the Epoch</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC123">Bellovin, Steven
M.</a></td><td valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC123">Berets, Jim</a></td><td
valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX389">Berry, K.</a></td><td
valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX171">Block number where error
occurred</a></td><td valign="top"><a href="#SEC46">3.7 Checking
<code>tar</code> progress</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX266"><code>BLOCKING</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC149">Blocking Factor</a></td><td
valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX428">blocking factor</a></td><td
valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC149">Blocks per record</a></td><td
valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC7">bug reports</a></td><td
valign="top"><a href="#SEC7">1.6 Reporting bugs or suggestions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC149">Bytes per record</a></td><td
valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_2">C</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC115">calendar date item</a></td><td
valign="top"><a href="#SEC115">7.2 Calendar date items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX358">case, ignored in
dates</a></td><td valign="top"><a href="#SEC114">7.1 General date
syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX185"><code>cat</code> vs
<code>concatenate</code></a></td><td valign="top"><a href="#SEC57">4.2.4
Combining Archives with ‘<samp>--concatenate</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX344">Changing directory
mid-stream</a></td><td valign="top"><a href="#SEC111">6.10.1 Changing the
Working Directory</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX317">Character class, excluding
characters from</a></td><td valign="top"><a href="#SEC104">6.5 Wildcards
Patterns and Matching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX291">Choosing an archive
file</a></td><td valign="top"><a href="#SEC98">6.1 Choosing and Naming Archive
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX359">comments, in dates</a></td><td
valign="top"><a href="#SEC114">7.1 General date syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC126">Compressed
archives</a></td><td valign="top"><a href="#SEC126">8.1.1 Creating and Reading
Compressed Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX184"><code>concatenate</code> vs
<code>cat</code></a></td><td valign="top"><a href="#SEC57">4.2.4 Combining
Archives with ‘<samp>--concatenate</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC57">Concatenating
Archives</a></td><td valign="top"><a href="#SEC57">4.2.4 Combining Archives
with ‘<samp>--concatenate</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX255">corrupted archives</a></td><td
valign="top"><a href="#SEC87">5.1 Using <code>tar</code> to Perform Full
Dumps</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX392">corrupted archives</a></td><td
valign="top"><a href="#SEC126">8.1.1 Creating and Reading Compressed
Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX16">Creation of the
archive</a></td><td valign="top"><a href="#SEC17">2.6 How to Create
Archives</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_3">D</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX431">DAT blocking</a></td><td
valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX331">Data Modification time,
excluding files by</a></td><td valign="top"><a href="#SEC108">6.8 Operating
Only on New Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC74">Data modification times of
extracted files</a></td><td valign="top"><a href="#SEC74">Setting Data
Modification Times</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX361">date format,
<small>ISO</small> 8601</a></td><td valign="top"><a href="#SEC115">7.2 Calendar
date items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC113">date input formats</a></td><td
valign="top"><a href="#SEC113">7. Date input formats</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX376"><code>day <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX380"><code>day <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC118">day of week item</a></td><td
valign="top"><a href="#SEC118">7.5 Day of week items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX186">Deleting files from an
archive</a></td><td valign="top"><a href="#SEC58">4.2.5 Removing Archive
Members Using ‘<samp>--delete</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX190">Deleting from tape
archives</a></td><td valign="top"><a href="#SEC58">4.2.5 Removing Archive
Members Using ‘<samp>--delete</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX338">Descending directories,
avoiding</a></td><td valign="top"><a href="#SEC109">6.9 Descending into
Directories</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC22">Directories,
Archiving</a></td><td valign="top"><a href="#SEC22">2.6.5 Archiving
Directories</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX339">Directories, avoiding
recursion</a></td><td valign="top"><a href="#SEC109">6.9 Descending into
Directories</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX345">Directory, changing
mid-stream</a></td><td valign="top"><a href="#SEC111">6.10.1 Changing the
Working Directory</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX268"><code>DIRLIST</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC119">displacement of
dates</a></td><td valign="top"><a href="#SEC119">7.6 Relative items in date
strings</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX459"><code>doc-opt-col</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC158">Double-checking a write
operation</a></td><td valign="top"><a href="#SEC158">9.8 Verifying Data as It
is Stored</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX285"><code>DUMP_BEGIN</code></a></td><td valign="top"><a
href="#SEC93">5.4.3 User Hooks</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX286"><code>DUMP_END</code></a></td><td valign="top"><a
href="#SEC93">5.4.3 User Hooks</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX277"><code>DUMP_REMIND_SCRIPT</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX254">dumps, full</a></td><td
valign="top"><a href="#SEC87">5.1 Using <code>tar</code> to Perform Full
Dumps</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX455"><code>dup-args</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX456"><code>dup-args-note</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_4">E</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC123">Eggert, Paul</a></td><td
valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC66">End-of-archive blocks,
ignoring</a></td><td valign="top"><a href="#SEC66">Ignoring Blocks of
Zeros</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX438">End-of-archive info
script</a></td><td valign="top"><a href="#SEC154">9.6.1 Archives Longer than
One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX10">entry</a></td><td
valign="top"><a href="#SEC5">1.4 How <code>tar</code> Archives are
Named</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX387">epoch, for
<acronym>POSIX</acronym></a></td><td valign="top"><a href="#SEC121">7.8 Seconds
since the Epoch</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX172">Error message, block number
of</a></td><td valign="top"><a href="#SEC46">3.7 Checking <code>tar</code>
progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX430">Exabyte blocking</a></td><td
valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX311"><code>exclude</code></a></td><td valign="top"><a
href="#SEC102">6.4 Excluding Some Files</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX315"><code>exclude-caches</code></a></td><td valign="top"><a
href="#SEC102">6.4 Excluding Some Files</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX313"><code>exclude-from</code></a></td><td valign="top"><a
href="#SEC102">6.4 Excluding Some Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX316">Excluding characters from a
character class</a></td><td valign="top"><a href="#SEC104">6.5 Wildcards
Patterns and Matching</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX330">Excluding file by
age</a></td><td valign="top"><a href="#SEC108">6.8 Operating Only on New
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX309">Excluding files by file
system</a></td><td valign="top"><a href="#SEC102">6.4 Excluding Some
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX308">Excluding files by name and
pattern</a></td><td valign="top"><a href="#SEC102">6.4 Excluding Some
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC174">Exec Mode,
<code>genfile</code></a></td><td valign="top"><a href="#SEC174">D.3 Exec
Mode</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX247">existing <span
class="roman">backup method</span></a></td><td valign="top"><a
href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX28">exit status</a></td><td
valign="top"><a href="#SEC33">3.1 General Synopsis of
<code>tar</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX24">Extraction</a></td><td
valign="top"><a href="#SEC25">2.8 How to Extract Members from an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX7">extraction</a></td><td
valign="top"><a href="#SEC3">1.2 Some Definitions</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_5">F</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC177">FDL, GNU Free Documentation
License</a></td><td valign="top"><a href="#SEC177">F.1 GNU Free Documentation
License</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX1">file archival</a></td><td
valign="top"><a href="#SEC_Top"><acronym>GNU</acronym> tar: an archiver
tool</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX476">File lists separated by NUL
characters</a></td><td valign="top"><a href="#SEC172">D.1 Generate
Mode</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX5">file name</a></td><td
valign="top"><a href="#SEC3">1.2 Some Definitions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC100">File Name arguments,
alternatives</a></td><td valign="top"><a href="#SEC100">6.3 Reading Names from
a File</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX22">File name arguments, using
‘<samp>--list</samp>’ with</a></td><td valign="top"><a
href="#SEC23">2.7 How to List Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX307">File names, excluding files
by</a></td><td valign="top"><a href="#SEC102">6.4 Excluding Some
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC101">File names, terminated by
<code>NUL</code></a></td><td valign="top"><a href="#SEC101">6.3.1
<code>NUL</code> Terminated File Names</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC131">File names, using symbolic
links</a></td><td valign="top"><a href="#SEC131">8.3.2 Symbolic
Links</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC110">File system boundaries, not
crossing</a></td><td valign="top"><a href="#SEC110">6.10 Crossing File System
Boundaries</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX270"><code>FILELIST</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX351"><code>first <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC114">7.1 General date syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC148">Format Options</a></td><td
valign="top"><a href="#SEC148">9.4.1 Format Variations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC148">Format Parameters</a></td><td
valign="top"><a href="#SEC148">9.4.1 Format Variations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC132">Format, old style</a></td><td
valign="top"><a href="#SEC132">8.3.3 Old V7 Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX374"><code>fortnight <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC175">free documentation</a></td><td
valign="top"><a href="#SEC175">E. Free Software Needs Free
Documentation</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX253">full dumps</a></td><td
valign="top"><a href="#SEC87">5.1 Using <code>tar</code> to Perform Full
Dumps</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC138">future time stamps</a></td><td
valign="top"><a href="#SEC138">8.3.8 Large or Negative Values</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_6">G</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC114">general date
syntax</a></td><td valign="top"><a href="#SEC114">7.1 General date
syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC172">Generate Mode,
<code>genfile</code></a></td><td valign="top"><a href="#SEC172">D.1 Generate
Mode</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC171">genfile</a></td><td
valign="top"><a href="#SEC171">D. Genfile</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC172"><code>genfile</code>, create
file</a></td><td valign="top"><a href="#SEC172">D.1 Generate Mode</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX479"><code>genfile</code>, creating
sparse files</a></td><td valign="top"><a href="#SEC172">D.1 Generate
Mode</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC172"><code>genfile</code>, generate
mode</a></td><td valign="top"><a href="#SEC172">D.1 Generate Mode</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX475"><code>genfile</code>, reading
a list of file names</a></td><td valign="top"><a href="#SEC172">D.1 Generate
Mode</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC113"><code>get_date</code></a></td><td valign="top"><a
href="#SEC113">7. Date input formats</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC44">Getting program version
number</a></td><td valign="top"><a href="#SEC44">3.5 <acronym>GNU</acronym>
<code>tar</code> documentation</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC134">GNU archive format</a></td><td
valign="top"><a href="#SEC134">8.3.5 <acronym>GNU</acronym> and old
<acronym>GNU</acronym> <code>tar</code> format</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX471"><code>GNU.sparse.major,
extended header variable</code></a></td><td valign="top"><a
href="#SEC168">C.0.3 PAX Format, Version 1.0</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX469"><code>GNU.sparse.map, extended
header variable</code></a></td><td valign="top"><a href="#SEC167">C.0.2 PAX
Format, Versions 0.0 and 0.1</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX472"><code>GNU.sparse.minor,
extended header variable</code></a></td><td valign="top"><a
href="#SEC168">C.0.3 PAX Format, Version 1.0</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX470"><code>GNU.sparse.name,
extended header variable</code></a></td><td valign="top"><a
href="#SEC167">C.0.2 PAX Format, Versions 0.0 and 0.1</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX473"><code>GNU.sparse.name,
extended header variable, in v.1.0</code></a></td><td valign="top"><a
href="#SEC168">C.0.3 PAX Format, Version 1.0</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX465"><code>GNU.sparse.numblocks,
extended header variable</code></a></td><td valign="top"><a
href="#SEC167">C.0.2 PAX Format, Versions 0.0 and 0.1</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX467"><code>GNU.sparse.numbytes,
extended header variable</code></a></td><td valign="top"><a
href="#SEC167">C.0.2 PAX Format, Versions 0.0 and 0.1</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX466"><code>GNU.sparse.offset,
extended header variable</code></a></td><td valign="top"><a
href="#SEC167">C.0.2 PAX Format, Versions 0.0 and 0.1</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX474"><code>GNU.sparse.realsize,
extended header variable</code></a></td><td valign="top"><a
href="#SEC168">C.0.3 PAX Format, Version 1.0</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX464"><code>GNU.sparse.size,
extended header variable</code></a></td><td valign="top"><a
href="#SEC167">C.0.2 PAX Format, Versions 0.0 and 0.1</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX398">gnupg, using with
tar</a></td><td valign="top"><a href="#SEC126">8.1.1 Creating and Reading
Compressed Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX397">gpg, using with
tar</a></td><td valign="top"><a href="#SEC126">8.1.1 Creating and Reading
Compressed Archives</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_7">H</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX461"><code>header-col</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX284"><code>hook</code></a></td><td
valign="top"><a href="#SEC93">5.4.3 User Hooks</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX377"><code>hour <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_8">I</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC66">Ignoring end-of-archive
blocks</a></td><td valign="top"><a href="#SEC66">Ignoring Blocks of
Zeros</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX439">Info script</a></td><td
valign="top"><a href="#SEC154">9.6.1 Archives Longer than One Tape or
Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC47">Interactive
operation</a></td><td valign="top"><a href="#SEC47">3.8 Asking for Confirmation
During Operations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX360"><small>ISO</small> 8601 date
format</a></td><td valign="top"><a href="#SEC115">7.2 Calendar date
items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC114">items in date
strings</a></td><td valign="top"><a href="#SEC114">7.1 General date
syntax</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_9">L</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC157">Labeling an
archive</a></td><td valign="top"><a href="#SEC157">9.7 Including a Label in the
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC157">Labeling multi-volume
archives</a></td><td valign="top"><a href="#SEC157">9.7 Including a Label in
the Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC157">Labels on the archive
media</a></td><td valign="top"><a href="#SEC157">9.7 Including a Label in the
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX355">language, in dates</a></td><td
valign="top"><a href="#SEC114">7.1 General date syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX356">language, in dates</a></td><td
valign="top"><a href="#SEC114">7.1 General date syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX239">Large lists of file names on
small machines</a></td><td valign="top"><a href="#SEC82">Same
Order</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC138">large values</a></td><td
valign="top"><a href="#SEC138">8.3.8 Large or Negative Values</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX371"><code>last
<var>day</var></code></a></td><td valign="top"><a href="#SEC118">7.5 Day of
week items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX353"><code>last <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC114">7.1 General date syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX160">Listing all <code>tar</code>
options</a></td><td valign="top"><a href="#SEC44">3.5 <acronym>GNU</acronym>
<code>tar</code> documentation</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX20">listing member and file
names</a></td><td valign="top"><a href="#SEC23">2.7 How to List
Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX449">Listing volume
label</a></td><td valign="top"><a href="#SEC157">9.7 Including a Label in the
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC100">Lists of file
names</a></td><td valign="top"><a href="#SEC100">6.3 Reading Names from a
File</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX300">Local and remote
archives</a></td><td valign="top"><a href="#SEC98">6.1 Choosing and Naming
Archive Files</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX458"><code>long-opt-col</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_10">M</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC123">MacKenzie, David</a></td><td
valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX3">member</a></td><td
valign="top"><a href="#SEC3">1.2 Some Definitions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX6">member name</a></td><td
valign="top"><a href="#SEC3">1.2 Some Definitions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX177">Members, replacing with other
members</a></td><td valign="top"><a href="#SEC52">4.2.2 How to Add Files to
Existing Archives: ‘<samp>--append</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC123">Meyering, Jim</a></td><td
valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX238">Middle of the archive,
starting in the</a></td><td valign="top"><a href="#SEC81">Starting
File</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX366"><code>midnight <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC116">7.3 Time of day items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX378"><code>minute <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX369">minutes, time zone correction
by</a></td><td valign="top"><a href="#SEC116">7.3 Time of day
items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC75">Modes of extracted
files</a></td><td valign="top"><a href="#SEC75">Setting Access
Permissions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX332">Modification time, excluding
files by</a></td><td valign="top"><a href="#SEC108">6.8 Operating Only on New
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC74">Modification times of extracted
files</a></td><td valign="top"><a href="#SEC74">Setting Data Modification
Times</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX373"><code>month <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX362">month names in date
strings</a></td><td valign="top"><a href="#SEC115">7.2 Calendar date
items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX354">months,
written-out</a></td><td valign="top"><a href="#SEC114">7.1 General date
syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX271"><code>MT</code></a></td><td
valign="top"><a href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX280"><code>MT_BEGIN</code></a></td><td valign="top"><a
href="#SEC92">5.4.2 Magnetic Tape Control</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX282"><code>MT_OFFLINE</code></a></td><td valign="top"><a
href="#SEC92">5.4.2 Magnetic Tape Control</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX281"><code>MT_REWIND</code></a></td><td valign="top"><a
href="#SEC92">5.4.2 Magnetic Tape Control</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX283"><code>MT_STATUS</code></a></td><td valign="top"><a
href="#SEC92">5.4.2 Magnetic Tape Control</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC154">Multi-volume
archives</a></td><td valign="top"><a href="#SEC154">9.6.1 Archives Longer than
One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX412">Mutli-volume archives in PAX
format, extracting using non-GNU tars</a></td><td valign="top"><a
href="#SEC140">8.3.9.1 Extracting Members Split Between Volumes</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC140">Mutli-volume archives,
extracting using non-GNU tars</a></td><td valign="top"><a
href="#SEC140">8.3.9.1 Extracting Members Split Between Volumes</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_11">N</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX289">Naming an archive</a></td><td
valign="top"><a href="#SEC98">6.1 Choosing and Naming Archive
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC138">negative time
stamps</a></td><td valign="top"><a href="#SEC138">8.3.8 Large or Negative
Values</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX370"><code>next
<var>day</var></code></a></td><td valign="top"><a href="#SEC118">7.5 Day of
week items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX352"><code>next <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC114">7.1 General date syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX367"><code>noon <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC116">7.3 Time of day items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX383"><code>now <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC150"><code>ntape <span
class="roman">device</span></code></a></td><td valign="top"><a
href="#SEC150">9.5 Many Archives on One Tape</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC101"><code>NUL</code> terminated
file names</a></td><td valign="top"><a href="#SEC101">6.3.1 <code>NUL</code>
Terminated File Names</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC149">Number of blocks per
record</a></td><td valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of
an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC149">Number of bytes per
record</a></td><td valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of
an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX246">numbered <span
class="roman">backup method</span></a></td><td valign="top"><a
href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX349">numbers,
written-out</a></td><td valign="top"><a href="#SEC114">7.1 General date
syntax</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_12">O</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX159">Obtaining help</a></td><td
valign="top"><a href="#SEC44">3.5 <acronym>GNU</acronym> <code>tar</code>
documentation</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX165">Obtaining total status
information</a></td><td valign="top"><a href="#SEC46">3.7 Checking
<code>tar</code> progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC134">Old GNU archive
format</a></td><td valign="top"><a href="#SEC134">8.3.5 <acronym>GNU</acronym>
and old <acronym>GNU</acronym> <code>tar</code> format</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC166">Old GNU sparse
format</a></td><td valign="top"><a href="#SEC166">C.0.1 Old GNU
Format</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC132">Old style archives</a></td><td
valign="top"><a href="#SEC132">8.3.3 Old V7 Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC132">Old style format</a></td><td
valign="top"><a href="#SEC132">8.3.3 Old V7 Archives</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX460"><code>opt-doc-col</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX31">option syntax,
traditional</a></td><td valign="top"><a href="#SEC38">3.3.3 Old Option
Style</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC64">Options when reading
archives</a></td><td valign="top"><a href="#SEC64">4.4.1 Options to Help Read
Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC148">Options, archive format
specifying</a></td><td valign="top"><a href="#SEC148">9.4.1 Format
Variations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC148">Options, format
specifying</a></td><td valign="top"><a href="#SEC148">9.4.1 Format
Variations</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX350">ordinal numbers</a></td><td
valign="top"><a href="#SEC114">7.1 General date syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX202">Overwriting old files,
prevention</a></td><td valign="top"><a href="#SEC68">Options Controlling the
Overwriting of Existing Files</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_13">P</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX477">pattern,
<code>genfile</code></a></td><td valign="top"><a href="#SEC172">D.1 Generate
Mode</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC135">PAX archive format</a></td><td
valign="top"><a href="#SEC135">8.3.6 <acronym>GNU</acronym> <code>tar</code>
and <acronym>POSIX</acronym> <code>tar</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC75">Permissions of extracted
files</a></td><td valign="top"><a href="#SEC75">Setting Access
Permissions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX388">Pinard, F.</a></td><td
valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX365"><code>pm <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC116">7.3 Time of day items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC135">POSIX archive
format</a></td><td valign="top"><a href="#SEC135">8.3.6 <acronym>GNU</acronym>
<code>tar</code> and <acronym>POSIX</acronym> <code>tar</code></a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX167">Progress
information</a></td><td valign="top"><a href="#SEC46">3.7 Checking
<code>tar</code> progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX205">Protecting old
files</a></td><td valign="top"><a href="#SEC68">Options Controlling the
Overwriting of Existing Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC120">pure numbers in date
strings</a></td><td valign="top"><a href="#SEC120">7.7 Pure numbers in date
strings</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_14">R</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC100">Reading file names from a
file</a></td><td valign="top"><a href="#SEC100">6.3 Reading Names from a
File</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX198">Reading incomplete
records</a></td><td valign="top"><a href="#SEC64">4.4.1 Options to Help Read
Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC149">Record Size</a></td><td
valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX199">Records,
incomplete</a></td><td valign="top"><a href="#SEC64">4.4.1 Options to Help Read
Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX340">Recursion in directories,
avoiding</a></td><td valign="top"><a href="#SEC109">6.9 Descending into
Directories</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC119">relative items in date
strings</a></td><td valign="top"><a href="#SEC119">7.6 Relative items in date
strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX298">Remote devices</a></td><td
valign="top"><a href="#SEC98">6.1 Choosing and Naming Archive
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC145">remote tape drive</a></td><td
valign="top"><a href="#SEC145">9.2 The Remote Tape Server</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX187">Removing files from an
archive</a></td><td valign="top"><a href="#SEC58">4.2.5 Removing Archive
Members Using ‘<samp>--delete</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX178">Replacing members with other
members</a></td><td valign="top"><a href="#SEC52">4.2.2 How to Add Files to
Existing Archives: ‘<samp>--append</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC7">reporting bugs</a></td><td
valign="top"><a href="#SEC7">1.6 Reporting bugs or suggestions</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX287"><code>RESTORE_BEGIN</code></a></td><td valign="top"><a
href="#SEC93">5.4.3 User Hooks</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX288"><code>RESTORE_END</code></a></td><td valign="top"><a
href="#SEC93">5.4.3 User Hooks</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX26">Resurrecting files from an
archive</a></td><td valign="top"><a href="#SEC25">2.8 How to Extract Members
from an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX25">Retrieving files from an
archive</a></td><td valign="top"><a href="#SEC25">2.8 How to Extract Members
from an Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX29">return status</a></td><td
valign="top"><a href="#SEC33">3.1 General Synopsis of
<code>tar</code></a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX463"><code>rmargin</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC145"><code>rmt</code></a></td><td
valign="top"><a href="#SEC145">9.2 The Remote Tape Server</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX272"><code>RSH</code></a></td><td
valign="top"><a href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX273"><code>RSH_COMMAND</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX236">Running out of
space</a></td><td valign="top"><a href="#SEC80">4.4.3 Coping with Scarce
Resources</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_15">S</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC123">Salz, Rich</a></td><td
valign="top"><a href="#SEC123">7.10 Authors of
<code>get_date</code></a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX457"><code>short-opt-col</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX248">simple <span
class="roman">backup method</span></a></td><td valign="top"><a
href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX251"><code>SIMPLE_BACKUP_SUFFIX</code></a></td><td valign="top"><a
href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX278"><code>SLEEP_MESSAGE</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX276"><code>SLEEP_TIME</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX235">Small memory</a></td><td
valign="top"><a href="#SEC80">4.4.3 Coping with Scarce Resources</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC127">Sparse Files</a></td><td
valign="top"><a href="#SEC127">8.1.2 Archiving Sparse Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX416">sparse files v.0.0, extracting
with non-GNU tars</a></td><td valign="top"><a href="#SEC141">8.3.9.2 Extracting
Sparse Members</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX415">sparse files v.0.1, extracting
with non-GNU tars</a></td><td valign="top"><a href="#SEC141">8.3.9.2 Extracting
Sparse Members</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX414">sparse files v.1.0, extracting
with non-GNU tars</a></td><td valign="top"><a href="#SEC141">8.3.9.2 Extracting
Sparse Members</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX478">Sparse files, creating using
<code>genfile</code></a></td><td valign="top"><a href="#SEC172">D.1 Generate
Mode</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC141">sparse files, extracting with
non-GNU tars</a></td><td valign="top"><a href="#SEC141">8.3.9.2 Extracting
Sparse Members</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC165">sparse formats</a></td><td
valign="top"><a href="#SEC165">Storing Sparse Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX401">sparse formats,
defined</a></td><td valign="top"><a href="#SEC127">8.1.2 Archiving Sparse
Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC166">sparse formats, Old
GNU</a></td><td valign="top"><a href="#SEC166">C.0.1 Old GNU
Format</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC167">sparse formats,
v.0.0</a></td><td valign="top"><a href="#SEC167">C.0.2 PAX Format, Versions 0.0
and 0.1</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX468">sparse formats,
v.0.1</a></td><td valign="top"><a href="#SEC167">C.0.2 PAX Format, Versions 0.0
and 0.1</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC168">sparse formats,
v.1.0</a></td><td valign="top"><a href="#SEC168">C.0.3 PAX Format, Version
1.0</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC165">sparse versions</a></td><td
valign="top"><a href="#SEC165">Storing Sparse Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC99">Specifying archive
members</a></td><td valign="top"><a href="#SEC99">6.2 Selecting Archive
Members</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC99">Specifying files to act
on</a></td><td valign="top"><a href="#SEC99">6.2 Selecting Archive
Members</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX296">Standard input and
output</a></td><td valign="top"><a href="#SEC98">6.1 Choosing and Naming
Archive Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC77">Standard output, writing
extracted files to</a></td><td valign="top"><a href="#SEC77">Writing to
Standard Output</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC126">Storing archives in compressed
format</a></td><td valign="top"><a href="#SEC126">8.1.1 Creating and Reading
Compressed Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC131">Symbolic link as file
name</a></td><td valign="top"><a href="#SEC131">8.3.2 Symbolic
Links</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_16">T</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX13"><code>TAPE</code></a></td><td
valign="top"><a href="#SEC14">The ‘<samp>--file</samp>’
Option</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX429">tape blocking</a></td><td
valign="top"><a href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX433">tape marks</a></td><td
valign="top"><a href="#SEC150">9.5 Many Archives on One Tape</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX432">tape positioning</a></td><td
valign="top"><a href="#SEC150">9.5 Many Archives on One Tape</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX265"><code>TAPE_FILE</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX189">Tapes, using
‘<samp>--delete</samp>’ and</a></td><td valign="top"><a
href="#SEC58">4.2.5 Removing Archive Members Using
‘<samp>--delete</samp>’</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC4">tar</a></td><td valign="top"><a
href="#SEC4">1.3 What <code>tar</code> Does</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX279"><code>TAR</code></a></td><td
valign="top"><a href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC3">tar archive</a></td><td
valign="top"><a href="#SEC3">1.2 Some Definitions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC124">Tar archive
formats</a></td><td valign="top"><a href="#SEC124">8. Controlling the Archive
Format</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX11">tar entry</a></td><td
valign="top"><a href="#SEC5">1.4 How <code>tar</code> Archives are
Named</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX9">tar file</a></td><td
valign="top"><a href="#SEC5">1.4 How <code>tar</code> Archives are
Named</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX299">tar to a remote
device</a></td><td valign="top"><a href="#SEC98">6.1 Choosing and Naming
Archive Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX297">tar to standard input and
output</a></td><td valign="top"><a href="#SEC98">6.1 Choosing and Naming
Archive Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX443"><code>TAR_ARCHIVE, info script
environment variable</code></a></td><td valign="top"><a href="#SEC154">9.6.1
Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX226"><code>TAR_ATIME, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX228"><code>TAR_CTIME, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX222"><code>TAR_FILENAME, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX220"><code>TAR_FILETYPE, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX446"><code>TAR_FORMAT, info script
environment variable</code></a></td><td valign="top"><a href="#SEC154">9.6.1
Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX231"><code>TAR_GID, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX225"><code>TAR_GNAME, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX221"><code>TAR_MODE, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX227"><code>TAR_MTIME, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX30"><code>TAR_OPTIONS, environment
variable</code></a></td><td valign="top"><a href="#SEC34">3.2 Using
<code>tar</code> Options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX223"><code>TAR_REALNAME, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX229"><code>TAR_SIZE, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX445"><code>TAR_SUBCOMMAND, info
script environment variable</code></a></td><td valign="top"><a
href="#SEC154">9.6.1 Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX230"><code>TAR_UID, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX224"><code>TAR_UNAME, to-command
environment</code></a></td><td valign="top"><a href="#SEC78">Writing to an
External Program</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX442"><code>TAR_VERSION, info script
environment variable</code></a></td><td valign="top"><a href="#SEC154">9.6.1
Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX444"><code>TAR_VOLUME, info script
environment variable</code></a></td><td valign="top"><a href="#SEC154">9.6.1
Archives Longer than One Tape or Disk</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#SEC156"><code>tarcat</code></a></td><td valign="top"><a
href="#SEC156">9.6.3 Concatenate Volumes into a Single Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX385"><code>this <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC116">time of day item</a></td><td
valign="top"><a href="#SEC116">7.3 Time of day items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX368">time zone
correction</a></td><td valign="top"><a href="#SEC116">7.3 Time of day
items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX357">time zone item</a></td><td
valign="top"><a href="#SEC114">7.1 General date syntax</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC117">time zone item</a></td><td
valign="top"><a href="#SEC117">7.4 Time zone items</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX384"><code>today <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX381"><code>tomorrow <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC122"><code>TZ</code></a></td><td
valign="top"><a href="#SEC122">7.9 Specifying time zone rules</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_17">U</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX424">Ultrix 3.1 and write
failure</a></td><td valign="top"><a href="#SEC145">9.2 The Remote Tape
Server</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX8">unpacking</a></td><td
valign="top"><a href="#SEC3">1.2 Some Definitions</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX182">Updating an
archive</a></td><td valign="top"><a href="#SEC55">4.2.3 Updating an
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX462"><code>usage-indent</code></a></td><td valign="top"><a
href="#SEC161">B. Configuring Help Summary</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX399">Using encrypted
archives</a></td><td valign="top"><a href="#SEC126">8.1.1 Creating and Reading
Compressed Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC133">ustar archive
format</a></td><td valign="top"><a href="#SEC133">8.3.4 Ustar Archive
Format</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX252"><code>uuencode</code></a></td><td valign="top"><a
href="#SEC84">4.6 Notable <code>tar</code> Usages</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_18">V</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC132">v7 archive format</a></td><td
valign="top"><a href="#SEC132">8.3.3 Old V7 Archives</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX163">Verbose operation</a></td><td
valign="top"><a href="#SEC46">3.7 Checking <code>tar</code>
progress</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC158">Verifying a write
operation</a></td><td valign="top"><a href="#SEC158">9.8 Verifying Data as It
is Stored</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC59">Verifying the currency of an
archive</a></td><td valign="top"><a href="#SEC59">4.2.6 Comparing Archive
Members with the File System</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC44">Version of the <code>tar</code>
program</a></td><td valign="top"><a href="#SEC44">3.5 <acronym>GNU</acronym>
<code>tar</code> documentation</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX245"><code>version-control <span
class="roman">Emacs variable</span></code></a></td><td valign="top"><a
href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX243"><code>VERSION_CONTROL</code></a></td><td valign="top"><a
href="#SEC83">4.5 Backup options</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX436">volno file</a></td><td
valign="top"><a href="#SEC154">9.6.1 Archives Longer than One Tape or
Disk</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX274"><code>VOLNO_FILE</code></a></td><td valign="top"><a
href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX448">Volume label,
listing</a></td><td valign="top"><a href="#SEC157">9.7 Including a Label in the
Archive</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX435">Volume number file</a></td><td
valign="top"><a href="#SEC154">9.6.1 Archives Longer than One Tape or
Disk</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_19">W</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX375"><code>week <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX292">Where is the
archive?</a></td><td valign="top"><a href="#SEC98">6.1 Choosing and Naming
Archive Files</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX346">Working directory,
specifying</a></td><td valign="top"><a href="#SEC111">6.10.1 Changing the
Working Directory</a></td></tr>
+<tr><td></td><td valign="top"><a href="#SEC77">Writing extracted files to
standard output</a></td><td valign="top"><a href="#SEC77">Writing to Standard
Output</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX294">Writing new
archives</a></td><td valign="top"><a href="#SEC98">6.1 Choosing and Naming
Archive Files</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_20">X</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX275"><code>XLIST</code></a></td><td
valign="top"><a href="#SEC91">5.4.1 General-Purpose Variables</a></td></tr>
+<tr><td></td><td valign="top"><a
href="#IDX413"><code>xsparse</code></a></td><td valign="top"><a
href="#SEC141">8.3.9.2 Extracting Sparse Members</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+<tr><th><a name="SEC180_21">Y</a></th><td></td><td></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX372"><code>year <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td></td><td valign="top"><a href="#IDX382"><code>yesterday <span
class="roman">in date strings</span></code></a></td><td valign="top"><a
href="#SEC119">7.6 Relative items in date strings</a></td></tr>
+<tr><td colspan="3"> <hr></td></tr>
+</table>
+<table><tr><th valign="top">Jump to: </th><td><a href="#SEC180_0"
class="summary-letter"><b>A</b></a>
+
+<a href="#SEC180_1" class="summary-letter"><b>B</b></a>
+
+<a href="#SEC180_2" class="summary-letter"><b>C</b></a>
+
+<a href="#SEC180_3" class="summary-letter"><b>D</b></a>
+
+<a href="#SEC180_4" class="summary-letter"><b>E</b></a>
+
+<a href="#SEC180_5" class="summary-letter"><b>F</b></a>
+
+<a href="#SEC180_6" class="summary-letter"><b>G</b></a>
+
+<a href="#SEC180_7" class="summary-letter"><b>H</b></a>
+
+<a href="#SEC180_8" class="summary-letter"><b>I</b></a>
+
+<a href="#SEC180_9" class="summary-letter"><b>L</b></a>
+
+<a href="#SEC180_10" class="summary-letter"><b>M</b></a>
+
+<a href="#SEC180_11" class="summary-letter"><b>N</b></a>
+
+<a href="#SEC180_12" class="summary-letter"><b>O</b></a>
+
+<a href="#SEC180_13" class="summary-letter"><b>P</b></a>
+
+<a href="#SEC180_14" class="summary-letter"><b>R</b></a>
+
+<a href="#SEC180_15" class="summary-letter"><b>S</b></a>
+
+<a href="#SEC180_16" class="summary-letter"><b>T</b></a>
+
+<a href="#SEC180_17" class="summary-letter"><b>U</b></a>
+
+<a href="#SEC180_18" class="summary-letter"><b>V</b></a>
+
+<a href="#SEC180_19" class="summary-letter"><b>W</b></a>
+
+<a href="#SEC180_20" class="summary-letter"><b>X</b></a>
+
+<a href="#SEC180_21" class="summary-letter"><b>Y</b></a>
+
+</td></tr></table>
+
+
+<hr size="6">
+<a name="SEC_Foot"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1>Footnotes</h1>
+<h3><a name="FOOT1" href="#DOCF1">(1)</a></h3>
+<p>This 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</code> is compatible with original
+permissions.
+</p><h3><a name="FOOT2" href="#DOCF2">(2)</a></h3>
+<p>Clustering many
+options, the last of which has an argument, is a rather opaque way to
+write options. Some wonder if <acronym>GNU</acronym> <code>getopt</code>
should not
+even be made helpful enough for considering such usages as invalid.
+</p><h3><a name="FOOT3" href="#DOCF3">(3)</a></h3>
+<p>Beware that if you precede options
+with a dash, you are announcing the short option style instead of the
+old option style; short options are decoded differently.
+</p><h3><a name="FOOT4" href="#DOCF4">(4)</a></h3>
+<p>Before <acronym>GNU</acronym> <code>tar</code> version 1.11.6,
+a bug prevented intermixing old style options with long options in
+some cases.
+</p><h3><a name="FOOT5" href="#DOCF5">(5)</a></h3>
+<p>Earlier versions of <acronym>GNU</acronym> <code>tar</code> understood
‘<samp>-l</samp>’ as a
+synonym for ‘<samp>--one-file-system</samp>’. The current
semantics, which
+complies to UNIX98, was introduced with version
+1.15.91. See section <a href="#SEC160">Changes</a>, for more information.
+</p><h3><a name="FOOT6" href="#DOCF6">(6)</a></h3>
+<p>Earlier versions of <acronym>GNU</acronym> <code>tar</code> understood
‘<samp>-l</samp>’ as a
+synonym for ‘<samp>--one-file-system</samp>’. This has changed in
version
+1.15.91. See section <a href="#SEC160">Changes</a>, for more information.
+</p><h3><a name="FOOT7" href="#DOCF7">(7)</a></h3>
+<p>This option was called ‘<samp>--strip-path</samp>’ in
+version 1.14.
+</p><h3><a name="FOOT8" href="#DOCF8">(8)</a></h3>
+<p>There are plans to merge the <code>cpio</code> and
+<code>tar</code> packages into a single one which would be called
+<code>paxutils</code>. So, who knows if, one of this days, the
+‘<samp>--version</samp>’ would not output ‘<samp>tar
(<acronym>GNU</acronym>
+paxutils) 3.2</samp>’
+</p><h3><a name="FOOT9" href="#DOCF9">(9)</a></h3>
+<p>This is well described in <cite>Unix-haters
+Handbook</cite>, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG
+Books, ISBN 1-56884-203-1.
+</p><h3><a name="FOOT10" href="#DOCF10">(10)</a></h3>
+<p>Unless you give it
+‘<samp>--keep-old-files</samp>’ option, or the disk copy is newer
than the
+the one in the archive and you invoke <code>tar</code> with
+‘<samp>--keep-newer-files</samp>’ option
+</p><h3><a name="FOOT11" href="#DOCF11">(11)</a></h3>
+<p>This can cause multiple members to have the same name, for
+information on how this affects reading the archive, <a href="#SEC54">Multiple
Members with the Same Name</a>.
+</p><h3><a name="FOOT12" href="#DOCF12">(12)</a></h3>
+<p>Notice, that since both archives
+were created withouth ‘<samp>-P</samp>’ option (see section <a
href="#SEC112">Absolute File Names</a>), these
+commands should be run from the root file system.
+</p><h3><a name="FOOT13" href="#DOCF13">(13)</a></h3>
+<p>Two
+‘<samp>--verbose</samp>’ options were selected to avoid breaking
usual
+verbose listing output (‘<samp>--list --verbose</samp>’) when
using in
+scripts.
+</p>
+<a name="IDX259"></a>
+<a name="IDX260"></a>
+<a name="IDX261"></a>
+<a name="IDX262"></a>
+<p>Versions of <acronym>GNU</acronym> <code>tar</code> up to 1.15.1 used to
dump verbatim binary
+contents of the DUMPDIR header (with terminating nulls) when
+‘<samp>--incremental</samp>’ or
‘<samp>--listed-incremental</samp>’ 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
+</p><h3><a name="FOOT14" href="#DOCF14">(14)</a></h3>
+<p>For backward compatibility, the <code>backup</code> 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-</samp>’
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from <code>backup</code>
+to <code>level-1</code> and then run <code>level-1</code> whenever you need to
+create a level one dump.
+</p><h3><a name="FOOT15" href="#DOCF15">(15)</a></h3>
+<p>Versions of <acronym>GNU</acronym> <code>tar</code> up to 1.15.1
+recognized only ‘<samp>-C</samp>’ option in file lists, and only
if the
+option and its argument occupied two consecutive lines.
+</p><h3><a name="FOOT16" href="#DOCF16">(16)</a></h3>
+<p>Notice that earlier <acronym>GNU</acronym> <code>tar</code> versions used
+globbing for inclusion members, which contradicted to UNIX98
+specification and was not documented. See section <a
href="#SEC160">Changes</a>, for more
+information on this and other changes.
+</p><h3><a name="FOOT17" href="#DOCF17">(17)</a></h3>
+<p>A side effect of this is that when
+‘<samp>--create</samp>’ is used with
‘<samp>--verbose</samp>’ the resulting output
+is not, generally speaking, the same as the one you'd get running
+<kbd>tar --list</kbd> command. This may be important if you use some
+scripts for comparing both outputs. See <a
href="#listing-member-and-file-names">listing member and file names</a>,
+for the information on how to handle this case.
+</p><h3><a name="FOOT18" href="#DOCF18">(18)</a></h3>
+<p>See section <a href="#SEC168">PAX Format, Version 1.0</a>.
+</p><h3><a name="FOOT19" href="#DOCF19">(19)</a></h3>
+<p>technically speaking, <var>n</var> is a
+<em>process ID</em> of the <code>tar</code> process which created the
+archive (see section <a href="#SEC136">Controlling Extended Header
Keywords</a>).
+</p><h3><a name="FOOT20" href="#DOCF20">(20)</a></h3>
+<p>If you run <acronym>GNU</acronym> <code>tar</code> under a different
locale, the
+translation to the locale's language will be used.
+</p><h3><a name="FOOT21" href="#DOCF21">(21)</a></h3>
+<p>See <a href="#g_t_002d_002drestrict">–restrict</a>, for more
information about
+this option
+</p><h3><a name="FOOT22" href="#DOCF22">(22)</a></h3>
+<p>Previous versions of <code>tar</code> 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
+<code>tar</code>.
+</p><hr size="1">
+<a name="SEC_Contents"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1>Table of Contents</h1>
+<div class="contents">
+
+<ul class="toc">
+ <li><a name="TOC1" href="#SEC1">1. Introduction</a>
+ <ul class="toc">
+ <li><a name="TOC2" href="#SEC2">1.1 What this Book Contains</a></li>
+ <li><a name="TOC3" href="#SEC3">1.2 Some Definitions</a></li>
+ <li><a name="TOC4" href="#SEC4">1.3 What <code>tar</code> Does</a></li>
+ <li><a name="TOC5" href="#SEC5">1.4 How <code>tar</code> Archives are
Named</a></li>
+ <li><a name="TOC6" href="#SEC6">1.5 <acronym>GNU</acronym>
<code>tar</code> Authors</a></li>
+ <li><a name="TOC7" href="#SEC7">1.6 Reporting bugs or suggestions</a></li>
+ </ul></li>
+ <li><a name="TOC8" href="#SEC8">2. Tutorial Introduction to
<code>tar</code></a>
+ <ul class="toc">
+ <li><a name="TOC9" href="#SEC9">2.1 Assumptions this Tutorial
Makes</a></li>
+ <li><a name="TOC10" href="#SEC10">2.2 Stylistic Conventions</a></li>
+ <li><a name="TOC11" href="#SEC11">2.3 Basic <code>tar</code> Operations
and Options</a></li>
+ <li><a name="TOC12" href="#SEC12">2.4 The Three Most Frequently Used
Operations</a></li>
+ <li><a name="TOC13" href="#SEC13">2.5 Two Frequently Used Options</a>
+ <ul class="toc">
+ <li><a name="TOC14" href="#SEC14">The ‘<samp>--file</samp>’
Option</a></li>
+ <li><a name="TOC15" href="#SEC15">The
‘<samp>--verbose</samp>’ Option</a></li>
+ <li><a name="TOC16" href="#SEC16">Getting Help: Using the
‘<samp>--help</samp>’ Option</a></li>
+ </ul></li>
+ <li><a name="TOC17" href="#SEC17">2.6 How to Create Archives</a>
+ <ul class="toc">
+ <li><a name="TOC18" href="#SEC18">2.6.1 Preparing a Practice Directory
for Examples</a></li>
+ <li><a name="TOC19" href="#SEC19">2.6.2 Creating the Archive</a></li>
+ <li><a name="TOC20" href="#SEC20">2.6.3 Running
‘<samp>--create</samp>’ with
‘<samp>--verbose</samp>’</a></li>
+ <li><a name="TOC21" href="#SEC21">2.6.4 Short Forms with
‘<samp>create</samp>’</a></li>
+ <li><a name="TOC22" href="#SEC22">2.6.5 Archiving Directories</a></li>
+ </ul></li>
+ <li><a name="TOC23" href="#SEC23">2.7 How to List Archives</a>
+ <ul class="toc">
+ <li><a name="TOC24" href="#SEC24">Listing the Contents of a Stored
Directory</a></li>
+ </ul></li>
+ <li><a name="TOC25" href="#SEC25">2.8 How to Extract Members from an
Archive</a>
+ <ul class="toc">
+ <li><a name="TOC26" href="#SEC26">2.8.1 Extracting an Entire
Archive</a></li>
+ <li><a name="TOC27" href="#SEC27">2.8.2 Extracting Specific
Files</a></li>
+ <li><a name="TOC28" href="#SEC28">2.8.3 Extracting Files that are
Directories</a></li>
+ <li><a name="TOC29" href="#SEC29">2.8.4 Extracting Archives from
Untrusted Sources</a></li>
+ <li><a name="TOC30" href="#SEC30">2.8.5 Commands That Will Fail</a></li>
+ </ul></li>
+ <li><a name="TOC31" href="#SEC31">2.9 Going Further Ahead in this
Manual</a></li>
+ </ul></li>
+ <li><a name="TOC32" href="#SEC32">3. Invoking <acronym>GNU</acronym>
<code>tar</code></a>
+ <ul class="toc">
+ <li><a name="TOC33" href="#SEC33">3.1 General Synopsis of
<code>tar</code></a></li>
+ <li><a name="TOC34" href="#SEC34">3.2 Using <code>tar</code>
Options</a></li>
+ <li><a name="TOC35" href="#SEC35">3.3 The Three Option Styles</a>
+ <ul class="toc">
+ <li><a name="TOC36" href="#SEC36">3.3.1 Long Option Style</a></li>
+ <li><a name="TOC37" href="#SEC37">3.3.2 Short Option Style</a></li>
+ <li><a name="TOC38" href="#SEC38">3.3.3 Old Option Style</a></li>
+ <li><a name="TOC39" href="#SEC39">3.3.4 Mixing Option Styles</a></li>
+ </ul></li>
+ <li><a name="TOC40" href="#SEC40">3.4 All <code>tar</code> Options</a>
+ <ul class="toc">
+ <li><a name="TOC41" href="#SEC41">3.4.1 Operations</a></li>
+ <li><a name="TOC42" href="#SEC42">3.4.2 <code>tar</code> Options</a></li>
+ <li><a name="TOC43" href="#SEC43">3.4.3 Short Options Cross
Reference</a></li>
+ </ul></li>
+ <li><a name="TOC44" href="#SEC44">3.5 <acronym>GNU</acronym>
<code>tar</code> documentation</a></li>
+ <li><a name="TOC45" href="#SEC45">3.6 Obtaining <acronym>GNU</acronym>
<code>tar</code> default values</a></li>
+ <li><a name="TOC46" href="#SEC46">3.7 Checking <code>tar</code>
progress</a></li>
+ <li><a name="TOC47" href="#SEC47">3.8 Asking for Confirmation During
Operations</a></li>
+ </ul></li>
+ <li><a name="TOC48" href="#SEC48">4. <acronym>GNU</acronym> <code>tar</code>
Operations</a>
+ <ul class="toc">
+ <li><a name="TOC49" href="#SEC49">4.1 Basic <acronym>GNU</acronym>
<code>tar</code> Operations</a></li>
+ <li><a name="TOC50" href="#SEC50">4.2 Advanced <acronym>GNU</acronym>
<code>tar</code> Operations</a>
+ <ul class="toc">
+ <li><a name="TOC51" href="#SEC51">4.2.1 The Five Advanced
<code>tar</code> Operations</a></li>
+ <li><a name="TOC52" href="#SEC52">4.2.2 How to Add Files to Existing
Archives: ‘<samp>--append</samp>’</a>
+ <ul class="toc">
+ <li><a name="TOC53" href="#SEC53">4.2.2.1 Appending Files to an
Archive</a></li>
+ <li><a name="TOC54" href="#SEC54">4.2.2.2 Multiple Members with the
Same Name</a></li>
+ </ul></li>
+ <li><a name="TOC55" href="#SEC55">4.2.3 Updating an Archive</a>
+ <ul class="toc">
+ <li><a name="TOC56" href="#SEC56">4.2.3.1 How to Update an Archive
Using ‘<samp>--update</samp>’</a></li>
+ </ul></li>
+ <li><a name="TOC57" href="#SEC57">4.2.4 Combining Archives with
‘<samp>--concatenate</samp>’</a></li>
+ <li><a name="TOC58" href="#SEC58">4.2.5 Removing Archive Members Using
‘<samp>--delete</samp>’</a></li>
+ <li><a name="TOC59" href="#SEC59">4.2.6 Comparing Archive Members with
the File System</a></li>
+ </ul></li>
+ <li><a name="TOC60" href="#SEC60">4.3 Options Used by
‘<samp>--create</samp>’</a>
+ <ul class="toc">
+ <li><a name="TOC61" href="#SEC61">4.3.1 Overriding File Metadata</a></li>
+ <li><a name="TOC62" href="#SEC62">4.3.2 Ignore Fail Read</a></li>
+ </ul></li>
+ <li><a name="TOC63" href="#SEC63">4.4 Options Used by
‘<samp>--extract</samp>’</a>
+ <ul class="toc">
+ <li><a name="TOC64" href="#SEC64">4.4.1 Options to Help Read Archives</a>
+ <ul class="toc">
+ <li><a name="TOC65" href="#SEC65">Reading Full Records</a></li>
+ <li><a name="TOC66" href="#SEC66">Ignoring Blocks of Zeros</a></li>
+ </ul></li>
+ <li><a name="TOC67" href="#SEC67">4.4.2 Changing How <code>tar</code>
Writes Files</a>
+ <ul class="toc">
+ <li><a name="TOC68" href="#SEC68">Options Controlling the Overwriting
of Existing Files</a></li>
+ <li><a name="TOC69" href="#SEC69">Overwrite Old Files</a></li>
+ <li><a name="TOC70" href="#SEC70">Keep Old Files</a></li>
+ <li><a name="TOC71" href="#SEC71">Keep Newer Files</a></li>
+ <li><a name="TOC72" href="#SEC72">Unlink First</a></li>
+ <li><a name="TOC73" href="#SEC73">Recursive Unlink</a></li>
+ <li><a name="TOC74" href="#SEC74">Setting Data Modification
Times</a></li>
+ <li><a name="TOC75" href="#SEC75">Setting Access Permissions</a></li>
+ <li><a name="TOC76" href="#SEC76">Directory Modification Times and
Permissions</a></li>
+ <li><a name="TOC77" href="#SEC77">Writing to Standard Output</a></li>
+ <li><a name="TOC78" href="#SEC78">Writing to an External
Program</a></li>
+ <li><a name="TOC79" href="#SEC79">Removing Files</a></li>
+ </ul></li>
+ <li><a name="TOC80" href="#SEC80">4.4.3 Coping with Scarce Resources</a>
+ <ul class="toc">
+ <li><a name="TOC81" href="#SEC81">Starting File</a></li>
+ <li><a name="TOC82" href="#SEC82">Same Order</a></li>
+ </ul>
+</li>
+ </ul></li>
+ <li><a name="TOC83" href="#SEC83">4.5 Backup options</a></li>
+ <li><a name="TOC84" href="#SEC84">4.6 Notable <code>tar</code>
Usages</a></li>
+ <li><a name="TOC85" href="#SEC85">4.7 Looking Ahead: The Rest of this
Manual</a></li>
+ </ul></li>
+ <li><a name="TOC86" href="#SEC86">5. Performing Backups and Restoring
Files</a>
+ <ul class="toc">
+ <li><a name="TOC87" href="#SEC87">5.1 Using <code>tar</code> to Perform
Full Dumps</a></li>
+ <li><a name="TOC88" href="#SEC88">5.2 Using <code>tar</code> to Perform
Incremental Dumps</a></li>
+ <li><a name="TOC89" href="#SEC89">5.3 Levels of Backups</a></li>
+ <li><a name="TOC90" href="#SEC90">5.4 Setting Parameters for Backups and
Restoration</a>
+ <ul class="toc">
+ <li><a name="TOC91" href="#SEC91">5.4.1 General-Purpose
Variables</a></li>
+ <li><a name="TOC92" href="#SEC92">5.4.2 Magnetic Tape Control</a></li>
+ <li><a name="TOC93" href="#SEC93">5.4.3 User Hooks</a></li>
+ <li><a name="TOC94" href="#SEC94">5.4.4 An Example Text of
‘<tt>Backup-specs</tt>’</a></li>
+ </ul></li>
+ <li><a name="TOC95" href="#SEC95">5.5 Using the Backup Scripts</a></li>
+ <li><a name="TOC96" href="#SEC96">5.6 Using the Restore Script</a></li>
+ </ul></li>
+ <li><a name="TOC97" href="#SEC97">6. Choosing Files and Names for
<code>tar</code></a>
+ <ul class="toc">
+ <li><a name="TOC98" href="#SEC98">6.1 Choosing and Naming Archive
Files</a></li>
+ <li><a name="TOC99" href="#SEC99">6.2 Selecting Archive Members</a></li>
+ <li><a name="TOC100" href="#SEC100">6.3 Reading Names from a File</a>
+ <ul class="toc">
+ <li><a name="TOC101" href="#SEC101">6.3.1 <code>NUL</code> Terminated
File Names</a></li>
+ </ul></li>
+ <li><a name="TOC102" href="#SEC102">6.4 Excluding Some Files</a>
+ <ul class="toc">
+ <li><a name="TOC103" href="#SEC103">Problems with Using the
<code>exclude</code> Options</a></li>
+ </ul></li>
+ <li><a name="TOC104" href="#SEC104">6.5 Wildcards Patterns and Matching</a>
+ <ul class="toc">
+ <li><a name="TOC105" href="#SEC105">Controlling Pattern-Matching</a></li>
+ </ul></li>
+ <li><a name="TOC106" href="#SEC106">6.6 Quoting Member Names</a></li>
+ <li><a name="TOC107" href="#SEC107">6.7 Modifying File and Member
Names</a></li>
+ <li><a name="TOC108" href="#SEC108">6.8 Operating Only on New
Files</a></li>
+ <li><a name="TOC109" href="#SEC109">6.9 Descending into
Directories</a></li>
+ <li><a name="TOC110" href="#SEC110">6.10 Crossing File System
Boundaries</a>
+ <ul class="toc">
+ <li><a name="TOC111" href="#SEC111">6.10.1 Changing the Working
Directory</a></li>
+ <li><a name="TOC112" href="#SEC112">6.10.2 Absolute File Names</a></li>
+ </ul>
+</li>
+ </ul></li>
+ <li><a name="TOC113" href="#SEC113">7. Date input formats</a>
+ <ul class="toc">
+ <li><a name="TOC114" href="#SEC114">7.1 General date syntax</a></li>
+ <li><a name="TOC115" href="#SEC115">7.2 Calendar date items</a></li>
+ <li><a name="TOC116" href="#SEC116">7.3 Time of day items</a></li>
+ <li><a name="TOC117" href="#SEC117">7.4 Time zone items</a></li>
+ <li><a name="TOC118" href="#SEC118">7.5 Day of week items</a></li>
+ <li><a name="TOC119" href="#SEC119">7.6 Relative items in date
strings</a></li>
+ <li><a name="TOC120" href="#SEC120">7.7 Pure numbers in date
strings</a></li>
+ <li><a name="TOC121" href="#SEC121">7.8 Seconds since the Epoch</a></li>
+ <li><a name="TOC122" href="#SEC122">7.9 Specifying time zone rules</a></li>
+ <li><a name="TOC123" href="#SEC123">7.10 Authors of
<code>get_date</code></a></li>
+ </ul></li>
+ <li><a name="TOC124" href="#SEC124">8. Controlling the Archive Format</a>
+ <ul class="toc">
+ <li><a name="TOC125" href="#SEC125">8.1 Using Less Space through
Compression</a>
+ <ul class="toc">
+ <li><a name="TOC126" href="#SEC126">8.1.1 Creating and Reading
Compressed Archives</a></li>
+ <li><a name="TOC127" href="#SEC127">8.1.2 Archiving Sparse Files</a></li>
+ </ul></li>
+ <li><a name="TOC128" href="#SEC128">8.2 Handling File Attributes</a></li>
+ <li><a name="TOC129" href="#SEC129">8.3 Making <code>tar</code> Archives
More Portable</a>
+ <ul class="toc">
+ <li><a name="TOC130" href="#SEC130">8.3.1 Portable Names</a></li>
+ <li><a name="TOC131" href="#SEC131">8.3.2 Symbolic Links</a></li>
+ <li><a name="TOC132" href="#SEC132">8.3.3 Old V7 Archives</a></li>
+ <li><a name="TOC133" href="#SEC133">8.3.4 Ustar Archive Format</a></li>
+ <li><a name="TOC134" href="#SEC134">8.3.5 <acronym>GNU</acronym> and old
<acronym>GNU</acronym> <code>tar</code> format</a></li>
+ <li><a name="TOC135" href="#SEC135">8.3.6 <acronym>GNU</acronym>
<code>tar</code> and <acronym>POSIX</acronym> <code>tar</code></a>
+ <ul class="toc">
+ <li><a name="TOC136" href="#SEC136">8.3.6.1 Controlling Extended
Header Keywords</a></li>
+ </ul></li>
+ <li><a name="TOC137" href="#SEC137">8.3.7 Checksumming Problems</a></li>
+ <li><a name="TOC138" href="#SEC138">8.3.8 Large or Negative
Values</a></li>
+ <li><a name="TOC139" href="#SEC139">8.3.9 How to Extract GNU-Specific
Data Using Other <code>tar</code> Implementations</a>
+ <ul class="toc">
+ <li><a name="TOC140" href="#SEC140">8.3.9.1 Extracting Members Split
Between Volumes</a></li>
+ <li><a name="TOC141" href="#SEC141">8.3.9.2 Extracting Sparse
Members</a></li>
+ </ul>
+</li>
+ </ul></li>
+ <li><a name="TOC142" href="#SEC142">8.4 Comparison of <code>tar</code> and
<code>cpio</code></a></li>
+ </ul></li>
+ <li><a name="TOC143" href="#SEC143">9. Tapes and Other Archive Media</a>
+ <ul class="toc">
+ <li><a name="TOC144" href="#SEC144">9.1 Device Selection and
Switching</a></li>
+ <li><a name="TOC145" href="#SEC145">9.2 The Remote Tape Server</a></li>
+ <li><a name="TOC146" href="#SEC146">9.3 Some Common Problems and their
Solutions</a></li>
+ <li><a name="TOC147" href="#SEC147">9.4 Blocking</a>
+ <ul class="toc">
+ <li><a name="TOC148" href="#SEC148">9.4.1 Format Variations</a></li>
+ <li><a name="TOC149" href="#SEC149">9.4.2 The Blocking Factor of an
Archive</a></li>
+ </ul></li>
+ <li><a name="TOC150" href="#SEC150">9.5 Many Archives on One Tape</a>
+ <ul class="toc">
+ <li><a name="TOC151" href="#SEC151">9.5.1 Tape Positions and Tape
Marks</a></li>
+ <li><a name="TOC152" href="#SEC152">9.5.2 The <code>mt</code>
Utility</a></li>
+ </ul></li>
+ <li><a name="TOC153" href="#SEC153">9.6 Using Multiple Tapes</a>
+ <ul class="toc">
+ <li><a name="TOC154" href="#SEC154">9.6.1 Archives Longer than One Tape
or Disk</a></li>
+ <li><a name="TOC155" href="#SEC155">9.6.2 Tape Files</a></li>
+ <li><a name="TOC156" href="#SEC156">9.6.3 Concatenate Volumes into a
Single Archive</a></li>
+ </ul></li>
+ <li><a name="TOC157" href="#SEC157">9.7 Including a Label in the
Archive</a></li>
+ <li><a name="TOC158" href="#SEC158">9.8 Verifying Data as It is
Stored</a></li>
+ <li><a name="TOC159" href="#SEC159">9.9 Write Protection</a></li>
+ </ul></li>
+ <li><a name="TOC160" href="#SEC160">A. Changes</a></li>
+ <li><a name="TOC161" href="#SEC161">B. Configuring Help Summary</a></li>
+ <li><a name="TOC162" href="#SEC162">C. Tar Internals</a>
+ <ul class="toc">
+ <li><a name="TOC163" href="#SEC163">Basic Tar Format</a></li>
+ <li><a name="TOC164" href="#SEC164"><acronym>GNU</acronym> Extensions to
the Archive Format</a></li>
+ <li><a name="TOC165" href="#SEC165">Storing Sparse Files</a>
+ <ul class="toc">
+ <li><a name="TOC166" href="#SEC166">C.0.1 Old GNU Format</a></li>
+ <li><a name="TOC167" href="#SEC167">C.0.2 PAX Format, Versions 0.0 and
0.1</a></li>
+ <li><a name="TOC168" href="#SEC168">C.0.3 PAX Format, Version
1.0</a></li>
+ </ul></li>
+ <li><a name="TOC169" href="#SEC169">Format of the Incremental Snapshot
Files</a></li>
+ <li><a name="TOC170" href="#SEC170">Dumpdir</a></li>
+ </ul></li>
+ <li><a name="TOC171" href="#SEC171">D. Genfile</a>
+ <ul class="toc">
+ <li><a name="TOC172" href="#SEC172">D.1 Generate Mode</a></li>
+ <li><a name="TOC173" href="#SEC173">D.2 Status Mode</a></li>
+ <li><a name="TOC174" href="#SEC174">D.3 Exec Mode</a></li>
+ </ul></li>
+ <li><a name="TOC175" href="#SEC175">E. Free Software Needs Free
Documentation</a></li>
+ <li><a name="TOC176" href="#SEC176">F. Copying This Manual</a>
+ <ul class="toc">
+ <li><a name="TOC177" href="#SEC177">F.1 GNU Free Documentation License</a>
+ <ul class="toc">
+ <li><a name="TOC178" href="#SEC178">F.1.1 ADDENDUM: How to use this
License for your documents</a></li>
+ </ul>
+</li>
+ </ul></li>
+ <li><a name="TOC179" href="#SEC179">G. Index of Command Line Options</a></li>
+ <li><a name="TOC180" href="#SEC180">H. Index</a></li>
+</ul>
+</div>
+<hr size="1">
+<a name="SEC_Overview"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1>Short Table of Contents</h1>
+<div class="shortcontents">
+<ul class="toc">
+<li><a name="TOC1" href="#SEC1">1. Introduction</a></li>
+<li><a name="TOC8" href="#SEC8">2. Tutorial Introduction to
<code>tar</code></a></li>
+<li><a name="TOC32" href="#SEC32">3. Invoking <acronym>GNU</acronym>
<code>tar</code></a></li>
+<li><a name="TOC48" href="#SEC48">4. <acronym>GNU</acronym> <code>tar</code>
Operations</a></li>
+<li><a name="TOC86" href="#SEC86">5. Performing Backups and Restoring
Files</a></li>
+<li><a name="TOC97" href="#SEC97">6. Choosing Files and Names for
<code>tar</code></a></li>
+<li><a name="TOC113" href="#SEC113">7. Date input formats</a></li>
+<li><a name="TOC124" href="#SEC124">8. Controlling the Archive Format</a></li>
+<li><a name="TOC143" href="#SEC143">9. Tapes and Other Archive Media</a></li>
+<li><a name="TOC160" href="#SEC160">A. Changes</a></li>
+<li><a name="TOC161" href="#SEC161">B. Configuring Help Summary</a></li>
+<li><a name="TOC162" href="#SEC162">C. Tar Internals</a></li>
+<li><a name="TOC171" href="#SEC171">D. Genfile</a></li>
+<li><a name="TOC175" href="#SEC175">E. Free Software Needs Free
Documentation</a></li>
+<li><a name="TOC176" href="#SEC176">F. Copying This Manual</a></li>
+<li><a name="TOC179" href="#SEC179">G. Index of Command Line Options</a></li>
+<li><a name="TOC180" href="#SEC180">H. Index</a></li>
+</ul>
+</div>
+<hr size="1">
+<a name="SEC_About"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC_Top" title="Cover (top) of
document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_Contents" title="Table of
contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC179"
title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="#SEC_About" title="About (help)"> ?
</a>]</td>
+</tr></table>
+<h1>About This Document</h1>
+<p>
+ This document was generated by <em>a tester</em> on <em>a sunny day</em>
using <a href="http://www.nongnu.org/texi2html/";><em>texi2html</em></a>.
+</p>
+<p>
+ The buttons in the navigation panels have the following meaning:
+</p>
+<table border="1">
+ <tr>
+ <th> Button </th>
+ <th> Name </th>
+ <th> Go to </th>
+ <th> From 1.2.3 go to</th>
+ </tr>
+ <tr>
+ <td align="center"> [ < ] </td>
+ <td align="center">Back</td>
+ <td>Previous section in reading order</td>
+ <td>1.2.2</td>
+ </tr>
+ <tr>
+ <td align="center"> [ > ] </td>
+ <td align="center">Forward</td>
+ <td>Next section in reading order</td>
+ <td>1.2.4</td>
+ </tr>
+ <tr>
+ <td align="center"> [ << ] </td>
+ <td align="center">FastBack</td>
+ <td>Beginning of this chapter or previous chapter</td>
+ <td>1</td>
+ </tr>
+ <tr>
+ <td align="center"> [ Up ] </td>
+ <td align="center">Up</td>
+ <td>Up section</td>
+ <td>1.2</td>
+ </tr>
+ <tr>
+ <td align="center"> [ >> ] </td>
+ <td align="center">FastForward</td>
+ <td>Next chapter</td>
+ <td>2</td>
+ </tr>
+ <tr>
+ <td align="center"> [Top] </td>
+ <td align="center">Top</td>
+ <td>Cover (top) of document</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td align="center"> [Contents] </td>
+ <td align="center">Contents</td>
+ <td>Table of contents</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td align="center"> [Index] </td>
+ <td align="center">Index</td>
+ <td>Index</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td align="center"> [ ? ] </td>
+ <td align="center">About</td>
+ <td>About (help)</td>
+ <td> </td>
+ </tr>
+</table>
+
+<p>
+ where the <strong> Example </strong> assumes that the current position is at
<strong> Subsubsection One-Two-Three </strong> of a document of the following
structure:
+</p>
+
+<ul>
+ <li> 1. Section One
+ <ul>
+ <li>1.1 Subsection One-One
+ <ul>
+ <li>...</li>
+ </ul>
+ </li>
+ <li>1.2 Subsection One-Two
+ <ul>
+ <li>1.2.1 Subsubsection One-Two-One</li>
+ <li>1.2.2 Subsubsection One-Two-Two</li>
+ <li>1.2.3 Subsubsection One-Two-Three
+ <strong><== Current Position </strong></li>
+ <li>1.2.4 Subsubsection One-Two-Four</li>
+ </ul>
+ </li>
+ <li>1.3 Subsection One-Three
+ <ul>
+ <li>...</li>
+ </ul>
+ </li>
+ <li>1.4 Subsection One-Four</li>
+ </ul>
+ </li>
+</ul>
+
+<hr size="1">
+<p>
+ <font size="-1">
+ This document was generated by <em>a tester</em> on <em>a sunny day</em>
using <a href="http://www.nongnu.org/texi2html/";><em>texi2html</em></a>.
+ </font>
+ <br>
+
+</p>
+</body>
+</html>
Index: Tests/tar_res/tar.passfirst
===================================================================
RCS file: Tests/tar_res/tar.passfirst
diff -N Tests/tar_res/tar.passfirst
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_res/tar.passfirst 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,13423 @@
+../tar_texi/tar.texi(,2) @comment %**start of header
+../tar_texi/tar.texi(,3) @setfilename tar.info
+../tar_texi/tar.texi(,5) @settitle GNU tar 1.15.92
+../tar_texi/tar.texi(,6) @setchapternewpage odd
+../tar_texi/tar.texi(,7)
+../tar_texi/tar.texi(,8) @finalout
+../tar_texi/tar.texi(,9)
+../tar_texi/tar.texi(,10) @smallbook
+../tar_texi/tar.texi(,11) @c %**end of header
+../tar_texi/tar.texi(,12)
+../tar_texi/tar.texi(,13) @c Maintenance notes:
+../tar_texi/tar.texi(,14) @c 1. Pay attention to @FIXME{}s and @UNREVISED{}s
+../tar_texi/tar.texi(,15) @c 2. Before creating final variant:
+../tar_texi/tar.texi(,16) @c 2.1. Run `make check-options' to make sure all
options are properly
+../tar_texi/tar.texi(,17) @c documented;
+../tar_texi/tar.texi(,18) @c 2.2. Run `make master-menu' (see comment
before the master menu).
+../tar_texi/tar.texi(,19)
+../tar_texi/rendition.texi(,1) @c This is part of GNU tar manual.
+../tar_texi/rendition.texi(,2) @c Copyright (C) 1992, 1994, 1995, 1996, 1997,
1999, 2000, 2001,
+../tar_texi/rendition.texi(,3) @c 2003, 2004, 2006 Free Software Foundation,
Inc.
+../tar_texi/rendition.texi(,4) @c See file tar.texi for copying conditions.
+../tar_texi/rendition.texi(,5)
+../tar_texi/rendition.texi(,6) @c This file contains support for 'renditions'
by Fran@,{c}ois Pinard
+../tar_texi/rendition.texi(,7) @c I extended it by adding a FIXME_FOOTNOTE
variable, which controls
+../tar_texi/rendition.texi(,8) @c whether FIXME information should be placed
in footnotes or
+../tar_texi/rendition.texi(,9) @c inlined. --gray
+../tar_texi/rendition.texi(,10)
+../tar_texi/rendition.texi(,11) @c
======================================================================
+../tar_texi/rendition.texi(,12) @c This document has three levels of
rendition: PUBLISH, DISTRIB or PROOF,
+../tar_texi/rendition.texi(,13) @c as decided by @set symbols. The PUBLISH
rendition does not show
+../tar_texi/rendition.texi(,14) @c notes or marks asking for revision. Most
users will prefer having more
+../tar_texi/rendition.texi(,15) @c information, even if this information is
not fully revised for adequacy,
+../tar_texi/rendition.texi(,16) @c so DISTRIB is the default for
distributions. The PROOF rendition
+../tar_texi/rendition.texi(,17) @c show all marks to the point of ugliness,
but is nevertheless useful to
+../tar_texi/rendition.texi(,18) @c those working on the manual itself.
+../tar_texi/rendition.texi(,19) @c
======================================================================
+../tar_texi/rendition.texi(,20)
+../tar_texi/rendition.texi(,21) @c Set this symbol if you wish FIXMEs to
appear in footnotes, instead
+../tar_texi/rendition.texi(,22) @c of being inserted into the text.
+../tar_texi/rendition.texi(,23) @c @set PROOF_FOOTNOTED
+../tar_texi/rendition.texi(,24)
+../tar_texi/rendition.texi(,32)
+../tar_texi/rendition.texi(,36)
+../tar_texi/rendition.texi(,40)
+../tar_texi/rendition.texi(,44)
+../tar_texi/rendition.texi(,45) @c Output marks for nodes needing revision,
but not in PUBLISH rendition.
+../tar_texi/rendition.texi(,46)
+../tar_texi/rendition.texi(,54)
+../tar_texi/rendition.texi(,55) @c Output various FIXME information only in
PROOF rendition.
+../tar_texi/rendition.texi(,56)
+../tar_texi/rendition.texi(,72)
+../tar_texi/rendition.texi(,79)
+../tar_texi/rendition.texi(,87)
+../tar_texi/rendition.texi(,94)
+../tar_texi/rendition.texi(,95) @c End of rendition.texi
+../tar_texi/value.texi(,1) @c This is part of GNU tar manual.
+../tar_texi/value.texi(,2) @c Copyright (C) 1992, 1994, 1995, 1996, 1997,
1999, 2000, 2001,
+../tar_texi/value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation,
Inc.
+../tar_texi/value.texi(,4) @c See file tar.texi for copying conditions.
+../tar_texi/value.texi(,5)
+../tar_texi/value.texi(,9)
+../tar_texi/value.texi(,13)
+../tar_texi/value.texi(,21)
+../tar_texi/value.texi(,22)
+../tar_texi/tar.texi(,22)
+../tar_texi/tar.texi(,23) @defcodeindex op
+../tar_texi/tar.texi(,24)
+../tar_texi/tar.texi(,25) @c Put everything in one index (arbitrarily chosen
to be the concept index).
+../tar_texi/tar.texi(,26) @syncodeindex fn cp
+../tar_texi/tar.texi(,27) @syncodeindex ky cp
+../tar_texi/tar.texi(,28) @syncodeindex pg cp
+../tar_texi/tar.texi(,29) @syncodeindex vr cp
+../tar_texi/tar.texi(,30)
+../tar_texi/tar.texi(,53)
+../tar_texi/tar.texi(,54) @dircategory Archiving
+../tar_texi/tar.texi(,58)
+../tar_texi/tar.texi(,59) @dircategory Individual utilities
+../tar_texi/tar.texi(,63)
+../tar_texi/tar.texi(,64) @shorttitlepage @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,65)
+../tar_texi/tar.texi(,75)
+../tar_texi/tar.texi(,77) @node Top
+../tar_texi/tar.texi(,78) @top @acronym{GNU} tar: an archiver tool
+../tar_texi/tar.texi(,79)
+../tar_texi/tar.texi(,80) @insertcopying
+../tar_texi/tar.texi(,81)
+../tar_texi/tar.texi(,82) @cindex file archival
+../tar_texi/tar.texi(,83) @cindex archiving files
+../tar_texi/tar.texi(,84)
+../tar_texi/tar.texi(,85) The first part of this master menu lists the major
nodes in this Info
+../tar_texi/tar.texi(,86) document. The rest of the menu lists all the lower
level nodes.
+../tar_texi/tar.texi(,88)
+../tar_texi/tar.texi(,89) @c The master menu goes here.
+../tar_texi/tar.texi(,90) @c
+../tar_texi/tar.texi(,91) @c NOTE: To update it from within Emacs, make sure
mastermenu.el is
+../tar_texi/tar.texi(,92) @c loaded and run texinfo-master-menu.
+../tar_texi/tar.texi(,93) @c To update it from the command line, run
+../tar_texi/tar.texi(,94) @c
+../tar_texi/tar.texi(,95) @c make master-menu
+../tar_texi/tar.texi(,96)
+../tar_texi/tar.texi(,97) @menu
+../tar_texi/tar.texi(,98) * Introduction::
+../tar_texi/tar.texi(,99) * Tutorial::
+../tar_texi/tar.texi(,100) * tar invocation::
+../tar_texi/tar.texi(,101) * operations::
+../tar_texi/tar.texi(,102) * Backups::
+../tar_texi/tar.texi(,103) * Choosing::
+../tar_texi/tar.texi(,104) * Date input formats::
+../tar_texi/tar.texi(,105) * Formats::
+../tar_texi/tar.texi(,106) * Media::
+../tar_texi/tar.texi(,107)
+../tar_texi/tar.texi(,108) Appendices
+../tar_texi/tar.texi(,109)
+../tar_texi/tar.texi(,110) * Changes::
+../tar_texi/tar.texi(,111) * Configuring Help Summary::
+../tar_texi/tar.texi(,112) * Tar Internals::
+../tar_texi/tar.texi(,113) * Genfile::
+../tar_texi/tar.texi(,114) * Free Software Needs Free Documentation::
+../tar_texi/tar.texi(,115) * Copying This Manual::
+../tar_texi/tar.texi(,116) * Index of Command Line Options::
+../tar_texi/tar.texi(,117) * Index::
+../tar_texi/tar.texi(,118)
+../tar_texi/tar.texi(,119) @detailmenu
+../tar_texi/tar.texi(,120) --- The Detailed Node Listing ---
+../tar_texi/tar.texi(,121)
+../tar_texi/tar.texi(,122) Introduction
+../tar_texi/tar.texi(,123)
+../tar_texi/tar.texi(,124) * Book Contents:: What this Book
Contains
+../tar_texi/tar.texi(,125) * Definitions:: Some Definitions
+../tar_texi/tar.texi(,126) * What tar Does:: What @command{tar}
Does
+../tar_texi/tar.texi(,127) * Naming tar Archives:: How @command{tar}
Archives are Named
+../tar_texi/tar.texi(GNUTAR,128) * Authors:: @acronym{GNU}
@command{tar} Authors
+../tar_texi/tar.texi(,129) * Reports:: Reporting bugs or
suggestions
+../tar_texi/tar.texi(,130)
+../tar_texi/tar.texi(,131) Tutorial Introduction to @command{tar}
+../tar_texi/tar.texi(,132)
+../tar_texi/tar.texi(,133) * assumptions::
+../tar_texi/tar.texi(,134) * stylistic conventions::
+../tar_texi/tar.texi(,135) * basic tar options:: Basic @command{tar}
Operations and Options
+../tar_texi/tar.texi(,136) * frequent operations::
+../tar_texi/tar.texi(,137) * Two Frequent Options::
+../tar_texi/tar.texi(,138) * create:: How to Create
Archives
+../tar_texi/tar.texi(,139) * list:: How to List Archives
+../tar_texi/tar.texi(,140) * extract:: How to Extract
Members from an Archive
+../tar_texi/tar.texi(,141) * going further::
+../tar_texi/tar.texi(,142)
+../tar_texi/tar.texi(,143) Two Frequently Used Options
+../tar_texi/tar.texi(,144)
+../tar_texi/tar.texi(,145) * file tutorial::
+../tar_texi/tar.texi(,146) * verbose tutorial::
+../tar_texi/tar.texi(,147) * help tutorial::
+../tar_texi/tar.texi(,148)
+../tar_texi/tar.texi(,149) How to Create Archives
+../tar_texi/tar.texi(,150)
+../tar_texi/tar.texi(,151) * prepare for examples::
+../tar_texi/tar.texi(,152) * Creating the archive::
+../tar_texi/tar.texi(,153) * create verbose::
+../tar_texi/tar.texi(,154) * short create::
+../tar_texi/tar.texi(,155) * create dir::
+../tar_texi/tar.texi(,156)
+../tar_texi/tar.texi(,157) How to List Archives
+../tar_texi/tar.texi(,158)
+../tar_texi/tar.texi(,159) * list dir::
+../tar_texi/tar.texi(,160)
+../tar_texi/tar.texi(,161) How to Extract Members from an Archive
+../tar_texi/tar.texi(,162)
+../tar_texi/tar.texi(,163) * extracting archives::
+../tar_texi/tar.texi(,164) * extracting files::
+../tar_texi/tar.texi(,165) * extract dir::
+../tar_texi/tar.texi(,166) * extracting untrusted archives::
+../tar_texi/tar.texi(,167) * failing commands::
+../tar_texi/tar.texi(,168)
+../tar_texi/tar.texi(GNUTAR,169) Invoking @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,170)
+../tar_texi/tar.texi(,171) * Synopsis::
+../tar_texi/tar.texi(,172) * using tar options::
+../tar_texi/tar.texi(,173) * Styles::
+../tar_texi/tar.texi(,174) * All Options::
+../tar_texi/tar.texi(,175) * help::
+../tar_texi/tar.texi(,176) * defaults::
+../tar_texi/tar.texi(,177) * verbose::
+../tar_texi/tar.texi(,178) * interactive::
+../tar_texi/tar.texi(,179)
+../tar_texi/tar.texi(,180) The Three Option Styles
+../tar_texi/tar.texi(,181)
+../tar_texi/tar.texi(,182) * Long Options:: Long Option Style
+../tar_texi/tar.texi(,183) * Short Options:: Short Option Style
+../tar_texi/tar.texi(,184) * Old Options:: Old Option Style
+../tar_texi/tar.texi(,185) * Mixing:: Mixing Option Styles
+../tar_texi/tar.texi(,186)
+../tar_texi/tar.texi(,187) All @command{tar} Options
+../tar_texi/tar.texi(,188)
+../tar_texi/tar.texi(,189) * Operation Summary::
+../tar_texi/tar.texi(,190) * Option Summary::
+../tar_texi/tar.texi(,191) * Short Option Summary::
+../tar_texi/tar.texi(,192)
+../tar_texi/tar.texi(GNUTAR,193) @acronym{GNU} @command{tar} Operations
+../tar_texi/tar.texi(,194)
+../tar_texi/tar.texi(,195) * Basic tar::
+../tar_texi/tar.texi(,196) * Advanced tar::
+../tar_texi/tar.texi(,197) * create options::
+../tar_texi/tar.texi(,198) * extract options::
+../tar_texi/tar.texi(,199) * backup::
+../tar_texi/tar.texi(,200) * Applications::
+../tar_texi/tar.texi(,201) * looking ahead::
+../tar_texi/tar.texi(,202)
+../tar_texi/tar.texi(GNUTAR,203) Advanced @acronym{GNU} @command{tar}
Operations
+../tar_texi/tar.texi(,204)
+../tar_texi/tar.texi(,205) * Operations::
+../tar_texi/tar.texi(,206) * append::
+../tar_texi/tar.texi(,207) * update::
+../tar_texi/tar.texi(,208) * concatenate::
+../tar_texi/tar.texi(,209) * delete::
+../tar_texi/tar.texi(,210) * compare::
+../tar_texi/tar.texi(,211)
+../tar_texi/tar.texi(,212) How to Add Files to Existing Archives:
@option{--append}
+../tar_texi/tar.texi(,213)
+../tar_texi/tar.texi(,214) * appending files:: Appending Files to
an Archive
+../tar_texi/tar.texi(,215) * multiple::
+../tar_texi/tar.texi(,216)
+../tar_texi/tar.texi(,217) Updating an Archive
+../tar_texi/tar.texi(,218)
+../tar_texi/tar.texi(,219) * how to update::
+../tar_texi/tar.texi(,220)
+../tar_texi/tar.texi(,221) Options Used by @option{--create}
+../tar_texi/tar.texi(,222)
+../tar_texi/tar.texi(,223) * override:: Overriding File
Metadata.
+../tar_texi/tar.texi(,224) * Ignore Failed Read::
+../tar_texi/tar.texi(,225)
+../tar_texi/tar.texi(,226) Options Used by @option{--extract}
+../tar_texi/tar.texi(,227)
+../tar_texi/tar.texi(,228) * Reading:: Options to Help
Read Archives
+../tar_texi/tar.texi(,229) * Writing:: Changing How
@command{tar} Writes Files
+../tar_texi/tar.texi(,230) * Scarce:: Coping with Scarce
Resources
+../tar_texi/tar.texi(,231)
+../tar_texi/tar.texi(,232) Options to Help Read Archives
+../tar_texi/tar.texi(,233)
+../tar_texi/tar.texi(,234) * read full records::
+../tar_texi/tar.texi(,235) * Ignore Zeros::
+../tar_texi/tar.texi(,236)
+../tar_texi/tar.texi(,237) Changing How @command{tar} Writes Files
+../tar_texi/tar.texi(,238)
+../tar_texi/tar.texi(,239) * Dealing with Old Files::
+../tar_texi/tar.texi(,240) * Overwrite Old Files::
+../tar_texi/tar.texi(,241) * Keep Old Files::
+../tar_texi/tar.texi(,242) * Keep Newer Files::
+../tar_texi/tar.texi(,243) * Unlink First::
+../tar_texi/tar.texi(,244) * Recursive Unlink::
+../tar_texi/tar.texi(,245) * Data Modification Times::
+../tar_texi/tar.texi(,246) * Setting Access Permissions::
+../tar_texi/tar.texi(,247) * Directory Modification Times and Permissions::
+../tar_texi/tar.texi(,248) * Writing to Standard Output::
+../tar_texi/tar.texi(,249) * Writing to an External Program::
+../tar_texi/tar.texi(,250) * remove files::
+../tar_texi/tar.texi(,251)
+../tar_texi/tar.texi(,252) Coping with Scarce Resources
+../tar_texi/tar.texi(,253)
+../tar_texi/tar.texi(,254) * Starting File::
+../tar_texi/tar.texi(,255) * Same Order::
+../tar_texi/tar.texi(,256)
+../tar_texi/tar.texi(,257) Performing Backups and Restoring Files
+../tar_texi/tar.texi(,258)
+../tar_texi/tar.texi(,259) * Full Dumps:: Using @command{tar}
to Perform Full Dumps
+../tar_texi/tar.texi(,260) * Incremental Dumps:: Using @command{tar}
to Perform Incremental Dumps
+../tar_texi/tar.texi(,261) * Backup Levels:: Levels of Backups
+../tar_texi/tar.texi(,262) * Backup Parameters:: Setting Parameters
for Backups and Restoration
+../tar_texi/tar.texi(,263) * Scripted Backups:: Using the Backup
Scripts
+../tar_texi/tar.texi(,264) * Scripted Restoration:: Using the Restore
Script
+../tar_texi/tar.texi(,265)
+../tar_texi/tar.texi(,266) Setting Parameters for Backups and Restoration
+../tar_texi/tar.texi(,267)
+../tar_texi/tar.texi(,268) * General-Purpose Variables::
+../tar_texi/tar.texi(,269) * Magnetic Tape Control::
+../tar_texi/tar.texi(,270) * User Hooks::
+../tar_texi/tar.texi(,271) * backup-specs example:: An Example Text of
@file{Backup-specs}
+../tar_texi/tar.texi(,272)
+../tar_texi/tar.texi(,273) Choosing Files and Names for @command{tar}
+../tar_texi/tar.texi(,274)
+../tar_texi/tar.texi(,275) * file:: Choosing the
Archive's Name
+../tar_texi/tar.texi(,276) * Selecting Archive Members::
+../tar_texi/tar.texi(,277) * files:: Reading Names from
a File
+../tar_texi/tar.texi(,278) * exclude:: Excluding Some Files
+../tar_texi/tar.texi(,279) * wildcards:: Wildcards Patterns
and Matching
+../tar_texi/tar.texi(,280) * quoting styles:: Ways of Quoting
Special Characters in Names
+../tar_texi/tar.texi(,281) * transform:: Modifying File and
Member Names
+../tar_texi/tar.texi(,282) * after:: Operating Only on
New Files
+../tar_texi/tar.texi(,283) * recurse:: Descending into
Directories
+../tar_texi/tar.texi(,284) * one:: Crossing File
System Boundaries
+../tar_texi/tar.texi(,285)
+../tar_texi/tar.texi(,286) Reading Names from a File
+../tar_texi/tar.texi(,287)
+../tar_texi/tar.texi(,288) * nul::
+../tar_texi/tar.texi(,289)
+../tar_texi/tar.texi(,290) Excluding Some Files
+../tar_texi/tar.texi(,291)
+../tar_texi/tar.texi(,292) * problems with exclude::
+../tar_texi/tar.texi(,293)
+../tar_texi/tar.texi(,294) Wildcards Patterns and Matching
+../tar_texi/tar.texi(,295)
+../tar_texi/tar.texi(,296) * controlling pattern-matching::
+../tar_texi/tar.texi(,297)
+../tar_texi/tar.texi(,298) Crossing File System Boundaries
+../tar_texi/tar.texi(,299)
+../tar_texi/tar.texi(,300) * directory:: Changing Directory
+../tar_texi/tar.texi(,301) * absolute:: Absolute File Names
+../tar_texi/tar.texi(,302)
+../tar_texi/tar.texi(,303) Date input formats
+../tar_texi/tar.texi(,304)
+../tar_texi/tar.texi(,305) * General date syntax:: Common rules.
+../tar_texi/tar.texi(,306) * Calendar date items:: 19 Dec 1994.
+../tar_texi/tar.texi(,307) * Time of day items:: 9:20pm.
+../tar_texi/tar.texi(,308) * Time zone items:: @sc{est},
@sc{pdt}, @sc{gmt}.
+../tar_texi/tar.texi(,309) * Day of week items:: Monday and
others.
+../tar_texi/tar.texi(,310) * Relative items in date strings:: next tuesday, 2
years ago.
+../tar_texi/tar.texi(,311) * Pure numbers in date strings:: 19931219, 1440.
+../tar_texi/tar.texi(,312) * Seconds since the Epoch:: @@1078100502.
+../tar_texi/tar.texi(,313) * Specifying time zone rules::
TZ="America/New_York", TZ="UTC0".
+../tar_texi/tar.texi(,314) * Authors of get_date:: Bellovin,
Eggert, Salz, Berets, et al.
+../tar_texi/tar.texi(,315)
+../tar_texi/tar.texi(,316) Controlling the Archive Format
+../tar_texi/tar.texi(,317)
+../tar_texi/tar.texi(,318) * Portability:: Making
@command{tar} Archives More Portable
+../tar_texi/tar.texi(,319) * Compression:: Using Less Space
through Compression
+../tar_texi/tar.texi(,320) * Attributes:: Handling File
Attributes
+../tar_texi/tar.texi(,321) * cpio:: Comparison of
@command{tar} and @command{cpio}
+../tar_texi/tar.texi(,322)
+../tar_texi/tar.texi(,323) Making @command{tar} Archives More Portable
+../tar_texi/tar.texi(,324)
+../tar_texi/tar.texi(,325) * Portable Names:: Portable Names
+../tar_texi/tar.texi(,326) * dereference:: Symbolic Links
+../tar_texi/tar.texi(,327) * old:: Old V7 Archives
+../tar_texi/tar.texi(,328) * ustar:: Ustar Archives
+../tar_texi/tar.texi(,329) * gnu:: GNU and old GNU
format archives.
+../tar_texi/tar.texi(,330) * posix:: @acronym{POSIX}
archives
+../tar_texi/tar.texi(,331) * Checksumming:: Checksumming
Problems
+../tar_texi/tar.texi(,332) * Large or Negative Values:: Large files,
negative time stamps, etc.
+../tar_texi/tar.texi(,333) * Other Tars:: How to Extract
GNU-Specific Data Using
+../tar_texi/tar.texi(,334) Other @command{tar}
Implementations
+../tar_texi/tar.texi(,335)
+../tar_texi/tar.texi(GNUTAR,336) @acronym{GNU} @command{tar} and
@acronym{POSIX} @command{tar}
+../tar_texi/tar.texi(,337)
+../tar_texi/tar.texi(,338) * PAX keywords:: Controlling Extended Header
Keywords.
+../tar_texi/tar.texi(,339)
+../tar_texi/tar.texi(,340) How to Extract GNU-Specific Data Using Other
@command{tar} Implementations
+../tar_texi/tar.texi(,341)
+../tar_texi/tar.texi(,342) * Split Recovery:: Members Split Between
Volumes
+../tar_texi/tar.texi(,343) * Sparse Recovery:: Sparse Members
+../tar_texi/tar.texi(,344)
+../tar_texi/tar.texi(,345) Using Less Space through Compression
+../tar_texi/tar.texi(,346)
+../tar_texi/tar.texi(,347) * gzip:: Creating and
Reading Compressed Archives
+../tar_texi/tar.texi(,348) * sparse:: Archiving Sparse
Files
+../tar_texi/tar.texi(,349)
+../tar_texi/tar.texi(,350) Tapes and Other Archive Media
+../tar_texi/tar.texi(,351)
+../tar_texi/tar.texi(,352) * Device:: Device selection
and switching
+../tar_texi/tar.texi(,353) * Remote Tape Server::
+../tar_texi/tar.texi(,354) * Common Problems and Solutions::
+../tar_texi/tar.texi(,355) * Blocking:: Blocking
+../tar_texi/tar.texi(,356) * Many:: Many archives on
one tape
+../tar_texi/tar.texi(,357) * Using Multiple Tapes:: Using Multiple Tapes
+../tar_texi/tar.texi(,358) * label:: Including a Label
in the Archive
+../tar_texi/tar.texi(,359) * verify::
+../tar_texi/tar.texi(,360) * Write Protection::
+../tar_texi/tar.texi(,361)
+../tar_texi/tar.texi(,362) Blocking
+../tar_texi/tar.texi(,363)
+../tar_texi/tar.texi(,364) * Format Variations:: Format Variations
+../tar_texi/tar.texi(,365) * Blocking Factor:: The Blocking Factor
of an Archive
+../tar_texi/tar.texi(,366)
+../tar_texi/tar.texi(,367) Many Archives on One Tape
+../tar_texi/tar.texi(,368)
+../tar_texi/tar.texi(,369) * Tape Positioning:: Tape Positions and
Tape Marks
+../tar_texi/tar.texi(,370) * mt:: The @command{mt}
Utility
+../tar_texi/tar.texi(,371)
+../tar_texi/tar.texi(,372) Using Multiple Tapes
+../tar_texi/tar.texi(,373)
+../tar_texi/tar.texi(,374) * Multi-Volume Archives:: Archives Longer
than One Tape or Disk
+../tar_texi/tar.texi(,375) * Tape Files:: Tape Files
+../tar_texi/tar.texi(,376) * Tarcat:: Concatenate Volumes
into a Single Archive
+../tar_texi/tar.texi(,377)
+../tar_texi/tar.texi(,378)
+../tar_texi/tar.texi(,379) Tar Internals
+../tar_texi/tar.texi(,380)
+../tar_texi/tar.texi(,381) * Standard:: Basic Tar Format
+../tar_texi/tar.texi(,382) * Extensions:: @acronym{GNU} Extensions to
the Archive Format
+../tar_texi/tar.texi(,383) * Sparse Formats:: Storing Sparse Files
+../tar_texi/tar.texi(,384) * Snapshot Files::
+../tar_texi/tar.texi(,385) * Dumpdir::
+../tar_texi/tar.texi(,386)
+../tar_texi/tar.texi(,387) Storing Sparse Files
+../tar_texi/tar.texi(,388)
+../tar_texi/tar.texi(,389) * Old GNU Format::
+../tar_texi/tar.texi(,390) * PAX 0:: PAX Format, Versions 0.0
and 0.1
+../tar_texi/tar.texi(,391) * PAX 1:: PAX Format, Version 1.0
+../tar_texi/tar.texi(,392)
+../tar_texi/tar.texi(,393) Genfile
+../tar_texi/tar.texi(,394)
+../tar_texi/tar.texi(,395) * Generate Mode:: File Generation Mode.
+../tar_texi/tar.texi(,396) * Status Mode:: File Status Mode.
+../tar_texi/tar.texi(,397) * Exec Mode:: Synchronous Execution mode.
+../tar_texi/tar.texi(,398)
+../tar_texi/tar.texi(,399) Copying This Manual
+../tar_texi/tar.texi(,400)
+../tar_texi/tar.texi(,401) * GNU Free Documentation License:: License for
copying this manual
+../tar_texi/tar.texi(,402)
+../tar_texi/tar.texi(,403) @end detailmenu
+../tar_texi/tar.texi(,404) @end menu
+../tar_texi/tar.texi(,405)
+../tar_texi/tar.texi(,406) @node Introduction
+../tar_texi/tar.texi(,407) @chapter Introduction
+../tar_texi/tar.texi(,408)
+../tar_texi/tar.texi(GNUTAR,409) @acronym{GNU} @command{tar} creates
+../tar_texi/tar.texi(,410) and manipulates @dfn{archives} which are actually
collections of
+../tar_texi/tar.texi(,411) many other files; the program provides users with
an organized and
+../tar_texi/tar.texi(,412) systematic method for controlling a large amount of
data.
+../tar_texi/tar.texi(,413) The name ``tar'' originally came from the phrase
``Tape ARchive'', but
+../tar_texi/tar.texi(,414) archives need not (and these days, typically do
not) reside on tapes.
+../tar_texi/tar.texi(,415)
+../tar_texi/tar.texi(,416) @menu
+../tar_texi/tar.texi(,417) * Book Contents:: What this Book
Contains
+../tar_texi/tar.texi(,418) * Definitions:: Some Definitions
+../tar_texi/tar.texi(,419) * What tar Does:: What @command{tar}
Does
+../tar_texi/tar.texi(,420) * Naming tar Archives:: How @command{tar}
Archives are Named
+../tar_texi/tar.texi(GNUTAR,421) * Authors:: @acronym{GNU}
@command{tar} Authors
+../tar_texi/tar.texi(,422) * Reports:: Reporting bugs or
suggestions
+../tar_texi/tar.texi(,423) @end menu
+../tar_texi/tar.texi(,424)
+../tar_texi/tar.texi(,425) @node Book Contents
+../tar_texi/tar.texi(,426) @section What this Book Contains
+../tar_texi/tar.texi(,427)
+../tar_texi/tar.texi(,428) The first part of this chapter introduces you to
various terms that will
+../tar_texi/tar.texi(GNUTAR,429) recur throughout the book. It also tells you
who has worked on @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,430) and its documentation, and where you should send
bug reports
+../tar_texi/tar.texi(,431) or comments.
+../tar_texi/tar.texi(,432)
+../tar_texi/tar.texi(,433) The second chapter is a tutorial (@pxref{Tutorial})
which provides a
+../tar_texi/tar.texi(,434) gentle introduction for people who are new to using
@command{tar}. It is
+../tar_texi/tar.texi(,435) meant to be self contained, not requiring any
reading from subsequent
+../tar_texi/tar.texi(,436) chapters to make sense. It moves from topic to
topic in a logical,
+../tar_texi/tar.texi(,437) progressive order, building on information already
explained.
+../tar_texi/tar.texi(,438)
+../tar_texi/tar.texi(,439) Although the tutorial is paced and structured to
allow beginners to
+../tar_texi/tar.texi(,440) learn how to use @command{tar}, it is not intended
solely for beginners.
+../tar_texi/tar.texi(,441) The tutorial explains how to use the three most
frequently used
+../tar_texi/tar.texi(,442) operations (@samp{create}, @samp{list}, and
@samp{extract}) as well as
+../tar_texi/tar.texi(,443) two frequently used options (@samp{file} and
@samp{verbose}). The other
+../tar_texi/tar.texi(,444) chapters do not refer to the tutorial frequently;
however, if a section
+../tar_texi/tar.texi(,445) discusses something which is a complex variant of a
basic concept, there
+../tar_texi/tar.texi(,446) may be a cross reference to that basic concept.
(The entire book,
+../tar_texi/tar.texi(,447) including the tutorial, assumes that the reader
understands some basic
+../tar_texi/tar.texi(,448) concepts of using a Unix-type operating system;
@pxref{Tutorial}.)
+../tar_texi/tar.texi(,449)
+../tar_texi/tar.texi(,450) The third chapter presents the remaining five
operations, and
+../tar_texi/tar.texi(,451) information about using @command{tar} options and
option syntax.
+../tar_texi/tar.texi(,452)
+../tar_texi/tar.texi(FIXME,455) @allow-recursion
+../tar_texi/tar.texi(FIXME,455) @quote-arg
+../tar_texi/tar.texi(FIXME,455) The other chapters are meant to be used as a
+../tar_texi/tar.texi(,456) reference. Each chapter presents everything that
needs to be said
+../tar_texi/tar.texi(,457) about a specific topic.
+../tar_texi/tar.texi(,458)
+../tar_texi/tar.texi(,459) One of the chapters (@pxref{Date input formats})
exists in its
+../tar_texi/tar.texi(,460) entirety in other @acronym{GNU} manuals, and is
mostly self-contained.
+../tar_texi/tar.texi(,461) In addition, one section of this manual
(@pxref{Standard}) contains a
+../tar_texi/tar.texi(,462) big quote which is taken directly from
@command{tar} sources.
+../tar_texi/tar.texi(,463)
+../tar_texi/tar.texi(,464) In general, we give both long and short
(abbreviated) option names
+../tar_texi/tar.texi(,465) at least once in each section where the relevant
option is covered, so
+../tar_texi/tar.texi(,466) that novice readers will become familiar with both
styles. (A few
+../tar_texi/tar.texi(,467) options have no short versions, and the relevant
sections will
+../tar_texi/tar.texi(,468) indicate this.)
+../tar_texi/tar.texi(,469)
+../tar_texi/tar.texi(,470) @node Definitions
+../tar_texi/tar.texi(,471) @section Some Definitions
+../tar_texi/tar.texi(,472)
+../tar_texi/tar.texi(,473) @cindex archive
+../tar_texi/tar.texi(,474) @cindex tar archive
+../tar_texi/tar.texi(,475) The @command{tar} program is used to create and
manipulate @command{tar}
+../tar_texi/tar.texi(,476) archives. An @dfn{archive} is a single file which
contains the contents
+../tar_texi/tar.texi(,477) of many files, while still identifying the names of
the files, their
+../tar_texi/tar.texi(,478) owner(s), and so forth. (In addition, archives
record access
+../tar_texi/tar.texi(,479) permissions, user and group, size in bytes, and
data modification time.
+../tar_texi/tar.texi(,480) Some archives also record the file names in each
archived directory, as
+../tar_texi/tar.texi(,481) well as other file and directory information.) You
can use @command{tar}
+../tar_texi/tar.texi(,482) to @dfn{create} a new archive in a specified
directory.
+../tar_texi/tar.texi(,483)
+../tar_texi/tar.texi(,484) @cindex member
+../tar_texi/tar.texi(,485) @cindex archive member
+../tar_texi/tar.texi(,486) @cindex file name
+../tar_texi/tar.texi(,487) @cindex member name
+../tar_texi/tar.texi(,488) The files inside an archive are called
@dfn{members}. Within this
+../tar_texi/tar.texi(,489) manual, we use the term @dfn{file} to refer only to
files accessible in
+../tar_texi/tar.texi(,490) the normal ways (by @command{ls}, @command{cat},
and so forth), and the term
+../tar_texi/tar.texi(,491) @dfn{member} to refer only to the members of an
archive. Similarly, a
+../tar_texi/tar.texi(,492) @dfn{file name} is the name of a file, as it
resides in the file system,
+../tar_texi/tar.texi(,493) and a @dfn{member name} is the name of an archive
member within the
+../tar_texi/tar.texi(,494) archive.
+../tar_texi/tar.texi(,495)
+../tar_texi/tar.texi(,496) @cindex extraction
+../tar_texi/tar.texi(,497) @cindex unpacking
+../tar_texi/tar.texi(,498) The term @dfn{extraction} refers to the process of
copying an archive
+../tar_texi/tar.texi(,499) member (or multiple members) into a file in the
file system. Extracting
+../tar_texi/tar.texi(,500) all the members of an archive is often called
@dfn{extracting the
+../tar_texi/tar.texi(,501) archive}. The term @dfn{unpack} can also be used
to refer to the
+../tar_texi/tar.texi(,502) extraction of many or all the members of an
archive. Extracting an
+../tar_texi/tar.texi(,503) archive does not destroy the archive's structure,
just as creating an
+../tar_texi/tar.texi(,504) archive does not destroy the copies of the files
that exist outside of
+../tar_texi/tar.texi(,505) the archive. You may also @dfn{list} the members
in a given archive
+../tar_texi/tar.texi(,506) (this is often thought of as ``printing'' them to
the standard output,
+../tar_texi/tar.texi(,507) or the command line), or @dfn{append} members to a
pre-existing archive.
+../tar_texi/tar.texi(,508) All of these operations can be performed using
@command{tar}.
+../tar_texi/tar.texi(,509)
+../tar_texi/tar.texi(,510) @node What tar Does
+../tar_texi/tar.texi(,511) @section What @command{tar} Does
+../tar_texi/tar.texi(,512)
+../tar_texi/tar.texi(,513) @cindex tar
+../tar_texi/tar.texi(,514) The @command{tar} program provides the ability to
create @command{tar}
+../tar_texi/tar.texi(,515) archives, as well as various other kinds of
manipulation. For example,
+../tar_texi/tar.texi(,516) you can use @command{tar} on previously created
archives to extract files,
+../tar_texi/tar.texi(,517) to store additional files, or to update or list
files which were already
+../tar_texi/tar.texi(,518) stored.
+../tar_texi/tar.texi(,519)
+../tar_texi/tar.texi(,520) Initially, @command{tar} archives were used to
store files conveniently on
+../tar_texi/tar.texi(,521) magnetic tape. The name @command{tar} comes from
this use; it stands for
+../tar_texi/tar.texi(,522) @code{t}ape @code{ar}chiver. Despite the utility's
name, @command{tar} can
+../tar_texi/tar.texi(,523) direct its output to available devices, files, or
other programs (using
+../tar_texi/tar.texi(,524) pipes). @command{tar} may even access remote
devices or files (as archives).
+../tar_texi/tar.texi(,525)
+../tar_texi/tar.texi(,526) You can use @command{tar} archives in many ways.
We want to stress a few
+../tar_texi/tar.texi(,527) of them: storage, backup, and transportation.
+../tar_texi/tar.texi(,528)
+../tar_texi/tar.texi(FIXME,529) @allow-recursion
+../tar_texi/tar.texi(FIXME,529) @quote-arg
+../tar_texi/tar.texi(FIXME,529)
+../tar_texi/tar.texi(,530) @table @asis
+../tar_texi/tar.texi(,531) @item Storage
+../tar_texi/tar.texi(,532) Often, @command{tar} archives are used to store
related files for
+../tar_texi/tar.texi(,533) convenient file transfer over a network. For
example, the
+../tar_texi/tar.texi(,534) @acronym{GNU} Project distributes its software
bundled into
+../tar_texi/tar.texi(,535) @command{tar} archives, so that all the files
relating to a particular
+../tar_texi/tar.texi(,536) program (or set of related programs) can be
transferred as a single
+../tar_texi/tar.texi(,537) unit.
+../tar_texi/tar.texi(,538)
+../tar_texi/tar.texi(,539) A magnetic tape can store several files in
sequence. However, the tape
+../tar_texi/tar.texi(,540) has no names for these files; it only knows their
relative position on
+../tar_texi/tar.texi(,541) the tape. One way to store several files on one
tape and retain their
+../tar_texi/tar.texi(,542) names is by creating a @command{tar} archive. Even
when the basic transfer
+../tar_texi/tar.texi(,543) mechanism can keep track of names, as FTP can, the
nuisance of handling
+../tar_texi/tar.texi(,544) multiple files, directories, and multiple links
makes @command{tar}
+../tar_texi/tar.texi(,545) archives useful.
+../tar_texi/tar.texi(,546)
+../tar_texi/tar.texi(,547) Archive files are also used for long-term storage.
You can think of
+../tar_texi/tar.texi(,548) this as transportation from the present into the
future. (It is a
+../tar_texi/tar.texi(,549) science-fiction idiom that you can move through
time as well as in
+../tar_texi/tar.texi(,550) space; the idea here is that @command{tar} can be
used to move archives in
+../tar_texi/tar.texi(,551) all dimensions, even time!)
+../tar_texi/tar.texi(,552)
+../tar_texi/tar.texi(,553) @item Backup
+../tar_texi/tar.texi(,554) Because the archive created by @command{tar} is
capable of preserving
+../tar_texi/tar.texi(,555) file information and directory structure,
@command{tar} is commonly
+../tar_texi/tar.texi(,556) used for performing full and incremental backups of
disks. A backup
+../tar_texi/tar.texi(,557) puts a collection of files (possibly pertaining to
many users and
+../tar_texi/tar.texi(,558) projects) together on a disk or a tape. This
guards against
+../tar_texi/tar.texi(,559) accidental destruction of the information in those
files.
+../tar_texi/tar.texi(GNUTAR,560) @acronym{GNU} @command{tar} has special
features that allow it to be
+../tar_texi/tar.texi(,561) used to make incremental and full dumps of all the
files in a
+../tar_texi/tar.texi(,562) file system.
+../tar_texi/tar.texi(,563)
+../tar_texi/tar.texi(,564) @item Transportation
+../tar_texi/tar.texi(,565) You can create an archive on one system, transfer
it to another system,
+../tar_texi/tar.texi(,566) and extract the contents there. This allows you to
transport a group of
+../tar_texi/tar.texi(,567) files from one system to another.
+../tar_texi/tar.texi(,568) @end table
+../tar_texi/tar.texi(,569)
+../tar_texi/tar.texi(,570) @node Naming tar Archives
+../tar_texi/tar.texi(,571) @section How @command{tar} Archives are Named
+../tar_texi/tar.texi(,572)
+../tar_texi/tar.texi(,573) Conventionally, @command{tar} archives are given
names ending with
+../tar_texi/tar.texi(,574) @samp{.tar}. This is not necessary for
@command{tar} to operate properly,
+../tar_texi/tar.texi(,575) but this manual follows that convention in order to
accustom readers to
+../tar_texi/tar.texi(,576) it and to make examples more clear.
+../tar_texi/tar.texi(,577)
+../tar_texi/tar.texi(,578) @cindex tar file
+../tar_texi/tar.texi(,579) @cindex entry
+../tar_texi/tar.texi(,580) @cindex tar entry
+../tar_texi/tar.texi(,581) Often, people refer to @command{tar} archives as
address@hidden files,'' and
+../tar_texi/tar.texi(,582) archive members as ``files'' or ``entries''. For
people familiar with
+../tar_texi/tar.texi(,583) the operation of @command{tar}, this causes no
difficulty. However, in
+../tar_texi/tar.texi(,584) this manual, we consistently refer to ``archives''
and ``archive
+../tar_texi/tar.texi(,585) members'' to make learning to use @command{tar}
easier for novice users.
+../tar_texi/tar.texi(,586)
+../tar_texi/tar.texi(,587) @node Authors
+../tar_texi/tar.texi(GNUTAR,588) @section @acronym{GNU} @command{tar} Authors
+../tar_texi/tar.texi(,589)
+../tar_texi/tar.texi(GNUTAR,590) @acronym{GNU} @command{tar} was originally
written by John Gilmore,
+../tar_texi/tar.texi(,591) and modified by many people. The @acronym{GNU}
enhancements were
+../tar_texi/tar.texi(,592) written by Jay Fenlason, then Joy Kendall, and the
whole package has
+../tar_texi/tar.texi(,593) been further maintained by Thomas Bushnell, n/BSG,
address@hidden
+../tar_texi/tar.texi(,594) Pinard, Paul Eggert, and finally Sergey Poznyakoff
with the help of
+../tar_texi/tar.texi(,595) numerous and kind users.
+../tar_texi/tar.texi(,596)
+../tar_texi/tar.texi(,597) We wish to stress that @command{tar} is a
collective work, and owes much to
+../tar_texi/tar.texi(,598) all those people who reported problems, offered
solutions and other
+../tar_texi/tar.texi(,599) insights, or shared their thoughts and suggestions.
An impressive, yet
+../tar_texi/tar.texi(,600) partial list of those contributors can be found in
the @file{THANKS}
+../tar_texi/tar.texi(GNUTAR,601) file from the @acronym{GNU} @command{tar}
distribution.
+../tar_texi/tar.texi(,602)
+../tar_texi/tar.texi(FIXME,606) @allow-recursion
+../tar_texi/tar.texi(FIXME,606) @quote-arg
+../tar_texi/tar.texi(FIXME,606)
+../tar_texi/tar.texi(,607)
+../tar_texi/tar.texi(FIXME,609) @allow-recursion
+../tar_texi/tar.texi(FIXME,609) @quote-arg
+../tar_texi/tar.texi(FIXME,609)
+../tar_texi/tar.texi(,610)
+../tar_texi/tar.texi(GNUTAR,611) Jay Fenlason put together a draft of a
@acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,612) manual, borrowing notes from the original man page
from John Gilmore.
+../tar_texi/tar.texi(,613) This was withdrawn in version 1.11. Thomas
Bushnell, n/BSG and Amy
+../tar_texi/tar.texi(GNUTAR,614) Gorin worked on a tutorial and manual for
@acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,615) address@hidden Pinard put version 1.11.8 of the
manual together by
+../tar_texi/tar.texi(,616) taking information from all these sources and
merging them. Melissa
+../tar_texi/tar.texi(,617) Weisshaus finally edited and redesigned the book to
create version
+../tar_texi/tar.texi(,618) 1.12. The book for versions from 1.14 up to
1.15.92 were edited
+../tar_texi/tar.texi(,619) by the current maintainer, Sergey Poznyakoff.
+../tar_texi/tar.texi(,620)
+../tar_texi/tar.texi(,621) For version 1.12, Daniel Hagerty contributed a
great deal of technical
+../tar_texi/tar.texi(,622) consulting. In particular, he is the primary
author of @ref{Backups}.
+../tar_texi/tar.texi(,623)
+../tar_texi/tar.texi(GNUTAR,624) In July, 2003 @acronym{GNU} @command{tar} was
put on CVS at savannah.gnu.org
+../tar_texi/tar.texi(,625) (see @url{http://savannah.gnu.org/projects/tar}),
and
+../tar_texi/tar.texi(,626) active development and maintenance work has started
+../tar_texi/tar.texi(GNUTAR,627) again. Currently @acronym{GNU} @command{tar}
is being maintained by Paul Eggert, Sergey
+../tar_texi/tar.texi(,628) Poznyakoff and Jeff Bailey.
+../tar_texi/tar.texi(,629)
+../tar_texi/tar.texi(,630) Support for @acronym{POSIX} archives was added by
Sergey Poznyakoff.
+../tar_texi/tar.texi(,631)
+../tar_texi/tar.texi(,632) @node Reports
+../tar_texi/tar.texi(,633) @section Reporting bugs or suggestions
+../tar_texi/tar.texi(,634)
+../tar_texi/tar.texi(,635) @cindex bug reports
+../tar_texi/tar.texi(,636) @cindex reporting bugs
+../tar_texi/tar.texi(,637) If you find problems or have suggestions about this
program or manual,
+../tar_texi/tar.texi(,638) please report them to @file{bug-tar@@gnu.org}.
+../tar_texi/tar.texi(,639)
+../tar_texi/tar.texi(,640) When reporting a bug, please be sure to include as
much detail as
+../tar_texi/tar.texi(FIXME,643) possible, in order to reproduce it.
@allow-recursion
+../tar_texi/tar.texi(FIXME,643) @quote-arg
+../tar_texi/tar.texi(FIXME,643) .
+../tar_texi/tar.texi(,644)
+../tar_texi/tar.texi(,645) @node Tutorial
+../tar_texi/tar.texi(,646) @chapter Tutorial Introduction to @command{tar}
+../tar_texi/tar.texi(,647)
+../tar_texi/tar.texi(,648) This chapter guides you through some basic examples
of three @command{tar}
+../tar_texi/tar.texi(,649) operations: @option{--create}, @option{--list}, and
@option{--extract}. If
+../tar_texi/tar.texi(,650) you already know how to use some other version of
@command{tar}, then you
+../tar_texi/tar.texi(,651) may not need to read this chapter. This chapter
omits most complicated
+../tar_texi/tar.texi(,652) details about how @command{tar} works.
+../tar_texi/tar.texi(,653)
+../tar_texi/tar.texi(,654) @menu
+../tar_texi/tar.texi(,655) * assumptions::
+../tar_texi/tar.texi(,656) * stylistic conventions::
+../tar_texi/tar.texi(,657) * basic tar options:: Basic @command{tar}
Operations and Options
+../tar_texi/tar.texi(,658) * frequent operations::
+../tar_texi/tar.texi(,659) * Two Frequent Options::
+../tar_texi/tar.texi(,660) * create:: How to Create
Archives
+../tar_texi/tar.texi(,661) * list:: How to List Archives
+../tar_texi/tar.texi(,662) * extract:: How to Extract
Members from an Archive
+../tar_texi/tar.texi(,663) * going further::
+../tar_texi/tar.texi(,664) @end menu
+../tar_texi/tar.texi(,665)
+../tar_texi/tar.texi(,666) @node assumptions
+../tar_texi/tar.texi(,667) @section Assumptions this Tutorial Makes
+../tar_texi/tar.texi(,668)
+../tar_texi/tar.texi(,669) This chapter is paced to allow beginners to learn
about @command{tar}
+../tar_texi/tar.texi(,670) slowly. At the same time, we will try to cover all
the basic aspects of
+../tar_texi/tar.texi(,671) these three operations. In order to accomplish
both of these tasks, we
+../tar_texi/tar.texi(,672) have made certain assumptions about your knowledge
before reading this
+../tar_texi/tar.texi(,673) manual, and the hardware you will be using:
+../tar_texi/tar.texi(,674)
+../tar_texi/tar.texi(,675) @itemize @bullet
+../tar_texi/tar.texi(,676) @item
+../tar_texi/tar.texi(,677) Before you start to work through this tutorial, you
should understand
+../tar_texi/tar.texi(,678) what the terms ``archive'' and ``archive member''
mean
+../tar_texi/tar.texi(,679) (@pxref{Definitions}). In addition, you should
understand something
+../tar_texi/tar.texi(,680) about how Unix-type operating systems work, and you
should know how to
+../tar_texi/tar.texi(,681) use some basic utilities. For example, you should
know how to create,
+../tar_texi/tar.texi(,682) list, copy, rename, edit, and delete files and
directories; how to
+../tar_texi/tar.texi(,683) change between directories; and how to figure out
where you are in the
+../tar_texi/tar.texi(,684) file system. You should have some basic
understanding of directory
+../tar_texi/tar.texi(,685) structure and how files are named according to
which directory they are
+../tar_texi/tar.texi(,686) in. You should understand concepts such as
standard output and standard
+../tar_texi/tar.texi(,687) input, what various definitions of the term
``argument'' mean, and the
+../tar_texi/tar.texi(FIXME,689) differences between relative and absolute path
names. @allow-recursion
+../tar_texi/tar.texi(FIXME,689) @quote-arg
+../tar_texi/tar.texi(FIXME,689)
+../tar_texi/tar.texi(,690)
+../tar_texi/tar.texi(,691) @item
+../tar_texi/tar.texi(,692) This manual assumes that you are working from your
own home directory
+../tar_texi/tar.texi(,693) (unless we state otherwise). In this tutorial, you
will create a
+../tar_texi/tar.texi(,694) directory to practice @command{tar} commands in.
When we show path names,
+../tar_texi/tar.texi(,695) we will assume that those paths are relative to
your home directory.
+../tar_texi/tar.texi(,696) For example, my home directory path is
@file{/home/fsf/melissa}. All of
+../tar_texi/tar.texi(,697) my examples are in a subdirectory of the directory
named by that path
+../tar_texi/tar.texi(,698) name; the subdirectory is called @file{practice}.
+../tar_texi/tar.texi(,699)
+../tar_texi/tar.texi(,700) @item
+../tar_texi/tar.texi(,701) In general, we show examples of archives which
exist on (or can be
+../tar_texi/tar.texi(,702) written to, or worked with from) a directory on a
hard disk. In most
+../tar_texi/tar.texi(,703) cases, you could write those archives to, or work
with them on any other
+../tar_texi/tar.texi(,704) device, such as a tape drive. However, some of the
later examples in
+../tar_texi/tar.texi(,705) the tutorial and next chapter will not work on tape
drives.
+../tar_texi/tar.texi(,706) Additionally, working with tapes is much more
complicated than working
+../tar_texi/tar.texi(,707) with hard disks. For these reasons, the tutorial
does not cover working
+../tar_texi/tar.texi(,708) with tape drives. @xref{Media}, for complete
information on using
+../tar_texi/tar.texi(,709) @command{tar} archives with tape drives.
+../tar_texi/tar.texi(,710)
+../tar_texi/tar.texi(FIXME,711) @allow-recursion
+../tar_texi/tar.texi(FIXME,711) @quote-arg
+../tar_texi/tar.texi(FIXME,711)
+../tar_texi/tar.texi(,712) @end itemize
+../tar_texi/tar.texi(,713)
+../tar_texi/tar.texi(,714) @node stylistic conventions
+../tar_texi/tar.texi(,715) @section Stylistic Conventions
+../tar_texi/tar.texi(,716)
+../tar_texi/tar.texi(,717) In the examples, @samp{$} represents a typical
shell prompt. It
+../tar_texi/tar.texi(,718) precedes lines you should type; to make this more
clear, those lines are
+../tar_texi/tar.texi(,719) shown in @kbd{this font}, as opposed to lines which
represent the
+../tar_texi/tar.texi(,720) computer's response; those lines are shown in
@code{this font}, or
+../tar_texi/tar.texi(,721) sometimes @samp{like this}.
+../tar_texi/tar.texi(,722)
+../tar_texi/tar.texi(,723) @c When we have lines which are too long to be
+../tar_texi/tar.texi(,724) @c displayed in any other way, we will show them
like this:
+../tar_texi/tar.texi(,725)
+../tar_texi/tar.texi(,726) @node basic tar options
+../tar_texi/tar.texi(,727) @section Basic @command{tar} Operations and Options
+../tar_texi/tar.texi(,728)
+../tar_texi/tar.texi(,729) @command{tar} can take a wide variety of arguments
which specify and define
+../tar_texi/tar.texi(,730) the actions it will have on the particular set of
files or the archive.
+../tar_texi/tar.texi(,731) The main types of arguments to @command{tar} fall
into one of two classes:
+../tar_texi/tar.texi(,732) operations, and options.
+../tar_texi/tar.texi(,733)
+../tar_texi/tar.texi(,734) Some arguments fall into a class called
@dfn{operations}; exactly one of
+../tar_texi/tar.texi(,735) these is both allowed and required for any instance
of using @command{tar};
+../tar_texi/tar.texi(,736) you may @emph{not} specify more than one. People
sometimes speak of
+../tar_texi/tar.texi(,737) @dfn{operating modes}. You are in a particular
operating mode when you
+../tar_texi/tar.texi(,738) have specified the operation which specifies it;
there are eight
+../tar_texi/tar.texi(,739) operations in total, and thus there are eight
operating modes.
+../tar_texi/tar.texi(,740)
+../tar_texi/tar.texi(,741) The other arguments fall into the class known as
@dfn{options}. You are
+../tar_texi/tar.texi(,742) not required to specify any options, and you are
allowed to specify more
+../tar_texi/tar.texi(,743) than one at a time (depending on the way you are
using @command{tar} at
+../tar_texi/tar.texi(,744) that time). Some options are used so frequently,
and are so useful for
+../tar_texi/tar.texi(,745) helping you type commands more carefully that they
are effectively
+../tar_texi/tar.texi(,746) ``required''. We will discuss them in this chapter.
+../tar_texi/tar.texi(,747)
+../tar_texi/tar.texi(,748) You can write most of the @command{tar} operations
and options in any
+../tar_texi/tar.texi(,749) of three forms: long (mnemonic) form, short form,
and old style. Some
+../tar_texi/tar.texi(,750) of the operations and options have no short or
``old'' forms; however,
+../tar_texi/tar.texi(,751) the operations and options which we will cover in
this tutorial have
+../tar_texi/tar.texi(FIXME,753) corresponding abbreviations. @allow-recursion
+../tar_texi/tar.texi(FIXME,753) @quote-arg
+../tar_texi/tar.texi(FIXME,753) We will indicate those abbreviations
appropriately to get
+../tar_texi/tar.texi(,754) you used to seeing them. (Note that the ``old
style'' option forms
+../tar_texi/tar.texi(GNUTAR,755) exist in @acronym{GNU} @command{tar} for
compatibility with Unix
+../tar_texi/tar.texi(,756) @command{tar}. In this book we present a full
discussion of this way
+../tar_texi/tar.texi(,757) of writing options and operations (@pxref{Old
Options}), and we discuss
+../tar_texi/tar.texi(,758) the other two styles of writing options (@xref{Long
Options}, and
+../tar_texi/tar.texi(,759) @pxref{Short Options}).
+../tar_texi/tar.texi(,760)
+../tar_texi/tar.texi(,761) In the examples and in the text of this tutorial,
we usually use the
+../tar_texi/tar.texi(,762) long forms of operations and options; but the
``short'' forms produce
+../tar_texi/tar.texi(,763) the same result and can make typing long
@command{tar} commands easier.
+../tar_texi/tar.texi(,764) For example, instead of typing
+../tar_texi/tar.texi(,765)
+../tar_texi/tar.texi(,766) @smallexample
+../tar_texi/tar.texi(,767) @kbd{tar --create --verbose --file=afiles.tar apple
angst aspic}
+../tar_texi/tar.texi(,768) @end smallexample
+../tar_texi/tar.texi(,769)
+../tar_texi/tar.texi(,770) @noindent
+../tar_texi/tar.texi(,771) you can type
+../tar_texi/tar.texi(,772) @smallexample
+../tar_texi/tar.texi(,773) @kbd{tar -c -v -f afiles.tar apple angst aspic}
+../tar_texi/tar.texi(,774) @end smallexample
+../tar_texi/tar.texi(,775)
+../tar_texi/tar.texi(,776) @noindent
+../tar_texi/tar.texi(,777) or even
+../tar_texi/tar.texi(,778) @smallexample
+../tar_texi/tar.texi(,779) @kbd{tar -cvf afiles.tar apple angst aspic}
+../tar_texi/tar.texi(,780) @end smallexample
+../tar_texi/tar.texi(,781)
+../tar_texi/tar.texi(,782) @noindent
+../tar_texi/tar.texi(,783) For more information on option syntax, see
@ref{Advanced tar}. In
+../tar_texi/tar.texi(,784) discussions in the text, when we name an option by
its long form, we
+../tar_texi/tar.texi(,785) also give the corresponding short option in
parentheses.
+../tar_texi/tar.texi(,786)
+../tar_texi/tar.texi(,787) The term, ``option'', can be confusing at times,
since ``operations''
+../tar_texi/tar.texi(,788) are often lumped in with the actual,
@emph{optional} ``options'' in certain
+../tar_texi/tar.texi(,789) general class statements. For example, we just
talked about ``short and
+../tar_texi/tar.texi(,790) long forms of options and operations''. However,
experienced @command{tar}
+../tar_texi/tar.texi(,791) users often refer to these by shorthand terms such
as, ``short and long
+../tar_texi/tar.texi(,792) options''. This term assumes that the
``operations'' are included, also.
+../tar_texi/tar.texi(,793) Context will help you determine which definition of
``options'' to use.
+../tar_texi/tar.texi(,794)
+../tar_texi/tar.texi(,795) Similarly, the term ``command'' can be confusing,
as it is often used in
+../tar_texi/tar.texi(,796) two different ways. People sometimes refer to
@command{tar} ``commands''.
+../tar_texi/tar.texi(,797) A @command{tar} @dfn{command} is the entire command
line of user input
+../tar_texi/tar.texi(,798) which tells @command{tar} what to do --- including
the operation, options,
+../tar_texi/tar.texi(,799) and any arguments (file names, pipes, other
commands, etc). However,
+../tar_texi/tar.texi(,800) you will also sometimes hear the term ``the
@command{tar} command''. When
+../tar_texi/tar.texi(,801) the word ``command'' is used specifically like
this, a person is usually
+../tar_texi/tar.texi(,802) referring to the @command{tar} @emph{operation},
not the whole line.
+../tar_texi/tar.texi(,803) Again, use context to figure out which of the
meanings the speaker
+../tar_texi/tar.texi(,804) intends.
+../tar_texi/tar.texi(,805)
+../tar_texi/tar.texi(,806) @node frequent operations
+../tar_texi/tar.texi(,807) @section The Three Most Frequently Used Operations
+../tar_texi/tar.texi(,808)
+../tar_texi/tar.texi(,809) Here are the three most frequently used operations
(both short and long
+../tar_texi/tar.texi(,810) forms), as well as a brief description of their
meanings. The rest of
+../tar_texi/tar.texi(,811) this chapter will cover how to use these operations
in detail. We will
+../tar_texi/tar.texi(,812) present the rest of the operations in the next
chapter.
+../tar_texi/tar.texi(,813)
+../tar_texi/tar.texi(,814) @table @option
+../tar_texi/tar.texi(,815) @item --create
+../tar_texi/tar.texi(,816) @itemx -c
+../tar_texi/tar.texi(,817) Create a new @command{tar} archive.
+../tar_texi/tar.texi(,818) @item --list
+../tar_texi/tar.texi(,819) @itemx -t
+../tar_texi/tar.texi(,820) List the contents of an archive.
+../tar_texi/tar.texi(,821) @item --extract
+../tar_texi/tar.texi(,822) @itemx -x
+../tar_texi/tar.texi(,823) Extract one or more members from an archive.
+../tar_texi/tar.texi(,824) @end table
+../tar_texi/tar.texi(,825)
+../tar_texi/tar.texi(,826) @node Two Frequent Options
+../tar_texi/tar.texi(,827) @section Two Frequently Used Options
+../tar_texi/tar.texi(,828)
+../tar_texi/tar.texi(,829) To understand how to run @command{tar} in the three
operating modes listed
+../tar_texi/tar.texi(,830) previously, you also need to understand how to use
two of the options to
+../tar_texi/tar.texi(,831) @command{tar}: @option{--file} (which takes an
archive file as an argument)
+../tar_texi/tar.texi(,832) and @option{--verbose}. (You are usually not
@emph{required} to specify
+../tar_texi/tar.texi(,833) either of these options when you run @command{tar},
but they can be very
+../tar_texi/tar.texi(,834) useful in making things more clear and helping you
avoid errors.)
+../tar_texi/tar.texi(,835)
+../tar_texi/tar.texi(,836) @menu
+../tar_texi/tar.texi(,837) * file tutorial::
+../tar_texi/tar.texi(,838) * verbose tutorial::
+../tar_texi/tar.texi(,839) * help tutorial::
+../tar_texi/tar.texi(,840) @end menu
+../tar_texi/tar.texi(,841)
+../tar_texi/tar.texi(,842) @node file tutorial
+../tar_texi/tar.texi(,843) @unnumberedsubsec The @option{--file} Option
+../tar_texi/tar.texi(,844)
+../tar_texi/tar.texi(,845) @table @option
+../tar_texi/tar.texi(xopindex,846) @opindex address@hidden, tutorial}
+../tar_texi/tar.texi(,847) @item address@hidden
+../tar_texi/tar.texi(,848) @itemx -f @var{archive-name}
+../tar_texi/tar.texi(,849) Specify the name of an archive file.
+../tar_texi/tar.texi(,850) @end table
+../tar_texi/tar.texi(,851)
+../tar_texi/tar.texi(,852) You can specify an argument for the @address@hidden
(@option{-f @var{archive-name}}) option whenever you
+../tar_texi/tar.texi(,853) use @command{tar}; this option determines the name
of the archive file
+../tar_texi/tar.texi(,854) that @command{tar} will work on.
+../tar_texi/tar.texi(,855)
+../tar_texi/tar.texi(,856) @vrindex TAPE
+../tar_texi/tar.texi(,857) If you don't specify this argument, then
@command{tar} will examine
+../tar_texi/tar.texi(,858) the environment variable @env{TAPE}. If it is set,
its value will be
+../tar_texi/tar.texi(,859) used as the archive name. Otherwise, @command{tar}
will use the
+../tar_texi/tar.texi(,860) default archive, determined at the compile time.
Usually it is
+../tar_texi/tar.texi(,861) standard output or some physical tape drive
attached to your machine
+../tar_texi/tar.texi(,862) (you can verify what the default is by running
@kbd{tar
+../tar_texi/tar.texi(,863) --show-defaults}, @pxref{defaults}). If there is
no tape drive
+../tar_texi/tar.texi(,864) attached, or the default is not meaningful, then
@command{tar} will
+../tar_texi/tar.texi(,865) print an error message. The error message might
look roughly like one
+../tar_texi/tar.texi(,866) of the following:
+../tar_texi/tar.texi(,867)
+../tar_texi/tar.texi(,868) @smallexample
+../tar_texi/tar.texi(,869) tar: can't open /dev/rmt8 : No such device or
address
+../tar_texi/tar.texi(,870) tar: can't open /dev/rsmt0 : I/O error
+../tar_texi/tar.texi(,871) @end smallexample
+../tar_texi/tar.texi(,872)
+../tar_texi/tar.texi(,873) @noindent
+../tar_texi/tar.texi(,874) To avoid confusion, we recommend that you always
specify an archive file
+../tar_texi/tar.texi(,875) name by using @address@hidden (@option{-f
@var{archive-name}}) when writing your @command{tar} commands.
+../tar_texi/tar.texi(,876) For more information on using the @address@hidden
(@option{-f @var{archive-name}}) option, see
+../tar_texi/tar.texi(,877) @ref{file}.
+../tar_texi/tar.texi(,878)
+../tar_texi/tar.texi(,879) @node verbose tutorial
+../tar_texi/tar.texi(,880) @unnumberedsubsec The @option{--verbose} Option
+../tar_texi/tar.texi(,881)
+../tar_texi/tar.texi(,882) @table @option
+../tar_texi/tar.texi(xopindex,883) @opindex address@hidden, introduced}
+../tar_texi/tar.texi(,884) @item --verbose
+../tar_texi/tar.texi(,885) @itemx -v
+../tar_texi/tar.texi(,886) Show the files being worked on as @command{tar} is
running.
+../tar_texi/tar.texi(,887) @end table
+../tar_texi/tar.texi(,888)
+../tar_texi/tar.texi(,889) @option{--verbose} (@option{-v}) shows details
about the results of running
+../tar_texi/tar.texi(,890) @command{tar}. This can be especially useful when
the results might not be
+../tar_texi/tar.texi(,891) obvious. For example, if you want to see the
progress of @command{tar} as
+../tar_texi/tar.texi(,892) it writes files into the archive, you can use the
@option{--verbose}
+../tar_texi/tar.texi(,893) option. In the beginning, you may find it useful
to use
+../tar_texi/tar.texi(,894) @option{--verbose} at all times; when you are more
accustomed to
+../tar_texi/tar.texi(,895) @command{tar}, you will likely want to use it at
certain times but not at
+../tar_texi/tar.texi(,896) others. We will use @option{--verbose} at times to
help make something
+../tar_texi/tar.texi(,897) clear, and we will give many examples both using
and not using
+../tar_texi/tar.texi(,898) @option{--verbose} to show the differences.
+../tar_texi/tar.texi(,899)
+../tar_texi/tar.texi(,900) Each instance of @option{--verbose} on the command
line increases the
+../tar_texi/tar.texi(,901) verbosity level by one, so if you need more details
on the output,
+../tar_texi/tar.texi(,902) specify it twice.
+../tar_texi/tar.texi(,903)
+../tar_texi/tar.texi(,904) When reading archives (@option{--list},
@option{--extract},
+../tar_texi/tar.texi(,905) @option{--diff}), @command{tar} by default prints
only the names of
+../tar_texi/tar.texi(,906) the members being extracted. Using
@option{--verbose} will show a full,
+../tar_texi/tar.texi(,907) @command{ls} style member listing.
+../tar_texi/tar.texi(,908)
+../tar_texi/tar.texi(,909) In contrast, when writing archives
(@option{--create}, @option{--append},
+../tar_texi/tar.texi(,910) @option{--update}), @command{tar} does not print
file names by
+../tar_texi/tar.texi(,911) default. So, a single @option{--verbose} option
shows the file names
+../tar_texi/tar.texi(,912) being added to the archive, while two
@option{--verbose} options
+../tar_texi/tar.texi(,913) enable the full listing.
+../tar_texi/tar.texi(,914)
+../tar_texi/tar.texi(,915) For example, to create an archive in verbose mode:
+../tar_texi/tar.texi(,916)
+../tar_texi/tar.texi(,917) @smallexample
+../tar_texi/tar.texi(,918) $ @kbd{tar -cvf afiles.tar apple angst aspic}
+../tar_texi/tar.texi(,919) apple
+../tar_texi/tar.texi(,920) angst
+../tar_texi/tar.texi(,921) aspic
+../tar_texi/tar.texi(,922) @end smallexample
+../tar_texi/tar.texi(,923)
+../tar_texi/tar.texi(,924) @noindent
+../tar_texi/tar.texi(,925) Creating the same archive with the verbosity level
2 could give:
+../tar_texi/tar.texi(,926)
+../tar_texi/tar.texi(,927) @smallexample
+../tar_texi/tar.texi(,928) $ @kbd{tar -cvvf afiles.tar apple angst aspic}
+../tar_texi/tar.texi(,929) -rw-r--r-- gray/staff 62373 2006-06-09 12:06
apple
+../tar_texi/tar.texi(,930) -rw-r--r-- gray/staff 11481 2006-06-09 12:06
angst
+../tar_texi/tar.texi(,931) -rw-r--r-- gray/staff 23152 2006-06-09 12:06
aspic
+../tar_texi/tar.texi(,932) @end smallexample
+../tar_texi/tar.texi(,933)
+../tar_texi/tar.texi(,934) @noindent
+../tar_texi/tar.texi(,935) This works equally well using short or long forms
of options. Using
+../tar_texi/tar.texi(,936) long forms, you would simply write out the mnemonic
form of the option
+../tar_texi/tar.texi(,937) twice, like this:
+../tar_texi/tar.texi(,938)
+../tar_texi/tar.texi(,939) @smallexample
+../tar_texi/tar.texi(,940) $ @kbd{tar --create --verbose --verbose @dots{}}
+../tar_texi/tar.texi(,941) @end smallexample
+../tar_texi/tar.texi(,942)
+../tar_texi/tar.texi(,943) @noindent
+../tar_texi/tar.texi(,944) Note that you must double the hyphens properly each
time.
+../tar_texi/tar.texi(,945)
+../tar_texi/tar.texi(,946) Later in the tutorial, we will give examples using
@address@hidden
+../tar_texi/tar.texi(,947) --verbose}}.
+../tar_texi/tar.texi(,948)
+../tar_texi/tar.texi(,949) @anchor{verbose member listing}
+../tar_texi/tar.texi(,950) The full output consists of six fields:
+../tar_texi/tar.texi(,951)
+../tar_texi/tar.texi(,952) @itemize @bullet
+../tar_texi/tar.texi(,953) @item File type and permissions in symbolic form.
+../tar_texi/tar.texi(,954) These are displayed in the same format as the first
column of
+../tar_texi/tar.texi(,955) @command{ls -l} output (@pxref{What information is
listed,
+../tar_texi/tar.texi(,956) format=verbose, Verbose listing, fileutils, GNU
file utilities}).
+../tar_texi/tar.texi(,957)
+../tar_texi/tar.texi(,958) @item Owner name and group separated by a slash
character.
+../tar_texi/tar.texi(,959) If these data are not available (for example, when
listing a @samp{v7} format
+../tar_texi/tar.texi(,960) archive), numeric ID values are printed instead.
+../tar_texi/tar.texi(,961)
+../tar_texi/tar.texi(,962) @item Size of the file, in bytes.
+../tar_texi/tar.texi(,963)
+../tar_texi/tar.texi(,964) @item File modification date in ISO 8601 format.
+../tar_texi/tar.texi(,965)
+../tar_texi/tar.texi(,966) @item File modification time.
+../tar_texi/tar.texi(,967)
+../tar_texi/tar.texi(,968) @item File name.
+../tar_texi/tar.texi(,969) If the name contains any special characters (white
space, newlines,
+../tar_texi/tar.texi(,970) etc.) these are displayed in an unambiguous form
using so called
+../tar_texi/tar.texi(,971) @dfn{quoting style}. For the detailed discussion
of available styles
+../tar_texi/tar.texi(,972) and on how to use them, see @ref{quoting styles}.
+../tar_texi/tar.texi(,973)
+../tar_texi/tar.texi(,974) Depending on the file type, the name can be
followed by some
+../tar_texi/tar.texi(,975) additional information, described in the following
table:
+../tar_texi/tar.texi(,976)
+../tar_texi/tar.texi(,977) @table @samp
+../tar_texi/tar.texi(,978) @item -> @var{link-name}
+../tar_texi/tar.texi(,979) The file or archive member is a @dfn{symbolic link}
and
+../tar_texi/tar.texi(,980) @var{link-name} is the name of file it links to.
+../tar_texi/tar.texi(,981)
+../tar_texi/tar.texi(,982) @item link to @var{link-name}
+../tar_texi/tar.texi(,983) The file or archive member is a @dfn{hard link} and
@var{link-name} is
+../tar_texi/tar.texi(,984) the name of file it links to.
+../tar_texi/tar.texi(,985)
+../tar_texi/tar.texi(,986) @item --Long Link--
+../tar_texi/tar.texi(,987) The archive member is an old GNU format long link.
You will normally
+../tar_texi/tar.texi(,988) not encounter this.
+../tar_texi/tar.texi(,989)
+../tar_texi/tar.texi(,990) @item --Long Name--
+../tar_texi/tar.texi(,991) The archive member is an old GNU format long name.
You will normally
+../tar_texi/tar.texi(,992) not encounter this.
+../tar_texi/tar.texi(,993)
+../tar_texi/tar.texi(,994) @item --Volume Header--
+../tar_texi/tar.texi(,995) The archive member is a GNU @dfn{volume header}
(@pxref{Tape Files}).
+../tar_texi/tar.texi(,996)
+../tar_texi/tar.texi(,997) @item --Continued at byte @var{n}--
+../tar_texi/tar.texi(,998) Encountered only at the beginning of a multy-volume
archive
+../tar_texi/tar.texi(,999) (@pxref{Using Multiple Tapes}). This archive
member is a continuation
+../tar_texi/tar.texi(,1000) from the previous volume. The number @var{n} gives
the offset where
+../tar_texi/tar.texi(,1001) the original file was split.
+../tar_texi/tar.texi(,1002)
+../tar_texi/tar.texi(,1003) @item --Mangled file names--
+../tar_texi/tar.texi(,1004) This archive member contains @dfn{mangled file
names} declarations,
+../tar_texi/tar.texi(GNUTAR,1005) a special member type that was used by early
versions of @acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,1006) You probably will never encounter this, unless you
are reading a very
+../tar_texi/tar.texi(,1007) old archive.
+../tar_texi/tar.texi(,1008)
+../tar_texi/tar.texi(,1009) @item unknown file type @var{c}
+../tar_texi/tar.texi(,1010) An archive member of unknown type. @var{c} is the
type character from
+../tar_texi/tar.texi(,1011) the archive header. If you encounter such a
message, it means that
+../tar_texi/tar.texi(GNUTAR,1012) either your archive contains proprietary
member types @acronym{GNU} @command{tar} is not
+../tar_texi/tar.texi(,1013) able to handle, or the archive is corrupted.
+../tar_texi/tar.texi(,1014) @end table
+../tar_texi/tar.texi(,1015)
+../tar_texi/tar.texi(,1016) @end itemize
+../tar_texi/tar.texi(,1017)
+../tar_texi/tar.texi(,1018) For example, here is an archive listing containing
most of the special
+../tar_texi/tar.texi(,1019) suffixes explained above:
+../tar_texi/tar.texi(,1020)
+../tar_texi/tar.texi(,1021) @smallexample
+../tar_texi/tar.texi(,1022) @group
+../tar_texi/tar.texi(,1023) V--------- 0/0 1536 2006-06-09 13:07
MyVolume--Volume Header--
+../tar_texi/tar.texi(,1024) -rw-r--r-- gray/staff 456783 2006-06-09 12:06
aspic--Continued at
+../tar_texi/tar.texi(,1025) byte 32456--
+../tar_texi/tar.texi(,1026) -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+../tar_texi/tar.texi(,1027) lrwxrwxrwx gray/staff 0 2006-06-09 13:01
angst -> apple
+../tar_texi/tar.texi(,1028) -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+../tar_texi/tar.texi(,1029) hrw-r--r-- gray/staff 0 2006-06-09 12:06
music link to blues
+../tar_texi/tar.texi(,1030) @end group
+../tar_texi/tar.texi(,1031) @end smallexample
+../tar_texi/tar.texi(,1032)
+../tar_texi/tar.texi(,1033) @smallexample
+../tar_texi/tar.texi(,1034) @end smallexample
+../tar_texi/tar.texi(,1035)
+../tar_texi/tar.texi(,1036) @node help tutorial
+../tar_texi/tar.texi(,1037) @unnumberedsubsec Getting Help: Using the
@option{--help} Option
+../tar_texi/tar.texi(,1038)
+../tar_texi/tar.texi(,1039) @table @option
+../tar_texi/tar.texi(,1040) @opindex help
+../tar_texi/tar.texi(,1041) @item --help
+../tar_texi/tar.texi(,1042)
+../tar_texi/tar.texi(,1043) The @option{--help} option to @command{tar} prints
out a very brief list of
+../tar_texi/tar.texi(,1044) all operations and option available for the
current version of
+../tar_texi/tar.texi(,1045) @command{tar} available on your system.
+../tar_texi/tar.texi(,1046) @end table
+../tar_texi/tar.texi(,1047)
+../tar_texi/tar.texi(,1048) @node create
+../tar_texi/tar.texi(,1049) @section How to Create Archives
+../tar_texi/tar.texi(UNREVISED,1050) @quotation
+../tar_texi/tar.texi(UNREVISED,1050) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,1050) @end quotation
+../tar_texi/tar.texi(UNREVISED,1050)
+../tar_texi/tar.texi(,1051)
+../tar_texi/tar.texi(,1052) @cindex Creation of the archive
+../tar_texi/tar.texi(,1053) @cindex Archive, creation of
+../tar_texi/tar.texi(,1054) One of the basic operations of @command{tar} is
@option{--create} (@option{-c}), which
+../tar_texi/tar.texi(,1055) you use to create a @command{tar} archive. We
will explain
+../tar_texi/tar.texi(,1056) @option{--create} first because, in order to learn
about the other
+../tar_texi/tar.texi(,1057) operations, you will find it useful to have an
archive available to
+../tar_texi/tar.texi(,1058) practice on.
+../tar_texi/tar.texi(,1059)
+../tar_texi/tar.texi(,1060) To make this easier, in this section you will
first create a directory
+../tar_texi/tar.texi(,1061) containing three files. Then, we will show you
how to create an
+../tar_texi/tar.texi(,1062) @emph{archive} (inside the new directory). Both
the directory, and
+../tar_texi/tar.texi(,1063) the archive are specifically for you to practice
on. The rest of this
+../tar_texi/tar.texi(,1064) chapter and the next chapter will show many
examples using this
+../tar_texi/tar.texi(,1065) directory and the files you will create: some of
those files may be
+../tar_texi/tar.texi(,1066) other directories and other archives.
+../tar_texi/tar.texi(,1067)
+../tar_texi/tar.texi(,1068) The three files you will archive in this example
are called
+../tar_texi/tar.texi(,1069) @file{blues}, @file{folk}, and @file{jazz}. The
archive is called
+../tar_texi/tar.texi(,1070) @file{collection.tar}.
+../tar_texi/tar.texi(,1071)
+../tar_texi/tar.texi(,1072) This section will proceed slowly, detailing how to
use @option{--create}
+../tar_texi/tar.texi(,1073) in @code{verbose} mode, and showing examples using
both short and long
+../tar_texi/tar.texi(,1074) forms. In the rest of the tutorial, and in the
examples in the next
+../tar_texi/tar.texi(,1075) chapter, we will proceed at a slightly quicker
pace. This section
+../tar_texi/tar.texi(,1076) moves more slowly to allow beginning users to
understand how
+../tar_texi/tar.texi(,1077) @command{tar} works.
+../tar_texi/tar.texi(,1078)
+../tar_texi/tar.texi(,1079) @menu
+../tar_texi/tar.texi(,1080) * prepare for examples::
+../tar_texi/tar.texi(,1081) * Creating the archive::
+../tar_texi/tar.texi(,1082) * create verbose::
+../tar_texi/tar.texi(,1083) * short create::
+../tar_texi/tar.texi(,1084) * create dir::
+../tar_texi/tar.texi(,1085) @end menu
+../tar_texi/tar.texi(,1086)
+../tar_texi/tar.texi(,1087) @node prepare for examples
+../tar_texi/tar.texi(,1088) @subsection Preparing a Practice Directory for
Examples
+../tar_texi/tar.texi(,1089)
+../tar_texi/tar.texi(,1090) To follow along with this and future examples,
create a new directory
+../tar_texi/tar.texi(,1091) called @file{practice} containing files called
@file{blues}, @file{folk}
+../tar_texi/tar.texi(,1092) and @file{jazz}. The files can contain any
information you like:
+../tar_texi/tar.texi(,1093) ideally, they should contain information which
relates to their names,
+../tar_texi/tar.texi(,1094) and be of different lengths. Our examples assume
that @file{practice}
+../tar_texi/tar.texi(,1095) is a subdirectory of your home directory.
+../tar_texi/tar.texi(,1096)
+../tar_texi/tar.texi(,1097) Now @command{cd} to the directory named
@file{practice}; @file{practice}
+../tar_texi/tar.texi(,1098) is now your @dfn{working directory}.
(@emph{Please note}: Although
+../tar_texi/tar.texi(,1099) the full path name of this directory is
+../tar_texi/tar.texi(,1100) @file{/@var{homedir}/practice}, in our examples we
will refer to
+../tar_texi/tar.texi(,1101) this directory as @file{practice}; the
@var{homedir} is presumed.
+../tar_texi/tar.texi(,1102)
+../tar_texi/tar.texi(,1103) In general, you should check that the files to be
archived exist where
+../tar_texi/tar.texi(,1104) you think they do (in the working directory) by
running @command{ls}.
+../tar_texi/tar.texi(,1105) Because you just created the directory and the
files and have changed to
+../tar_texi/tar.texi(,1106) that directory, you probably don't need to do that
this time.
+../tar_texi/tar.texi(,1107)
+../tar_texi/tar.texi(,1108) It is very important to make sure there isn't
already a file in the
+../tar_texi/tar.texi(,1109) working directory with the archive name you intend
to use (in this case,
+../tar_texi/tar.texi(,1110) @samp{collection.tar}), or that you don't care
about its contents.
+../tar_texi/tar.texi(,1111) Whenever you use @samp{create}, @command{tar} will
erase the current
+../tar_texi/tar.texi(,1112) contents of the file named by @address@hidden
(@option{-f @var{archive-name}}) if it exists. @command{tar}
+../tar_texi/tar.texi(,1113) will not tell you if you are about to overwrite an
archive unless you
+../tar_texi/tar.texi(,1114) specify an option which does this (@pxref{backup},
for the
+../tar_texi/tar.texi(,1115) information on how to do so). To add files to an
existing archive,
+../tar_texi/tar.texi(,1116) you need to use a different option, such as
@option{--append} (@option{-r}); see
+../tar_texi/tar.texi(,1117) @ref{append} for information on how to do this.
+../tar_texi/tar.texi(,1118)
+../tar_texi/tar.texi(,1119) @node Creating the archive
+../tar_texi/tar.texi(,1120) @subsection Creating the Archive
+../tar_texi/tar.texi(,1121)
+../tar_texi/tar.texi(xopindex,1122) @opindex address@hidden, introduced}
+../tar_texi/tar.texi(,1123) To place the files @file{blues}, @file{folk}, and
@file{jazz} into an
+../tar_texi/tar.texi(,1124) archive named @file{collection.tar}, use the
following command:
+../tar_texi/tar.texi(,1125)
+../tar_texi/tar.texi(,1126) @smallexample
+../tar_texi/tar.texi(,1127) $ @kbd{tar --create --file=collection.tar blues
folk jazz}
+../tar_texi/tar.texi(,1128) @end smallexample
+../tar_texi/tar.texi(,1129)
+../tar_texi/tar.texi(,1130) The order of the arguments is not very important,
@emph{when using long
+../tar_texi/tar.texi(,1131) option forms}. You could also say:
+../tar_texi/tar.texi(,1132)
+../tar_texi/tar.texi(,1133) @smallexample
+../tar_texi/tar.texi(,1134) $ @kbd{tar blues --create folk
--file=collection.tar jazz}
+../tar_texi/tar.texi(,1135) @end smallexample
+../tar_texi/tar.texi(,1136)
+../tar_texi/tar.texi(,1137) @noindent
+../tar_texi/tar.texi(,1138) However, you can see that this order is harder to
understand; this is
+../tar_texi/tar.texi(,1139) why we will list the arguments in the order that
makes the commands
+../tar_texi/tar.texi(,1140) easiest to understand (and we encourage you to do
the same when you use
+../tar_texi/tar.texi(,1141) @command{tar}, to avoid errors).
+../tar_texi/tar.texi(,1142)
+../tar_texi/tar.texi(,1143) Note that the sequence
+../tar_texi/tar.texi(,1144) @address@hidden is considered to be @emph{one}
argument.
+../tar_texi/tar.texi(,1145) If you substituted any other string of characters
for
+../tar_texi/tar.texi(,1146) @kbd{collection.tar}, then that string would
become the name of the
+../tar_texi/tar.texi(,1147) archive file you create.
+../tar_texi/tar.texi(,1148)
+../tar_texi/tar.texi(,1149) The order of the options becomes more important
when you begin to use
+../tar_texi/tar.texi(,1150) short forms. With short forms, if you type
commands in the wrong order
+../tar_texi/tar.texi(,1151) (even if you type them correctly in all other
ways), you may end up with
+../tar_texi/tar.texi(,1152) results you don't expect. For this reason, it is
a good idea to get
+../tar_texi/tar.texi(,1153) into the habit of typing options in the order that
makes inherent sense.
+../tar_texi/tar.texi(,1154) @xref{short create}, for more information on this.
+../tar_texi/tar.texi(,1155)
+../tar_texi/tar.texi(,1156) In this example, you type the command as shown
above: @option{--create}
+../tar_texi/tar.texi(,1157) is the operation which creates the new archive
+../tar_texi/tar.texi(,1158) (@file{collection.tar}), and @option{--file} is
the option which lets
+../tar_texi/tar.texi(,1159) you give it the name you chose. The files,
@file{blues}, @file{folk},
+../tar_texi/tar.texi(,1160) and @file{jazz}, are now members of the archive,
@file{collection.tar}
+../tar_texi/tar.texi(,1161) (they are @dfn{file name arguments} to the
@option{--create} operation.
+../tar_texi/tar.texi(,1162) @xref{Choosing}, for the detailed discussion on
these.) Now that they are
+../tar_texi/tar.texi(,1163) in the archive, they are called @emph{archive
members}, not files.
+../tar_texi/tar.texi(,1164) (@pxref{Definitions,members}).
+../tar_texi/tar.texi(,1165)
+../tar_texi/tar.texi(,1166) When you create an archive, you @emph{must}
specify which files you
+../tar_texi/tar.texi(,1167) want placed in the archive. If you do not specify
any archive
+../tar_texi/tar.texi(GNUTAR,1168) members, @acronym{GNU} @command{tar} will
complain.
+../tar_texi/tar.texi(,1169)
+../tar_texi/tar.texi(,1170) If you now list the contents of the working
directory (@command{ls}), you will
+../tar_texi/tar.texi(,1171) find the archive file listed as well as the files
you saw previously:
+../tar_texi/tar.texi(,1172)
+../tar_texi/tar.texi(,1173) @smallexample
+../tar_texi/tar.texi(,1174) blues folk jazz collection.tar
+../tar_texi/tar.texi(,1175) @end smallexample
+../tar_texi/tar.texi(,1176)
+../tar_texi/tar.texi(,1177) @noindent
+../tar_texi/tar.texi(,1178) Creating the archive @samp{collection.tar} did not
destroy the copies of
+../tar_texi/tar.texi(,1179) the files in the directory.
+../tar_texi/tar.texi(,1180)
+../tar_texi/tar.texi(,1181) Keep in mind that if you don't indicate an
operation, @command{tar} will not
+../tar_texi/tar.texi(,1182) run and will prompt you for one. If you don't
name any files, @command{tar}
+../tar_texi/tar.texi(,1183) will complain. You must have write access to the
working directory,
+../tar_texi/tar.texi(,1184) or else you will not be able to create an archive
in that directory.
+../tar_texi/tar.texi(,1185)
+../tar_texi/tar.texi(,1186) @emph{Caution}: Do not attempt to use
@option{--create} (@option{-c}) to add files to
+../tar_texi/tar.texi(,1187) an existing archive; it will delete the archive
and write a new one.
+../tar_texi/tar.texi(,1188) Use @option{--append} (@option{-r}) instead.
@xref{append}.
+../tar_texi/tar.texi(,1189)
+../tar_texi/tar.texi(,1190) @node create verbose
+../tar_texi/tar.texi(,1191) @subsection Running @option{--create} with
@option{--verbose}
+../tar_texi/tar.texi(,1192)
+../tar_texi/tar.texi(xopindex,1193) @opindex address@hidden, using with
@option{--verbose}}
+../tar_texi/tar.texi(xopindex,1194) @opindex address@hidden, using with
@option{--create}}
+../tar_texi/tar.texi(,1195) If you include the @option{--verbose}
(@option{-v}) option on the command line,
+../tar_texi/tar.texi(,1196) @command{tar} will list the files it is acting on
as it is working. In
+../tar_texi/tar.texi(,1197) verbose mode, the @code{create} example above
would appear as:
+../tar_texi/tar.texi(,1198)
+../tar_texi/tar.texi(,1199) @smallexample
+../tar_texi/tar.texi(,1200) $ @kbd{tar --create --verbose
--file=collection.tar blues folk jazz}
+../tar_texi/tar.texi(,1201) blues
+../tar_texi/tar.texi(,1202) folk
+../tar_texi/tar.texi(,1203) jazz
+../tar_texi/tar.texi(,1204) @end smallexample
+../tar_texi/tar.texi(,1205)
+../tar_texi/tar.texi(,1206) This example is just like the example we showed
which did not use
+../tar_texi/tar.texi(,1207) @option{--verbose}, except that @command{tar}
generated the remaining lines
+../tar_texi/tar.texi(,1214)
+../tar_texi/tar.texi(,1215) In the rest of the examples in this chapter, we
will frequently use
+../tar_texi/tar.texi(,1216) @code{verbose} mode so we can show actions or
@command{tar} responses that
+../tar_texi/tar.texi(,1217) you would otherwise not see, and which are
important for you to
+../tar_texi/tar.texi(,1218) understand.
+../tar_texi/tar.texi(,1219)
+../tar_texi/tar.texi(,1220) @node short create
+../tar_texi/tar.texi(,1221) @subsection Short Forms with @samp{create}
+../tar_texi/tar.texi(,1222)
+../tar_texi/tar.texi(,1223) As we said before, the @option{--create}
(@option{-c}) operation is one of the most
+../tar_texi/tar.texi(,1224) basic uses of @command{tar}, and you will use it
countless times.
+../tar_texi/tar.texi(,1225) Eventually, you will probably want to use
abbreviated (or ``short'')
+../tar_texi/tar.texi(,1226) forms of options. A full discussion of the three
different forms that
+../tar_texi/tar.texi(,1227) options can take appears in @ref{Styles}; for now,
here is what the
+../tar_texi/tar.texi(,1228) previous example (including the @option{--verbose}
(@option{-v}) option) looks like
+../tar_texi/tar.texi(,1229) using short option forms:
+../tar_texi/tar.texi(,1230)
+../tar_texi/tar.texi(,1231) @smallexample
+../tar_texi/tar.texi(,1232) $ @kbd{tar -cvf collection.tar blues folk jazz}
+../tar_texi/tar.texi(,1233) blues
+../tar_texi/tar.texi(,1234) folk
+../tar_texi/tar.texi(,1235) jazz
+../tar_texi/tar.texi(,1236) @end smallexample
+../tar_texi/tar.texi(,1237)
+../tar_texi/tar.texi(,1238) @noindent
+../tar_texi/tar.texi(,1239) As you can see, the system responds the same no
matter whether you use
+../tar_texi/tar.texi(,1240) long or short option forms.
+../tar_texi/tar.texi(,1241)
+../tar_texi/tar.texi(FIXME,1242) @allow-recursion
+../tar_texi/tar.texi(FIXME,1242) @quote-arg
+../tar_texi/tar.texi(FIXME,1242) One difference between using
+../tar_texi/tar.texi(,1243) short and long option forms is that, although the
exact placement of
+../tar_texi/tar.texi(,1244) arguments following options is no more specific
when using short forms,
+../tar_texi/tar.texi(,1245) it is easier to become confused and make a mistake
when using short
+../tar_texi/tar.texi(,1246) forms. For example, suppose you attempted the
above example in the
+../tar_texi/tar.texi(,1247) following way:
+../tar_texi/tar.texi(,1248)
+../tar_texi/tar.texi(,1249) @smallexample
+../tar_texi/tar.texi(,1250) $ @kbd{tar -cfv collection.tar blues folk jazz}
+../tar_texi/tar.texi(,1251) @end smallexample
+../tar_texi/tar.texi(,1252)
+../tar_texi/tar.texi(,1253) @noindent
+../tar_texi/tar.texi(,1254) In this case, @command{tar} will make an archive
file called @file{v},
+../tar_texi/tar.texi(,1255) containing the files @file{blues}, @file{folk},
and @file{jazz}, because
+../tar_texi/tar.texi(,1256) the @samp{v} is the closest ``file name'' to the
@option{-f} option, and
+../tar_texi/tar.texi(,1257) is thus taken to be the chosen archive file name.
@command{tar} will try
+../tar_texi/tar.texi(,1258) to add a file called @file{collection.tar} to the
@file{v} archive file;
+../tar_texi/tar.texi(,1259) if the file @file{collection.tar} did not already
exist, @command{tar} will
+../tar_texi/tar.texi(,1260) report an error indicating that this file does not
exist. If the file
+../tar_texi/tar.texi(,1261) @file{collection.tar} does already exist (e.g.,
from a previous command
+../tar_texi/tar.texi(,1262) you may have run), then @command{tar} will add
this file to the archive.
+../tar_texi/tar.texi(,1263) Because the @option{-v} option did not get
registered, @command{tar} will not
+../tar_texi/tar.texi(,1264) run under @samp{verbose} mode, and will not report
its progress.
+../tar_texi/tar.texi(,1265)
+../tar_texi/tar.texi(,1266) The end result is that you may be quite confused
about what happened,
+../tar_texi/tar.texi(,1267) and possibly overwrite a file. To illustrate this
further, we will show
+../tar_texi/tar.texi(,1268) you how an example we showed previously would look
using short forms.
+../tar_texi/tar.texi(,1269)
+../tar_texi/tar.texi(,1270) This example,
+../tar_texi/tar.texi(,1271)
+../tar_texi/tar.texi(,1272) @smallexample
+../tar_texi/tar.texi(,1273) $ @kbd{tar blues --create folk
--file=collection.tar jazz}
+../tar_texi/tar.texi(,1274) @end smallexample
+../tar_texi/tar.texi(,1275)
+../tar_texi/tar.texi(,1276) @noindent
+../tar_texi/tar.texi(,1277) is confusing as it is. When shown using short
forms, however, it
+../tar_texi/tar.texi(,1278) becomes much more so:
+../tar_texi/tar.texi(,1279)
+../tar_texi/tar.texi(,1280) @smallexample
+../tar_texi/tar.texi(,1281) $ @kbd{tar blues -c folk -f collection.tar jazz}
+../tar_texi/tar.texi(,1282) @end smallexample
+../tar_texi/tar.texi(,1283)
+../tar_texi/tar.texi(,1284) @noindent
+../tar_texi/tar.texi(,1285) It would be very easy to put the wrong string of
characters
+../tar_texi/tar.texi(,1286) immediately following the @option{-f}, but doing
that could sacrifice
+../tar_texi/tar.texi(,1287) valuable data.
+../tar_texi/tar.texi(,1288)
+../tar_texi/tar.texi(,1289) For this reason, we recommend that you pay very
careful attention to
+../tar_texi/tar.texi(,1290) the order of options and placement of file and
archive names,
+../tar_texi/tar.texi(,1291) especially when using short option forms. Not
having the option name
+../tar_texi/tar.texi(,1292) written out mnemonically can affect how well you
remember which option
+../tar_texi/tar.texi(,1293) does what, and therefore where different names
have to be placed.
+../tar_texi/tar.texi(,1294)
+../tar_texi/tar.texi(,1295) @node create dir
+../tar_texi/tar.texi(,1296) @subsection Archiving Directories
+../tar_texi/tar.texi(,1297)
+../tar_texi/tar.texi(,1298) @cindex Archiving Directories
+../tar_texi/tar.texi(,1299) @cindex Directories, Archiving
+../tar_texi/tar.texi(,1300) You can archive a directory by specifying its
directory name as a
+../tar_texi/tar.texi(,1301) file name argument to @command{tar}. The files in
the directory will be
+../tar_texi/tar.texi(,1302) archived relative to the working directory, and
the directory will be
+../tar_texi/tar.texi(,1303) re-created along with its contents when the
archive is extracted.
+../tar_texi/tar.texi(,1304)
+../tar_texi/tar.texi(,1305) To archive a directory, first move to its superior
directory. If you
+../tar_texi/tar.texi(,1306) have followed the previous instructions in this
tutorial, you should
+../tar_texi/tar.texi(,1307) type:
+../tar_texi/tar.texi(,1308)
+../tar_texi/tar.texi(,1309) @smallexample
+../tar_texi/tar.texi(,1310) $ @kbd{cd ..}
+../tar_texi/tar.texi(,1311) $
+../tar_texi/tar.texi(,1312) @end smallexample
+../tar_texi/tar.texi(,1313)
+../tar_texi/tar.texi(,1314) @noindent
+../tar_texi/tar.texi(,1315) This will put you into the directory which
contains @file{practice},
+../tar_texi/tar.texi(,1316) i.e., your home directory. Once in the superior
directory, you can
+../tar_texi/tar.texi(,1317) specify the subdirectory, @file{practice}, as a
file name argument. To
+../tar_texi/tar.texi(,1318) store @file{practice} in the new archive file
@file{music.tar}, type:
+../tar_texi/tar.texi(,1319)
+../tar_texi/tar.texi(,1320) @smallexample
+../tar_texi/tar.texi(,1321) $ @kbd{tar --create --verbose --file=music.tar
practice}
+../tar_texi/tar.texi(,1322) @end smallexample
+../tar_texi/tar.texi(,1323)
+../tar_texi/tar.texi(,1324) @noindent
+../tar_texi/tar.texi(,1325) @command{tar} should output:
+../tar_texi/tar.texi(,1326)
+../tar_texi/tar.texi(,1327) @smallexample
+../tar_texi/tar.texi(,1328) practice/
+../tar_texi/tar.texi(,1329) practice/blues
+../tar_texi/tar.texi(,1330) practice/folk
+../tar_texi/tar.texi(,1331) practice/jazz
+../tar_texi/tar.texi(,1332) practice/collection.tar
+../tar_texi/tar.texi(,1333) @end smallexample
+../tar_texi/tar.texi(,1334)
+../tar_texi/tar.texi(,1335) Note that the archive thus created is not in the
subdirectory
+../tar_texi/tar.texi(,1336) @file{practice}, but rather in the current working
directory---the
+../tar_texi/tar.texi(,1337) directory from which @command{tar} was invoked.
Before trying to archive a
+../tar_texi/tar.texi(,1338) directory from its superior directory, you should
make sure you have
+../tar_texi/tar.texi(,1339) write access to the superior directory itself, not
only the directory
+../tar_texi/tar.texi(,1340) you are trying archive with @command{tar}. For
example, you will probably
+../tar_texi/tar.texi(,1341) not be able to store your home directory in an
archive by invoking
+../tar_texi/tar.texi(,1342) @command{tar} from the root directory;
@xref{absolute}. (Note
+../tar_texi/tar.texi(,1343) also that @file{collection.tar}, the original
archive file, has itself
+../tar_texi/tar.texi(,1344) been archived. @command{tar} will accept any file
as a file to be
+../tar_texi/tar.texi(,1345) archived, regardless of its content. When
@file{music.tar} is
+../tar_texi/tar.texi(,1346) extracted, the archive file @file{collection.tar}
will be re-written
+../tar_texi/tar.texi(,1347) into the file system).
+../tar_texi/tar.texi(,1348)
+../tar_texi/tar.texi(,1349) If you give @command{tar} a command such as
+../tar_texi/tar.texi(,1350)
+../tar_texi/tar.texi(,1351) @smallexample
+../tar_texi/tar.texi(,1352) $ @kbd{tar --create --file=foo.tar .}
+../tar_texi/tar.texi(,1353) @end smallexample
+../tar_texi/tar.texi(,1354)
+../tar_texi/tar.texi(,1355) @noindent
+../tar_texi/tar.texi(,1356) @command{tar} will report @samp{tar: ./foo.tar is
the archive; not
+../tar_texi/tar.texi(,1357) dumped}. This happens because @command{tar}
creates the archive
+../tar_texi/tar.texi(,1358) @file{foo.tar} in the current directory before
putting any files into
+../tar_texi/tar.texi(,1359) it. Then, when @command{tar} attempts to add all
the files in the
+../tar_texi/tar.texi(,1360) directory @file{.} to the archive, it notices that
the file
+../tar_texi/tar.texi(,1361) @file{./foo.tar} is the same as the archive
@file{foo.tar}, and skips
+../tar_texi/tar.texi(GNUTAR,1362) it. (It makes no sense to put an archive
into itself.) @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,1363) will continue in this case, and create the archive
+../tar_texi/tar.texi(,1364) normally, except for the exclusion of that one
file. (@emph{Please
+../tar_texi/tar.texi(,1365) note:} Other implementations of @command{tar} may
not be so clever;
+../tar_texi/tar.texi(,1366) they will enter an infinite loop when this
happens, so you should not
+../tar_texi/tar.texi(,1367) depend on this behavior unless you are certain you
are running
+../tar_texi/tar.texi(GNUTAR,1368) @acronym{GNU} @command{tar}. In general, it
is wise to always place the archive outside
+../tar_texi/tar.texi(,1369) of the directory being dumped.
+../tar_texi/tar.texi(,1370)
+../tar_texi/tar.texi(,1371) @node list
+../tar_texi/tar.texi(,1372) @section How to List Archives
+../tar_texi/tar.texi(,1373)
+../tar_texi/tar.texi(,1374) @opindex list
+../tar_texi/tar.texi(,1375) Frequently, you will find yourself wanting to
determine exactly what a
+../tar_texi/tar.texi(,1376) particular archive contains. You can use the
@option{--list}
+../tar_texi/tar.texi(,1377) (@option{-t}) operation to get the member names as
they currently
+../tar_texi/tar.texi(,1378) appear in the archive, as well as various
attributes of the files at
+../tar_texi/tar.texi(,1379) the time they were archived. For example, you can
examine the archive
+../tar_texi/tar.texi(,1380) @file{collection.tar} that you created in the last
section with the
+../tar_texi/tar.texi(,1381) command,
+../tar_texi/tar.texi(,1382)
+../tar_texi/tar.texi(,1383) @smallexample
+../tar_texi/tar.texi(,1384) $ @kbd{tar --list --file=collection.tar}
+../tar_texi/tar.texi(,1385) @end smallexample
+../tar_texi/tar.texi(,1386)
+../tar_texi/tar.texi(,1387) @noindent
+../tar_texi/tar.texi(,1388) The output of @command{tar} would then be:
+../tar_texi/tar.texi(,1389)
+../tar_texi/tar.texi(,1390) @smallexample
+../tar_texi/tar.texi(,1391) blues
+../tar_texi/tar.texi(,1392) folk
+../tar_texi/tar.texi(,1393) jazz
+../tar_texi/tar.texi(,1394) @end smallexample
+../tar_texi/tar.texi(,1395)
+../tar_texi/tar.texi(,1396) @noindent
+../tar_texi/tar.texi(,1397) The archive @file{bfiles.tar} would list as
follows:
+../tar_texi/tar.texi(,1398)
+../tar_texi/tar.texi(,1399) @smallexample
+../tar_texi/tar.texi(,1400) ./birds
+../tar_texi/tar.texi(,1401) baboon
+../tar_texi/tar.texi(,1402) ./box
+../tar_texi/tar.texi(,1403) @end smallexample
+../tar_texi/tar.texi(,1404)
+../tar_texi/tar.texi(,1405) @noindent
+../tar_texi/tar.texi(,1406) Be sure to use a @address@hidden (@option{-f
+../tar_texi/tar.texi(,1407) @var{archive-name}}) option just as with
@option{--create}
+../tar_texi/tar.texi(,1408) (@option{-c}) to specify the name of the archive.
+../tar_texi/tar.texi(,1409)
+../tar_texi/tar.texi(xopindex,1410) @opindex address@hidden, using with
@option{--verbose}}
+../tar_texi/tar.texi(xopindex,1411) @opindex address@hidden, using with
@option{--list}}
+../tar_texi/tar.texi(,1412) If you use the @option{--verbose} (@option{-v})
option with
+../tar_texi/tar.texi(,1413) @option{--list}, then @command{tar} will print out
a listing
+../tar_texi/tar.texi(,1414) reminiscent of @address@hidden -l}}, showing
owner, file size, and so
+../tar_texi/tar.texi(,1415) forth. This output is described in detail in
@ref{verbose member listing}.
+../tar_texi/tar.texi(,1416)
+../tar_texi/tar.texi(,1417) If you had used @option{--verbose} (@option{-v})
mode, the example
+../tar_texi/tar.texi(,1418) above would look like:
+../tar_texi/tar.texi(,1419)
+../tar_texi/tar.texi(,1420) @smallexample
+../tar_texi/tar.texi(,1421) $ @kbd{tar --list --verbose --file=collection.tar
folk}
+../tar_texi/tar.texi(,1422) -rw-r--r-- myself user 62 1990-05-23 10:55 folk
+../tar_texi/tar.texi(,1423) @end smallexample
+../tar_texi/tar.texi(,1424)
+../tar_texi/tar.texi(,1425) @cindex listing member and file names
+../tar_texi/tar.texi(,1426) @anchor{listing member and file names}
+../tar_texi/tar.texi(,1427) It is important to notice that the output of
@kbd{tar --list
+../tar_texi/tar.texi(,1428) --verbose} does not necessarily match that
produced by @kbd{tar
+../tar_texi/tar.texi(,1429) --create --verbose} while creating the archive.
It is because
+../tar_texi/tar.texi(GNUTAR,1430) @acronym{GNU} @command{tar}, unless told
explicitly not to do so, removes some directory
+../tar_texi/tar.texi(,1431) prefixes from file names before storing them in
the archive
+../tar_texi/tar.texi(,1432) (@xref{absolute}, for more information). In other
+../tar_texi/tar.texi(GNUTAR,1433) words, in verbose mode @acronym{GNU}
@command{tar} shows @dfn{file names} when creating
+../tar_texi/tar.texi(,1434) an archive and @dfn{member names} when listing it.
Consider this
+../tar_texi/tar.texi(,1435) example:
+../tar_texi/tar.texi(,1436)
+../tar_texi/tar.texi(,1437) @smallexample
+../tar_texi/tar.texi(,1438) @group
+../tar_texi/tar.texi(,1439) $ @kbd{tar cfv archive /etc/mail}
+../tar_texi/tar.texi(,1440) tar: Removing leading `/' from member names
+../tar_texi/tar.texi(,1441) /etc/mail/
+../tar_texi/tar.texi(,1442) /etc/mail/sendmail.cf
+../tar_texi/tar.texi(,1443) /etc/mail/aliases
+../tar_texi/tar.texi(,1444) $ @kbd{tar tf archive}
+../tar_texi/tar.texi(,1445) etc/mail/
+../tar_texi/tar.texi(,1446) etc/mail/sendmail.cf
+../tar_texi/tar.texi(,1447) etc/mail/aliases
+../tar_texi/tar.texi(,1448) @end group
+../tar_texi/tar.texi(,1449) @end smallexample
+../tar_texi/tar.texi(,1450)
+../tar_texi/tar.texi(,1451) @opindex show-stored-names
+../tar_texi/tar.texi(,1452) This default behavior can sometimes be
inconvenient. You can force
+../tar_texi/tar.texi(GNUTAR,1453) @acronym{GNU} @command{tar} show member
names when creating archive by supplying
+../tar_texi/tar.texi(,1454) @option{--show-stored-names} option.
+../tar_texi/tar.texi(,1455)
+../tar_texi/tar.texi(,1456) @table @option
+../tar_texi/tar.texi(,1457) @item --show-stored-names
+../tar_texi/tar.texi(,1458) Print member (as opposed to @emph{file}) names
when creating the archive.
+../tar_texi/tar.texi(,1459) @end table
+../tar_texi/tar.texi(,1460)
+../tar_texi/tar.texi(,1461) @cindex File name arguments, using @option{--list}
with
+../tar_texi/tar.texi(xopindex,1462) @opindex address@hidden, using with file
name arguments}
+../tar_texi/tar.texi(,1463) You can specify one or more individual member
names as arguments when
+../tar_texi/tar.texi(,1464) using @samp{list}. In this case, @command{tar}
will only list the
+../tar_texi/tar.texi(,1465) names of members you identify. For example,
@address@hidden --list
+../tar_texi/tar.texi(,1466) --file=afiles.tar apple}} would only print
@file{apple}.
+../tar_texi/tar.texi(,1467)
+../tar_texi/tar.texi(,1468) Because @command{tar} preserves paths, file names
must be specified as
+../tar_texi/tar.texi(,1469) they appear in the archive (i.e., relative to the
directory from which
+../tar_texi/tar.texi(,1470) the archive was created). Therefore, it is
essential when specifying
+../tar_texi/tar.texi(,1471) member names to @command{tar} that you give the
exact member names.
+../tar_texi/tar.texi(,1472) For example, @address@hidden --list
--file=bfiles.tar birds}} would produce an
+../tar_texi/tar.texi(,1473) error message something like @samp{tar: birds: Not
found in archive},
+../tar_texi/tar.texi(,1474) because there is no member named @file{birds},
only one named
+../tar_texi/tar.texi(,1475) @file{./birds}. While the names @file{birds} and
@file{./birds} name
+../tar_texi/tar.texi(,1476) the same file, @emph{member} names by default are
compared verbatim.
+../tar_texi/tar.texi(,1477)
+../tar_texi/tar.texi(,1478) However, @address@hidden --list --file=bfiles.tar
baboon}} would respond
+../tar_texi/tar.texi(,1479) with @file{baboon}, because this exact member name
is in the archive file
+../tar_texi/tar.texi(,1480) @file{bfiles.tar}. If you are not sure of the
exact file name,
+../tar_texi/tar.texi(,1481) use @dfn{globbing patterns}, for example:
+../tar_texi/tar.texi(,1482)
+../tar_texi/tar.texi(,1483) @smallexample
+../tar_texi/tar.texi(,1484) $ @kbd{tar --list --file=bfiles.tar --wildcards
'*b*'}
+../tar_texi/tar.texi(,1485) @end smallexample
+../tar_texi/tar.texi(,1486)
+../tar_texi/tar.texi(,1487) @noindent
+../tar_texi/tar.texi(,1488) will list all members whose name contains
@samp{b}. @xref{wildcards},
+../tar_texi/tar.texi(,1489) for a detailed discussion of globbing patterns and
related
+../tar_texi/tar.texi(,1490) @command{tar} command line options.
+../tar_texi/tar.texi(,1491)
+../tar_texi/tar.texi(,1492) @menu
+../tar_texi/tar.texi(,1493) * list dir::
+../tar_texi/tar.texi(,1494) @end menu
+../tar_texi/tar.texi(,1495)
+../tar_texi/tar.texi(,1496) @node list dir
+../tar_texi/tar.texi(,1497) @unnumberedsubsec Listing the Contents of a Stored
Directory
+../tar_texi/tar.texi(,1498)
+../tar_texi/tar.texi(,1499) To get information about the contents of an
archived directory,
+../tar_texi/tar.texi(,1500) use the directory name as a file name argument in
conjunction with
+../tar_texi/tar.texi(,1501) @option{--list} (@option{-t}). To find out file
attributes, include the
+../tar_texi/tar.texi(,1502) @option{--verbose} (@option{-v}) option.
+../tar_texi/tar.texi(,1503)
+../tar_texi/tar.texi(,1504) For example, to find out about files in the
directory @file{practice}, in
+../tar_texi/tar.texi(,1505) the archive file @file{music.tar}, type:
+../tar_texi/tar.texi(,1506)
+../tar_texi/tar.texi(,1507) @smallexample
+../tar_texi/tar.texi(,1508) $ @kbd{tar --list --verbose --file=music.tar
practice}
+../tar_texi/tar.texi(,1509) @end smallexample
+../tar_texi/tar.texi(,1510)
+../tar_texi/tar.texi(,1511) @command{tar} responds:
+../tar_texi/tar.texi(,1512)
+../tar_texi/tar.texi(,1513) @smallexample
+../tar_texi/tar.texi(,1514) drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
+../tar_texi/tar.texi(,1515) -rw-r--r-- myself user 42 1990-05-21 13:29
practice/blues
+../tar_texi/tar.texi(,1516) -rw-r--r-- myself user 62 1990-05-23 10:55
practice/folk
+../tar_texi/tar.texi(,1517) -rw-r--r-- myself user 40 1990-05-21 13:30
practice/jazz
+../tar_texi/tar.texi(,1518) -rw-r--r-- myself user 10240 1990-05-31 21:49
practice/collection.tar
+../tar_texi/tar.texi(,1519) @end smallexample
+../tar_texi/tar.texi(,1520)
+../tar_texi/tar.texi(,1521) When you use a directory name as a file name
argument, @command{tar} acts on
+../tar_texi/tar.texi(,1522) all the files (including sub-directories) in that
directory.
+../tar_texi/tar.texi(,1523)
+../tar_texi/tar.texi(,1524) @node extract
+../tar_texi/tar.texi(,1525) @section How to Extract Members from an Archive
+../tar_texi/tar.texi(UNREVISED,1526) @quotation
+../tar_texi/tar.texi(UNREVISED,1526) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,1526) @end quotation
+../tar_texi/tar.texi(UNREVISED,1526)
+../tar_texi/tar.texi(,1527) @cindex Extraction
+../tar_texi/tar.texi(,1528) @cindex Retrieving files from an archive
+../tar_texi/tar.texi(,1529) @cindex Resurrecting files from an archive
+../tar_texi/tar.texi(,1530)
+../tar_texi/tar.texi(,1531) @opindex extract
+../tar_texi/tar.texi(,1532) Creating an archive is only half the job---there
is no point in storing
+../tar_texi/tar.texi(,1533) files in an archive if you can't retrieve them.
The act of retrieving
+../tar_texi/tar.texi(,1534) members from an archive so they can be used and
manipulated as
+../tar_texi/tar.texi(,1535) unarchived files again is called @dfn{extraction}.
To extract files
+../tar_texi/tar.texi(,1536) from an archive, use the @option{--extract}
(@option{--get} or
+../tar_texi/tar.texi(,1537) @option{-x}) operation. As with
@option{--create}, specify the name
+../tar_texi/tar.texi(,1538) of the archive with @option{--file} (@option{-f})
option. Extracting
+../tar_texi/tar.texi(,1539) an archive does not modify the archive in any way;
you can extract it
+../tar_texi/tar.texi(,1540) multiple times if you want or need to.
+../tar_texi/tar.texi(,1541)
+../tar_texi/tar.texi(,1542) Using @option{--extract}, you can extract an
entire archive, or specific
+../tar_texi/tar.texi(,1543) files. The files can be directories containing
other files, or not. As
+../tar_texi/tar.texi(,1544) with @option{--create} (@option{-c}) and
@option{--list} (@option{-t}), you may use the short or the
+../tar_texi/tar.texi(,1545) long form of the operation without affecting the
performance.
+../tar_texi/tar.texi(,1546)
+../tar_texi/tar.texi(,1547) @menu
+../tar_texi/tar.texi(,1548) * extracting archives::
+../tar_texi/tar.texi(,1549) * extracting files::
+../tar_texi/tar.texi(,1550) * extract dir::
+../tar_texi/tar.texi(,1551) * extracting untrusted archives::
+../tar_texi/tar.texi(,1552) * failing commands::
+../tar_texi/tar.texi(,1553) @end menu
+../tar_texi/tar.texi(,1554)
+../tar_texi/tar.texi(,1555) @node extracting archives
+../tar_texi/tar.texi(,1556) @subsection Extracting an Entire Archive
+../tar_texi/tar.texi(,1557)
+../tar_texi/tar.texi(,1558) To extract an entire archive, specify the archive
file name only, with
+../tar_texi/tar.texi(,1559) no individual file names as arguments. For
example,
+../tar_texi/tar.texi(,1560)
+../tar_texi/tar.texi(,1561) @smallexample
+../tar_texi/tar.texi(,1562) $ @kbd{tar -xvf collection.tar}
+../tar_texi/tar.texi(,1563) @end smallexample
+../tar_texi/tar.texi(,1564)
+../tar_texi/tar.texi(,1565) @noindent
+../tar_texi/tar.texi(,1566) produces this:
+../tar_texi/tar.texi(,1567)
+../tar_texi/tar.texi(,1568) @smallexample
+../tar_texi/tar.texi(,1569) -rw-r--r-- me user 28 1996-10-18 16:31 jazz
+../tar_texi/tar.texi(,1570) -rw-r--r-- me user 21 1996-09-23 16:44 blues
+../tar_texi/tar.texi(,1571) -rw-r--r-- me user 20 1996-09-23 16:44 folk
+../tar_texi/tar.texi(,1572) @end smallexample
+../tar_texi/tar.texi(,1573)
+../tar_texi/tar.texi(,1574) @node extracting files
+../tar_texi/tar.texi(,1575) @subsection Extracting Specific Files
+../tar_texi/tar.texi(,1576)
+../tar_texi/tar.texi(,1577) To extract specific archive members, give their
exact member names as
+../tar_texi/tar.texi(,1578) arguments, as printed by @option{--list}
(@option{-t}). If you had
+../tar_texi/tar.texi(,1579) mistakenly deleted one of the files you had placed
in the archive
+../tar_texi/tar.texi(,1580) @file{collection.tar} earlier (say, @file{blues}),
you can extract it
+../tar_texi/tar.texi(,1581) from the archive without changing the archive's
structure. Its
+../tar_texi/tar.texi(,1582) contents will be identical to the original file
@file{blues} that you
+../tar_texi/tar.texi(,1583) deleted.
+../tar_texi/tar.texi(,1584)
+../tar_texi/tar.texi(,1585) First, make sure you are in the @file{practice}
directory, and list the
+../tar_texi/tar.texi(,1586) files in the directory. Now, delete the file,
@samp{blues}, and list
+../tar_texi/tar.texi(,1587) the files in the directory again.
+../tar_texi/tar.texi(,1588)
+../tar_texi/tar.texi(,1589) You can now extract the member @file{blues} from
the archive file
+../tar_texi/tar.texi(,1590) @file{collection.tar} like this:
+../tar_texi/tar.texi(,1591)
+../tar_texi/tar.texi(,1592) @smallexample
+../tar_texi/tar.texi(,1593) $ @kbd{tar --extract --file=collection.tar blues}
+../tar_texi/tar.texi(,1594) @end smallexample
+../tar_texi/tar.texi(,1595)
+../tar_texi/tar.texi(,1596) @noindent
+../tar_texi/tar.texi(,1597) If you list the files in the directory again, you
will see that the file
+../tar_texi/tar.texi(,1598) @file{blues} has been restored, with its original
permissions, data
+../tar_texi/tar.texi(,1599) modification times, and address@hidden is only
accidentally
+../tar_texi/tar.texi(,1600) true, but not in general. Whereas modification
times are always
+../tar_texi/tar.texi(,1601) restored, in most cases, one has to be root for
restoring the owner,
+../tar_texi/tar.texi(,1602) and use a special option for restoring
permissions. Here, it just
+../tar_texi/tar.texi(,1603) happens that the restoring user is also the owner
of the archived
+../tar_texi/tar.texi(,1604) members, and that the current @code{umask} is
compatible with original
+../tar_texi/tar.texi(,1605) permissions.} (These parameters will be identical
to those which
+../tar_texi/tar.texi(,1606) the file had when you originally placed it in the
archive; any changes
+../tar_texi/tar.texi(,1607) you may have made before deleting the file from
the file system,
+../tar_texi/tar.texi(,1608) however, will @emph{not} have been made to the
archive member.) The
+../tar_texi/tar.texi(,1609) archive file, @samp{collection.tar}, is the same
as it was before you
+../tar_texi/tar.texi(,1610) extracted @samp{blues}. You can confirm this by
running @command{tar} with
+../tar_texi/tar.texi(,1611) @option{--list} (@option{-t}).
+../tar_texi/tar.texi(,1612)
+../tar_texi/tar.texi(,1613) Remember that as with other operations, specifying
the exact member
+../tar_texi/tar.texi(,1614) name is important. @address@hidden --extract
--file=bfiles.tar birds}}
+../tar_texi/tar.texi(,1615) will fail, because there is no member named
@file{birds}. To extract
+../tar_texi/tar.texi(,1616) the member named @file{./birds}, you must specify
@address@hidden
+../tar_texi/tar.texi(,1617) --extract --file=bfiles.tar ./birds}}. If you
don't remember the
+../tar_texi/tar.texi(,1618) exact member names, use @option{--list}
(@option{-t}) option
+../tar_texi/tar.texi(,1619) (@pxref{list}). You can also extract those
members that match a
+../tar_texi/tar.texi(,1620) specific @dfn{globbing pattern}. For example, to
extract from
+../tar_texi/tar.texi(,1621) @file{bfiles.tar} all files that begin with
@samp{b}, no matter their
+../tar_texi/tar.texi(,1622) directory prefix, you could type:
+../tar_texi/tar.texi(,1623)
+../tar_texi/tar.texi(,1624) @smallexample
+../tar_texi/tar.texi(,1625) $ @kbd{tar -x -f bfiles.tar --wildcards
--no-anchored 'b*'}
+../tar_texi/tar.texi(,1626) @end smallexample
+../tar_texi/tar.texi(,1627)
+../tar_texi/tar.texi(,1628) @noindent
+../tar_texi/tar.texi(,1629) Here, @option{--wildcards} instructs @command{tar}
to treat
+../tar_texi/tar.texi(,1630) command line arguments as globbing patterns and
@option{--no-anchored}
+../tar_texi/tar.texi(,1631) informs it that the patterns apply to member names
after any @samp{/}
+../tar_texi/tar.texi(,1632) delimiter. The use of globbing patterns is
discussed in detail in
+../tar_texi/tar.texi(,1633) @xref{wildcards}.
+../tar_texi/tar.texi(,1634)
+../tar_texi/tar.texi(,1635) You can extract a file to standard output by
combining the above options
+../tar_texi/tar.texi(,1636) with the @option{--to-stdout} (@option{-O}) option
(@pxref{Writing to Standard
+../tar_texi/tar.texi(,1637) Output}).
+../tar_texi/tar.texi(,1638)
+../tar_texi/tar.texi(,1639) If you give the @option{--verbose} option, then
@option{--extract}
+../tar_texi/tar.texi(,1640) will print the names of the archive members as it
extracts them.
+../tar_texi/tar.texi(,1641)
+../tar_texi/tar.texi(,1642) @node extract dir
+../tar_texi/tar.texi(,1643) @subsection Extracting Files that are Directories
+../tar_texi/tar.texi(,1644)
+../tar_texi/tar.texi(,1645) Extracting directories which are members of an
archive is similar to
+../tar_texi/tar.texi(,1646) extracting other files. The main difference to be
aware of is that if
+../tar_texi/tar.texi(,1647) the extracted directory has the same name as any
directory already in
+../tar_texi/tar.texi(,1648) the working directory, then files in the extracted
directory will be
+../tar_texi/tar.texi(,1649) placed into the directory of the same name.
Likewise, if there are
+../tar_texi/tar.texi(,1650) files in the pre-existing directory with the same
names as the members
+../tar_texi/tar.texi(,1651) which you extract, the files from the extracted
archive will replace
+../tar_texi/tar.texi(,1652) the files already in the working directory (and
possible
+../tar_texi/tar.texi(,1653) subdirectories). This will happen regardless of
whether or not the
+../tar_texi/tar.texi(,1654) files in the working directory were more recent
than those extracted
+../tar_texi/tar.texi(,1655) (there exist, however, special options that alter
this behavior
+../tar_texi/tar.texi(,1656) @pxref{Writing}).
+../tar_texi/tar.texi(,1657)
+../tar_texi/tar.texi(,1658) However, if a file was stored with a directory
name as part of its file
+../tar_texi/tar.texi(,1659) name, and that directory does not exist under the
working directory when
+../tar_texi/tar.texi(,1660) the file is extracted, @command{tar} will create
the directory.
+../tar_texi/tar.texi(,1661)
+../tar_texi/tar.texi(,1662) We can demonstrate how to use @option{--extract}
to extract a directory
+../tar_texi/tar.texi(,1663) file with an example. Change to the
@file{practice} directory if you
+../tar_texi/tar.texi(,1664) weren't there, and remove the files @file{folk}
and @file{jazz}. Then,
+../tar_texi/tar.texi(,1665) go back to the parent directory and extract the
archive
+../tar_texi/tar.texi(,1666) @file{music.tar}. You may either extract the
entire archive, or you may
+../tar_texi/tar.texi(,1667) extract only the files you just deleted. To
extract the entire archive,
+../tar_texi/tar.texi(,1668) don't give any file names as arguments after the
archive name
+../tar_texi/tar.texi(,1669) @file{music.tar}. To extract only the files you
deleted, use the
+../tar_texi/tar.texi(,1670) following command:
+../tar_texi/tar.texi(,1671)
+../tar_texi/tar.texi(,1672) @smallexample
+../tar_texi/tar.texi(,1673) $ @kbd{tar -xvf music.tar practice/folk
practice/jazz}
+../tar_texi/tar.texi(,1674) practice/folk
+../tar_texi/tar.texi(,1675) practice/jazz
+../tar_texi/tar.texi(,1676) @end smallexample
+../tar_texi/tar.texi(,1677)
+../tar_texi/tar.texi(,1678) @noindent
+../tar_texi/tar.texi(,1679) If you were to specify two @option{--verbose}
(@option{-v}) options, @command{tar}
+../tar_texi/tar.texi(,1680) would have displayed more detail about the
extracted files, as shown
+../tar_texi/tar.texi(,1681) in the example below:
+../tar_texi/tar.texi(,1682)
+../tar_texi/tar.texi(,1683) @smallexample
+../tar_texi/tar.texi(,1684) $ @kbd{tar -xvvf music.tar practice/folk
practice/jazz}
+../tar_texi/tar.texi(,1685) -rw-r--r-- me user 28 1996-10-18 16:31
practice/jazz
+../tar_texi/tar.texi(,1686) -rw-r--r-- me user 20 1996-09-23 16:44
practice/folk
+../tar_texi/tar.texi(,1687) @end smallexample
+../tar_texi/tar.texi(,1688)
+../tar_texi/tar.texi(,1689) @noindent
+../tar_texi/tar.texi(,1690) Because you created the directory with
@file{practice} as part of the
+../tar_texi/tar.texi(,1691) file names of each of the files by archiving the
@file{practice}
+../tar_texi/tar.texi(,1692) directory as @file{practice}, you must give
@file{practice} as part
+../tar_texi/tar.texi(,1693) of the file names when you extract those files
from the archive.
+../tar_texi/tar.texi(,1694)
+../tar_texi/tar.texi(,1695) @node extracting untrusted archives
+../tar_texi/tar.texi(,1696) @subsection Extracting Archives from Untrusted
Sources
+../tar_texi/tar.texi(,1697)
+../tar_texi/tar.texi(,1698) Extracting files from archives can overwrite files
that already exist.
+../tar_texi/tar.texi(,1699) If you receive an archive from an untrusted
source, you should make a
+../tar_texi/tar.texi(,1700) new directory and extract into that directory, so
that you don't have
+../tar_texi/tar.texi(,1701) to worry about the extraction overwriting one of
your existing files.
+../tar_texi/tar.texi(,1702) For example, if @file{untrusted.tar} came from
somewhere else on the
+../tar_texi/tar.texi(,1703) Internet, and you don't necessarily trust its
contents, you can
+../tar_texi/tar.texi(,1704) extract it as follows:
+../tar_texi/tar.texi(,1705)
+../tar_texi/tar.texi(,1706) @smallexample
+../tar_texi/tar.texi(,1707) $ @kbd{mkdir newdir}
+../tar_texi/tar.texi(,1708) $ @kbd{cd newdir}
+../tar_texi/tar.texi(,1709) $ @kbd{tar -xvf ../untrusted.tar}
+../tar_texi/tar.texi(,1710) @end smallexample
+../tar_texi/tar.texi(,1711)
+../tar_texi/tar.texi(,1712) It is also a good practice to examine contents of
the archive
+../tar_texi/tar.texi(,1713) before extracting it, using @option{--list}
(@option{-t}) option, possibly combined
+../tar_texi/tar.texi(,1714) with @option{--verbose} (@option{-v}).
+../tar_texi/tar.texi(,1715)
+../tar_texi/tar.texi(,1716) @node failing commands
+../tar_texi/tar.texi(,1717) @subsection Commands That Will Fail
+../tar_texi/tar.texi(,1718)
+../tar_texi/tar.texi(,1719) Here are some sample commands you might try which
will not work, and why
+../tar_texi/tar.texi(,1720) they won't work.
+../tar_texi/tar.texi(,1721)
+../tar_texi/tar.texi(,1722) If you try to use this command,
+../tar_texi/tar.texi(,1723)
+../tar_texi/tar.texi(,1724) @smallexample
+../tar_texi/tar.texi(,1725) $ @kbd{tar -xvf music.tar folk jazz}
+../tar_texi/tar.texi(,1726) @end smallexample
+../tar_texi/tar.texi(,1727)
+../tar_texi/tar.texi(,1728) @noindent
+../tar_texi/tar.texi(,1729) you will get the following response:
+../tar_texi/tar.texi(,1730)
+../tar_texi/tar.texi(,1731) @smallexample
+../tar_texi/tar.texi(,1732) tar: folk: Not found in archive
+../tar_texi/tar.texi(,1733) tar: jazz: Not found in archive
+../tar_texi/tar.texi(,1734) $
+../tar_texi/tar.texi(,1735) @end smallexample
+../tar_texi/tar.texi(,1736)
+../tar_texi/tar.texi(,1737) @noindent
+../tar_texi/tar.texi(,1738) This is because these files were not originally
@emph{in} the parent
+../tar_texi/tar.texi(,1739) directory @file{..}, where the archive is located;
they were in the
+../tar_texi/tar.texi(,1740) @file{practice} directory, and their file names
reflect this:
+../tar_texi/tar.texi(,1741)
+../tar_texi/tar.texi(,1742) @smallexample
+../tar_texi/tar.texi(,1743) $ @kbd{tar -tvf music.tar}
+../tar_texi/tar.texi(,1744) practice/folk
+../tar_texi/tar.texi(,1745) practice/jazz
+../tar_texi/tar.texi(,1746) practice/rock
+../tar_texi/tar.texi(,1747) @end smallexample
+../tar_texi/tar.texi(,1748)
+../tar_texi/tar.texi(FIXME,1750) @allow-recursion
+../tar_texi/tar.texi(FIXME,1750) @quote-arg
+../tar_texi/tar.texi(FIXME,1750)
+../tar_texi/tar.texi(,1751)
+../tar_texi/tar.texi(,1752) @noindent
+../tar_texi/tar.texi(,1753) Likewise, if you try to use this command,
+../tar_texi/tar.texi(,1754)
+../tar_texi/tar.texi(,1755) @smallexample
+../tar_texi/tar.texi(,1756) $ @kbd{tar -tvf music.tar folk jazz}
+../tar_texi/tar.texi(,1757) @end smallexample
+../tar_texi/tar.texi(,1758)
+../tar_texi/tar.texi(,1759) @noindent
+../tar_texi/tar.texi(,1760) you would get a similar response. Members with
those names are not in the
+../tar_texi/tar.texi(,1761) archive. You must use the correct member names,
or wildcards, in order
+../tar_texi/tar.texi(,1762) to extract the files from the archive.
+../tar_texi/tar.texi(,1763)
+../tar_texi/tar.texi(,1764) If you have forgotten the correct names of the
files in the archive,
+../tar_texi/tar.texi(,1765) use @address@hidden --list --verbose}} to list
them correctly.
+../tar_texi/tar.texi(,1766)
+../tar_texi/tar.texi(FIXME,1767) @allow-recursion
+../tar_texi/tar.texi(FIXME,1767) @quote-arg
+../tar_texi/tar.texi(FIXME,1767)
+../tar_texi/tar.texi(,1768)
+../tar_texi/tar.texi(,1769) @node going further
+../tar_texi/tar.texi(,1770) @section Going Further Ahead in this Manual
+../tar_texi/tar.texi(,1771)
+../tar_texi/tar.texi(FIXME,1773) @allow-recursion
+../tar_texi/tar.texi(FIXME,1773) @quote-arg
+../tar_texi/tar.texi(FIXME,1773)
+../tar_texi/tar.texi(,1774)
+../tar_texi/tar.texi(,1775) @node tar invocation
+../tar_texi/tar.texi(GNUTAR,1776) @chapter Invoking @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(UNREVISED,1777) @quotation
+../tar_texi/tar.texi(UNREVISED,1777) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,1777) @end quotation
+../tar_texi/tar.texi(UNREVISED,1777)
+../tar_texi/tar.texi(,1778)
+../tar_texi/tar.texi(GNUTAR,1779) This chapter is about how one invokes the
@acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,1780) command, from the command synopsis
(@pxref{Synopsis}). There are
+../tar_texi/tar.texi(,1781) numerous options, and many styles for writing
them. One mandatory
+../tar_texi/tar.texi(,1782) option specifies the operation @command{tar}
should perform
+../tar_texi/tar.texi(,1783) (@pxref{Operation Summary}), other options are
meant to detail how
+../tar_texi/tar.texi(,1784) this operation should be performed (@pxref{Option
Summary}).
+../tar_texi/tar.texi(,1785) Non-option arguments are not always interpreted
the same way,
+../tar_texi/tar.texi(,1786) depending on what the operation is.
+../tar_texi/tar.texi(,1787)
+../tar_texi/tar.texi(,1788) You will find in this chapter everything about
option styles and rules for
+../tar_texi/tar.texi(,1789) writing them (@pxref{Styles}). On the other hand,
operations and options
+../tar_texi/tar.texi(,1790) are fully described elsewhere, in other chapters.
Here, you will find
+../tar_texi/tar.texi(,1791) only synthetic descriptions for operations and
options, together with
+../tar_texi/tar.texi(,1792) pointers to other parts of the @command{tar}
manual.
+../tar_texi/tar.texi(,1793)
+../tar_texi/tar.texi(,1794) Some options are so special they are fully
described right in this
+../tar_texi/tar.texi(,1795) chapter. They have the effect of inhibiting the
normal operation of
+../tar_texi/tar.texi(,1796) @command{tar} or else, they globally alter the
amount of feedback the user
+../tar_texi/tar.texi(,1797) receives about what is going on. These are the
@option{--help} and
+../tar_texi/tar.texi(,1798) @option{--version} (@pxref{help}),
@option{--verbose} (@pxref{verbose})
+../tar_texi/tar.texi(,1799) and @option{--interactive} options
(@pxref{interactive}).
+../tar_texi/tar.texi(,1800)
+../tar_texi/tar.texi(,1801) @menu
+../tar_texi/tar.texi(,1802) * Synopsis::
+../tar_texi/tar.texi(,1803) * using tar options::
+../tar_texi/tar.texi(,1804) * Styles::
+../tar_texi/tar.texi(,1805) * All Options::
+../tar_texi/tar.texi(,1806) * help::
+../tar_texi/tar.texi(,1807) * defaults::
+../tar_texi/tar.texi(,1808) * verbose::
+../tar_texi/tar.texi(,1809) * interactive::
+../tar_texi/tar.texi(,1810) @end menu
+../tar_texi/tar.texi(,1811)
+../tar_texi/tar.texi(,1812) @node Synopsis
+../tar_texi/tar.texi(,1813) @section General Synopsis of @command{tar}
+../tar_texi/tar.texi(,1814)
+../tar_texi/tar.texi(GNUTAR,1815) The @acronym{GNU} @command{tar} program is
invoked as either one of:
+../tar_texi/tar.texi(,1816)
+../tar_texi/tar.texi(,1817) @smallexample
+../tar_texi/tar.texi(,1818) @kbd{tar @address@hidden address@hidden@dots{}}
+../tar_texi/tar.texi(,1819) @kbd{tar @address@hidden address@hidden@dots{}
address@hidden@dots{} address@hidden@dots{}}
+../tar_texi/tar.texi(,1820) @end smallexample
+../tar_texi/tar.texi(,1821)
+../tar_texi/tar.texi(,1822) The second form is for when old options are being
used.
+../tar_texi/tar.texi(,1823)
+../tar_texi/tar.texi(,1824) You can use @command{tar} to store files in an
archive, to extract them from
+../tar_texi/tar.texi(,1825) an archive, and to do other types of archive
manipulation. The primary
+../tar_texi/tar.texi(,1826) argument to @command{tar}, which is called the
@dfn{operation}, specifies
+../tar_texi/tar.texi(,1827) which action to take. The other arguments to
@command{tar} are either
+../tar_texi/tar.texi(,1828) @dfn{options}, which change the way @command{tar}
performs an operation,
+../tar_texi/tar.texi(,1829) or file names or archive members, which specify
the files or members
+../tar_texi/tar.texi(,1830) @command{tar} is to act on.
+../tar_texi/tar.texi(,1831)
+../tar_texi/tar.texi(,1832) You can actually type in arguments in any order,
even if in this manual
+../tar_texi/tar.texi(,1833) the options always precede the other arguments, to
make examples easier
+../tar_texi/tar.texi(,1834) to understand. Further, the option stating the
main operation mode
+../tar_texi/tar.texi(,1835) (the @command{tar} main command) is usually given
first.
+../tar_texi/tar.texi(,1836)
+../tar_texi/tar.texi(,1837) Each @var{name} in the synopsis above is
interpreted as an archive member
+../tar_texi/tar.texi(,1838) name when the main command is one of
@option{--compare}
+../tar_texi/tar.texi(,1839) (@option{--diff}, @option{-d}), @option{--delete},
@option{--extract}
+../tar_texi/tar.texi(,1840) (@option{--get}, @option{-x}), @option{--list}
(@option{-t}) or
+../tar_texi/tar.texi(,1841) @option{--update} (@option{-u}). When naming
archive members, you
+../tar_texi/tar.texi(,1842) must give the exact name of the member in the
archive, as it is
+../tar_texi/tar.texi(,1843) printed by @option{--list}. For @option{--append}
(@option{-r}) and
+../tar_texi/tar.texi(,1844) @option{--create} (@option{-c}), these @var{name}
arguments specify
+../tar_texi/tar.texi(,1845) the names of either files or directory hierarchies
to place in the archive.
+../tar_texi/tar.texi(,1846) These files or hierarchies should already exist in
the file system,
+../tar_texi/tar.texi(,1847) prior to the execution of the @command{tar}
command.
+../tar_texi/tar.texi(,1848)
+../tar_texi/tar.texi(,1849) @command{tar} interprets relative file names as
being relative to the
+../tar_texi/tar.texi(,1850) working directory. @command{tar} will make all
file names relative
+../tar_texi/tar.texi(,1851) (by removing leading slashes when archiving or
restoring files),
+../tar_texi/tar.texi(,1852) unless you specify otherwise (using the
@option{--absolute-names}
+../tar_texi/tar.texi(,1853) option). @xref{absolute}, for more information
about
+../tar_texi/tar.texi(,1854) @option{--absolute-names}.
+../tar_texi/tar.texi(,1855)
+../tar_texi/tar.texi(,1856) If you give the name of a directory as either a
file name or a member
+../tar_texi/tar.texi(,1857) name, then @command{tar} acts recursively on all
the files and directories
+../tar_texi/tar.texi(,1858) beneath that directory. For example, the name
@file{/} identifies all
+../tar_texi/tar.texi(,1859) the files in the file system to @command{tar}.
+../tar_texi/tar.texi(,1860)
+../tar_texi/tar.texi(,1861) The distinction between file names and archive
member names is especially
+../tar_texi/tar.texi(,1862) important when shell globbing is used, and
sometimes a source of confusion
+../tar_texi/tar.texi(,1863) for newcomers. @xref{wildcards}, for more
information about globbing.
+../tar_texi/tar.texi(,1864) The problem is that shells may only glob using
existing files in the
+../tar_texi/tar.texi(,1865) file system. Only @command{tar} itself may glob
on archive members, so when
+../tar_texi/tar.texi(,1866) needed, you must ensure that wildcard characters
reach @command{tar} without
+../tar_texi/tar.texi(,1867) being interpreted by the shell first. Using a
backslash before @samp{*}
+../tar_texi/tar.texi(,1868) or @samp{?}, or putting the whole argument between
quotes, is usually
+../tar_texi/tar.texi(,1869) sufficient for this.
+../tar_texi/tar.texi(,1870)
+../tar_texi/tar.texi(,1871) Even if @var{name}s are often specified on the
command line, they
+../tar_texi/tar.texi(,1872) can also be read from a text file in the file
system, using the
+../tar_texi/tar.texi(,1873) @address@hidden (@option{-T @var{file-of-names}})
option.
+../tar_texi/tar.texi(,1874)
+../tar_texi/tar.texi(,1875) If you don't use any file name arguments,
@option{--append} (@option{-r}),
+../tar_texi/tar.texi(,1876) @option{--delete} and @option{--concatenate}
(@option{--catenate},
+../tar_texi/tar.texi(,1877) @option{-A}) will do nothing, while
@option{--create} (@option{-c})
+../tar_texi/tar.texi(,1878) will usually yield a diagnostic and inhibit
@command{tar} execution.
+../tar_texi/tar.texi(,1879) The other operations of @command{tar}
(@option{--list},
+../tar_texi/tar.texi(,1880) @option{--extract}, @option{--compare}, and
@option{--update})
+../tar_texi/tar.texi(,1881) will act on the entire contents of the archive.
+../tar_texi/tar.texi(,1882)
+../tar_texi/tar.texi(,1883) @cindex exit status
+../tar_texi/tar.texi(,1884) @cindex return status
+../tar_texi/tar.texi(GNUTAR,1885) Besides successful exits, @acronym{GNU}
@command{tar} may fail for
+../tar_texi/tar.texi(,1886) many reasons. Some reasons correspond to bad
usage, that is, when the
+../tar_texi/tar.texi(,1887) @command{tar} command is improperly written.
Errors may be
+../tar_texi/tar.texi(,1888) encountered later, while encountering an error
processing the archive
+../tar_texi/tar.texi(,1889) or the files. Some errors are recoverable, in
which case the failure
+../tar_texi/tar.texi(,1890) is delayed until @command{tar} has completed all
its work. Some
+../tar_texi/tar.texi(,1891) errors are such that it would not meaningful, or
at least risky, to
+../tar_texi/tar.texi(,1892) continue processing: @command{tar} then aborts
processing immediately.
+../tar_texi/tar.texi(,1893) All abnormal exits, whether immediate or delayed,
should always be
+../tar_texi/tar.texi(,1894) clearly diagnosed on @code{stderr}, after a line
stating the nature of
+../tar_texi/tar.texi(,1895) the error.
+../tar_texi/tar.texi(,1896)
+../tar_texi/tar.texi(GNUTAR,1897) @acronym{GNU} @command{tar} returns only a
few exit statuses. I'm really
+../tar_texi/tar.texi(,1898) aiming simplicity in that area, for now. If you
are not using the
+../tar_texi/tar.texi(,1899) @option{--compare} @option{--diff}, @option{-d})
option, zero means
+../tar_texi/tar.texi(,1900) that everything went well, besides maybe innocuous
warnings. Nonzero
+../tar_texi/tar.texi(,1901) means that something went wrong. Right now, as of
today, ``nonzero''
+../tar_texi/tar.texi(,1902) is almost always 2, except for remote operations,
where it may be
+../tar_texi/tar.texi(,1903) 128.
+../tar_texi/tar.texi(,1904)
+../tar_texi/tar.texi(,1905) @node using tar options
+../tar_texi/tar.texi(,1906) @section Using @command{tar} Options
+../tar_texi/tar.texi(,1907)
+../tar_texi/tar.texi(GNUTAR,1908) @acronym{GNU} @command{tar} has a total of
eight operating modes which
+../tar_texi/tar.texi(,1909) allow you to perform a variety of tasks. You are
required to choose
+../tar_texi/tar.texi(,1910) one operating mode each time you employ the
@command{tar} program by
+../tar_texi/tar.texi(,1911) specifying one, and only one operation as an
argument to the
+../tar_texi/tar.texi(,1912) @command{tar} command (two lists of four
operations each may be found
+../tar_texi/tar.texi(,1913) at @ref{frequent operations} and
@ref{Operations}). Depending on
+../tar_texi/tar.texi(,1914) circumstances, you may also wish to customize how
the chosen operating
+../tar_texi/tar.texi(,1915) mode behaves. For example, you may wish to change
the way the output
+../tar_texi/tar.texi(,1916) looks, or the format of the files that you wish to
archive may require
+../tar_texi/tar.texi(,1917) you to do something special in order to make the
archive look right.
+../tar_texi/tar.texi(,1918)
+../tar_texi/tar.texi(,1919) You can customize and control @command{tar}'s
performance by running
+../tar_texi/tar.texi(,1920) @command{tar} with one or more options (such as
@option{--verbose}
+../tar_texi/tar.texi(,1921) (@option{-v}), which we used in the tutorial). As
we said in the
+../tar_texi/tar.texi(,1922) tutorial, @dfn{options} are arguments to
@command{tar} which are (as
+../tar_texi/tar.texi(,1923) their name suggests) optional. Depending on the
operating mode, you
+../tar_texi/tar.texi(,1924) may specify one or more options. Different options
will have different
+../tar_texi/tar.texi(,1925) effects, but in general they all change details of
the operation, such
+../tar_texi/tar.texi(,1926) as archive format, archive name, or level of user
interaction. Some
+../tar_texi/tar.texi(,1927) options make sense with all operating modes, while
others are
+../tar_texi/tar.texi(,1928) meaningful only with particular modes. You will
likely use some
+../tar_texi/tar.texi(,1929) options frequently, while you will only use others
infrequently, or
+../tar_texi/tar.texi(,1930) not at all. (A full list of options is available
in @pxref{All Options}.)
+../tar_texi/tar.texi(,1931)
+../tar_texi/tar.texi(,1932) @vrindex TAR_OPTIONS, environment variable
+../tar_texi/tar.texi(,1933) @anchor{TAR_OPTIONS}
+../tar_texi/tar.texi(,1934) The @env{TAR_OPTIONS} environment variable
specifies default options to
+../tar_texi/tar.texi(,1935) be placed in front of any explicit options. For
example, if
+../tar_texi/tar.texi(,1936) @code{TAR_OPTIONS} is @samp{-v --unlink-first},
@command{tar} behaves as
+../tar_texi/tar.texi(,1937) if the two options @option{-v} and
@option{--unlink-first} had been
+../tar_texi/tar.texi(,1938) specified before any explicit options. Option
specifications are
+../tar_texi/tar.texi(,1939) separated by whitespace. A backslash escapes the
next character, so it
+../tar_texi/tar.texi(,1940) can be used to specify an option containing
whitespace or a backslash.
+../tar_texi/tar.texi(,1941)
+../tar_texi/tar.texi(,1942) Note that @command{tar} options are case
sensitive. For example, the
+../tar_texi/tar.texi(,1943) options @option{-T} and @option{-t} are different;
the first requires an
+../tar_texi/tar.texi(,1944) argument for stating the name of a file providing
a list of @var{name}s,
+../tar_texi/tar.texi(,1945) while the second does not require an argument and
is another way to
+../tar_texi/tar.texi(,1946) write @option{--list} (@option{-t}).
+../tar_texi/tar.texi(,1947)
+../tar_texi/tar.texi(,1948) In addition to the eight operations, there are
many options to
+../tar_texi/tar.texi(,1949) @command{tar}, and three different styles for
writing both: long (mnemonic)
+../tar_texi/tar.texi(,1950) form, short form, and old style. These styles are
discussed below.
+../tar_texi/tar.texi(,1951) Both the options and the operations can be written
in any of these three
+../tar_texi/tar.texi(,1952) styles.
+../tar_texi/tar.texi(,1953)
+../tar_texi/tar.texi(FIXME,1956) @allow-recursion
+../tar_texi/tar.texi(FIXME,1956) @quote-arg
+../tar_texi/tar.texi(FIXME,1956)
+../tar_texi/tar.texi(,1957)
+../tar_texi/tar.texi(,1958) @node Styles
+../tar_texi/tar.texi(,1959) @section The Three Option Styles
+../tar_texi/tar.texi(,1960)
+../tar_texi/tar.texi(,1961) There are three styles for writing operations and
options to the command
+../tar_texi/tar.texi(,1962) line invoking @command{tar}. The different styles
were developed at
+../tar_texi/tar.texi(,1963) different times during the history of
@command{tar}. These styles will be
+../tar_texi/tar.texi(,1964) presented below, from the most recent to the
oldest.
+../tar_texi/tar.texi(,1965)
+../tar_texi/tar.texi(,1966) Some options must take an argument. (For example,
@option{--file}
+../tar_texi/tar.texi(,1967) (@option{-f})) takes the name of an archive file
as an argument. If
+../tar_texi/tar.texi(,1968) you do not supply an archive file name,
@command{tar} will use a
+../tar_texi/tar.texi(,1969) default, but this can be confusing; thus, we
recommend that you always
+../tar_texi/tar.texi(,1970) supply a specific archive file name.) Where you
@emph{place} the
+../tar_texi/tar.texi(,1971) arguments generally depends on which style of
options you choose. We
+../tar_texi/tar.texi(,1972) will detail specific information relevant to each
option style in the
+../tar_texi/tar.texi(,1973) sections on the different option styles, below.
The differences are
+../tar_texi/tar.texi(,1974) subtle, yet can often be very important; incorrect
option placement
+../tar_texi/tar.texi(,1975) can cause you to overwrite a number of important
files. We urge you
+../tar_texi/tar.texi(,1976) to note these differences, and only use the option
style(s) which
+../tar_texi/tar.texi(,1977) makes the most sense to you until you feel
comfortable with the others.
+../tar_texi/tar.texi(,1978)
+../tar_texi/tar.texi(,1979) Some options @emph{may} take an argument. Such
options may have at
+../tar_texi/tar.texi(,1980) most long and short forms, they do not have old
style equivalent. The
+../tar_texi/tar.texi(,1981) rules for specifying an argument for such options
are stricter than
+../tar_texi/tar.texi(,1982) those for specifying mandatory arguments. Please,
pay special
+../tar_texi/tar.texi(,1983) attention to them.
+../tar_texi/tar.texi(,1984)
+../tar_texi/tar.texi(,1985) @menu
+../tar_texi/tar.texi(,1986) * Long Options:: Long Option Style
+../tar_texi/tar.texi(,1987) * Short Options:: Short Option Style
+../tar_texi/tar.texi(,1988) * Old Options:: Old Option Style
+../tar_texi/tar.texi(,1989) * Mixing:: Mixing Option
Styles
+../tar_texi/tar.texi(,1990) @end menu
+../tar_texi/tar.texi(,1991)
+../tar_texi/tar.texi(,1992) @node Long Options
+../tar_texi/tar.texi(,1993) @subsection Long Option Style
+../tar_texi/tar.texi(,1994)
+../tar_texi/tar.texi(,1995) Each option has at least one @dfn{long} (or
@dfn{mnemonic}) name starting with two
+../tar_texi/tar.texi(,1996) dashes in a row, e.g., @option{--list}. The long
names are more clear than
+../tar_texi/tar.texi(,1997) their corresponding short or old names. It
sometimes happens that a
+../tar_texi/tar.texi(,1998) single long option has many different different
names which are
+../tar_texi/tar.texi(,1999) synonymous, such as @option{--compare} and
@option{--diff}. In addition,
+../tar_texi/tar.texi(,2000) long option names can be given unique
abbreviations. For example,
+../tar_texi/tar.texi(,2001) @option{--cre} can be used in place of
@option{--create} because there is no
+../tar_texi/tar.texi(,2002) other long option which begins with @samp{cre}.
(One way to find
+../tar_texi/tar.texi(,2003) this out is by trying it and seeing what happens;
if a particular
+../tar_texi/tar.texi(,2004) abbreviation could represent more than one option,
@command{tar} will tell
+../tar_texi/tar.texi(,2005) you that that abbreviation is ambiguous and you'll
know that that
+../tar_texi/tar.texi(,2006) abbreviation won't work. You may also choose to
run @samp{tar --help}
+../tar_texi/tar.texi(,2007) to see a list of options. Be aware that if you
run @command{tar} with a
+../tar_texi/tar.texi(,2008) unique abbreviation for the long name of an option
you didn't want to
+../tar_texi/tar.texi(,2009) use, you are stuck; @command{tar} will perform the
command as ordered.)
+../tar_texi/tar.texi(,2010)
+../tar_texi/tar.texi(,2011) Long options are meant to be obvious and easy to
remember, and their
+../tar_texi/tar.texi(,2012) meanings are generally easier to discern than
those of their
+../tar_texi/tar.texi(,2013) corresponding short options (see below). For
example:
+../tar_texi/tar.texi(,2014)
+../tar_texi/tar.texi(,2015) @smallexample
+../tar_texi/tar.texi(,2016) $ @kbd{tar --create --verbose --blocking-factor=20
--file=/dev/rmt0}
+../tar_texi/tar.texi(,2017) @end smallexample
+../tar_texi/tar.texi(,2018)
+../tar_texi/tar.texi(,2019) @noindent
+../tar_texi/tar.texi(,2020) gives a fairly good set of hints about what the
command does, even
+../tar_texi/tar.texi(,2021) for those not fully acquainted with @command{tar}.
+../tar_texi/tar.texi(,2022)
+../tar_texi/tar.texi(,2023) Long options which require arguments take those
arguments
+../tar_texi/tar.texi(,2024) immediately following the option name. There are
two ways of
+../tar_texi/tar.texi(,2025) specifying a mandatory argument. It can be
separated from the
+../tar_texi/tar.texi(,2026) option name either by an equal sign, or by any
amount of
+../tar_texi/tar.texi(,2027) white space characters. For example, the
@option{--file} option (which
+../tar_texi/tar.texi(,2028) tells the name of the @command{tar} archive) is
given a file such as
+../tar_texi/tar.texi(,2029) @file{archive.tar} as argument by using any of the
following notations:
+../tar_texi/tar.texi(,2030) @option{--file=archive.tar} or @option{--file
archive.tar}.
+../tar_texi/tar.texi(,2031)
+../tar_texi/tar.texi(,2032) In contrast, optional arguments must always be
introduced using
+../tar_texi/tar.texi(,2033) an equal sign. For example, the @option{--backup}
option takes
+../tar_texi/tar.texi(,2034) an optional argument specifying backup type. It
must be used
+../tar_texi/tar.texi(,2035) as @address@hidden
+../tar_texi/tar.texi(,2036)
+../tar_texi/tar.texi(,2037) @node Short Options
+../tar_texi/tar.texi(,2038) @subsection Short Option Style
+../tar_texi/tar.texi(,2039)
+../tar_texi/tar.texi(,2040) Most options also have a @dfn{short option} name.
Short options start with
+../tar_texi/tar.texi(,2041) a single dash, and are followed by a single
character, e.g., @option{-t}
+../tar_texi/tar.texi(,2042) (which is equivalent to @option{--list}). The
forms are absolutely
+../tar_texi/tar.texi(,2043) identical in function; they are interchangeable.
+../tar_texi/tar.texi(,2044)
+../tar_texi/tar.texi(,2045) The short option names are faster to type than
long option names.
+../tar_texi/tar.texi(,2046)
+../tar_texi/tar.texi(,2047) Short options which require arguments take their
arguments immediately
+../tar_texi/tar.texi(,2048) following the option, usually separated by white
space. It is also
+../tar_texi/tar.texi(,2049) possible to stick the argument right after the
short option name, using
+../tar_texi/tar.texi(,2050) no intervening space. For example, you might
write @address@hidden
+../tar_texi/tar.texi(,2051) archive.tar}} or @option{-farchive.tar} instead of
using
+../tar_texi/tar.texi(,2052) @option{--file=archive.tar}. Both @address@hidden
and
+../tar_texi/tar.texi(,2053) @address@hidden @var{archive-name}}} denote the
option which indicates a
+../tar_texi/tar.texi(,2054) specific archive, here named @file{archive.tar}.
+../tar_texi/tar.texi(,2055)
+../tar_texi/tar.texi(,2056) Short options which take optional arguments take
their arguments
+../tar_texi/tar.texi(,2057) immediately following the option letter,
@emph{without any intervening
+../tar_texi/tar.texi(,2058) white space characters}.
+../tar_texi/tar.texi(,2059)
+../tar_texi/tar.texi(,2060) Short options' letters may be clumped together,
but you are not
+../tar_texi/tar.texi(,2061) required to do this (as compared to old options;
see below). When
+../tar_texi/tar.texi(,2062) short options are clumped as a set, use one
(single) dash for them
+../tar_texi/tar.texi(,2063) all, e.g., @address@hidden@command{tar} -cvf}}.
Only the last option in
+../tar_texi/tar.texi(,2064) such a set is allowed to have an address@hidden
many
+../tar_texi/tar.texi(,2065) options, the last of which has an argument, is a
rather opaque way to
+../tar_texi/tar.texi(,2066) write options. Some wonder if @acronym{GNU}
@code{getopt} should not
+../tar_texi/tar.texi(,2067) even be made helpful enough for considering such
usages as invalid.}.
+../tar_texi/tar.texi(,2068)
+../tar_texi/tar.texi(,2069) When the options are separated, the argument for
each option which requires
+../tar_texi/tar.texi(,2070) an argument directly follows that option, as is
usual for Unix programs.
+../tar_texi/tar.texi(,2071) For example:
+../tar_texi/tar.texi(,2072)
+../tar_texi/tar.texi(,2073) @smallexample
+../tar_texi/tar.texi(,2074) $ @kbd{tar -c -v -b 20 -f /dev/rmt0}
+../tar_texi/tar.texi(,2075) @end smallexample
+../tar_texi/tar.texi(,2076)
+../tar_texi/tar.texi(,2077) If you reorder short options' locations, be sure
to move any arguments
+../tar_texi/tar.texi(,2078) that belong to them. If you do not move the
arguments properly, you may
+../tar_texi/tar.texi(,2079) end up overwriting files.
+../tar_texi/tar.texi(,2080)
+../tar_texi/tar.texi(,2081) @node Old Options
+../tar_texi/tar.texi(,2082) @subsection Old Option Style
+../tar_texi/tar.texi(UNREVISED,2083) @quotation
+../tar_texi/tar.texi(UNREVISED,2083) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,2083) @end quotation
+../tar_texi/tar.texi(UNREVISED,2083)
+../tar_texi/tar.texi(,2084)
+../tar_texi/tar.texi(,2085) Like short options, @dfn{old options} are single
letters. However, old options
+../tar_texi/tar.texi(,2086) must be written together as a single clumped set,
without spaces separating
+../tar_texi/tar.texi(,2087) them or dashes preceding address@hidden that if
you precede options
+../tar_texi/tar.texi(,2088) with a dash, you are announcing the short option
style instead of the
+../tar_texi/tar.texi(,2089) old option style; short options are decoded
differently.}. This set
+../tar_texi/tar.texi(,2090) of letters must be the first to appear on the
command line, after the
+../tar_texi/tar.texi(,2091) @command{tar} program name and some white space;
old options cannot appear
+../tar_texi/tar.texi(,2092) anywhere else. The letter of an old option is
exactly the same letter as
+../tar_texi/tar.texi(,2093) the corresponding short option. For example, the
old option @samp{t} is
+../tar_texi/tar.texi(,2094) the same as the short option @option{-t}, and
consequently, the same as the
+../tar_texi/tar.texi(,2095) long option @option{--list}. So for example, the
command @address@hidden
+../tar_texi/tar.texi(,2096) cv}} specifies the option @option{-v} in addition
to the operation @option{-c}.
+../tar_texi/tar.texi(,2097)
+../tar_texi/tar.texi(,2098) When options that need arguments are given
together with the command,
+../tar_texi/tar.texi(,2099) all the associated arguments follow, in the same
order as the options.
+../tar_texi/tar.texi(,2100) Thus, the example given previously could also be
written in the old
+../tar_texi/tar.texi(,2101) style as follows:
+../tar_texi/tar.texi(,2102)
+../tar_texi/tar.texi(,2103) @smallexample
+../tar_texi/tar.texi(,2104) $ @kbd{tar cvbf 20 /dev/rmt0}
+../tar_texi/tar.texi(,2105) @end smallexample
+../tar_texi/tar.texi(,2106)
+../tar_texi/tar.texi(,2107) @noindent
+../tar_texi/tar.texi(,2108) Here, @samp{20} is the argument of @option{-b} and
@samp{/dev/rmt0} is
+../tar_texi/tar.texi(,2109) the argument of @option{-f}.
+../tar_texi/tar.texi(,2110)
+../tar_texi/tar.texi(,2111) On the other hand, this old style syntax makes it
difficult to match
+../tar_texi/tar.texi(,2112) option letters with their corresponding arguments,
and is often
+../tar_texi/tar.texi(,2113) confusing. In the command @address@hidden cvbf 20
/dev/rmt0}}, for example,
+../tar_texi/tar.texi(,2114) @samp{20} is the argument for @option{-b},
@samp{/dev/rmt0} is the
+../tar_texi/tar.texi(,2115) argument for @option{-f}, and @option{-v} does not
have a corresponding
+../tar_texi/tar.texi(,2116) argument. Even using short options like in
@address@hidden -c -v -b 20 -f
+../tar_texi/tar.texi(,2117) /dev/rmt0}} is clearer, putting all arguments next
to the option they
+../tar_texi/tar.texi(,2118) pertain to.
+../tar_texi/tar.texi(,2119)
+../tar_texi/tar.texi(,2120) If you want to reorder the letters in the old
option argument, be
+../tar_texi/tar.texi(,2121) sure to reorder any corresponding argument
appropriately.
+../tar_texi/tar.texi(,2122)
+../tar_texi/tar.texi(,2123) This old way of writing @command{tar} options can
surprise even experienced
+../tar_texi/tar.texi(,2124) users. For example, the two commands:
+../tar_texi/tar.texi(,2125)
+../tar_texi/tar.texi(,2126) @smallexample
+../tar_texi/tar.texi(,2127) @kbd{tar cfz archive.tar.gz file}
+../tar_texi/tar.texi(,2128) @kbd{tar -cfz archive.tar.gz file}
+../tar_texi/tar.texi(,2129) @end smallexample
+../tar_texi/tar.texi(,2130)
+../tar_texi/tar.texi(,2131) @noindent
+../tar_texi/tar.texi(,2132) are quite different. The first example uses
@file{archive.tar.gz} as
+../tar_texi/tar.texi(,2133) the value for option @samp{f} and recognizes the
option @samp{z}. The
+../tar_texi/tar.texi(,2134) second example, however, uses @file{z} as the
value for option
+../tar_texi/tar.texi(,2135) @samp{f} --- probably not what was intended.
+../tar_texi/tar.texi(,2136)
+../tar_texi/tar.texi(,2137) Old options are kept for compatibility with old
versions of @command{tar}.
+../tar_texi/tar.texi(,2138)
+../tar_texi/tar.texi(,2139) This second example could be corrected in many
ways, among which the
+../tar_texi/tar.texi(,2140) following are equivalent:
+../tar_texi/tar.texi(,2141)
+../tar_texi/tar.texi(,2142) @smallexample
+../tar_texi/tar.texi(,2143) @kbd{tar -czf archive.tar.gz file}
+../tar_texi/tar.texi(,2144) @kbd{tar -cf archive.tar.gz -z file}
+../tar_texi/tar.texi(,2145) @kbd{tar cf archive.tar.gz -z file}
+../tar_texi/tar.texi(,2146) @end smallexample
+../tar_texi/tar.texi(,2147)
+../tar_texi/tar.texi(,2148) @cindex option syntax, traditional
+../tar_texi/tar.texi(,2149) As far as we know, all @command{tar} programs,
@acronym{GNU} and
+../tar_texi/tar.texi(GNUTAR,2150) address@hidden, support old options.
@acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,2151) supports them not only for historical reasons, but
also because many
+../tar_texi/tar.texi(,2152) people are used to them. For compatibility with
Unix @command{tar},
+../tar_texi/tar.texi(,2153) the first argument is always treated as containing
command and option
+../tar_texi/tar.texi(,2154) letters even if it doesn't start with @samp{-}.
Thus, @samp{tar c} is
+../tar_texi/tar.texi(,2155) equivalent to @address@hidden -c}:} both of them
specify the
+../tar_texi/tar.texi(,2156) @option{--create} (@option{-c}) command to create
an archive.
+../tar_texi/tar.texi(,2157)
+../tar_texi/tar.texi(,2158) @node Mixing
+../tar_texi/tar.texi(,2159) @subsection Mixing Option Styles
+../tar_texi/tar.texi(,2160)
+../tar_texi/tar.texi(,2161) All three styles may be intermixed in a single
@command{tar} command,
+../tar_texi/tar.texi(,2162) so long as the rules for each style are fully
+../tar_texi/tar.texi(GNUTAR,2163) address@hidden @acronym{GNU} @command{tar}
version 1.11.6,
+../tar_texi/tar.texi(,2164) a bug prevented intermixing old style options with
long options in
+../tar_texi/tar.texi(,2165) some cases.}. Old style options and either of the
modern styles of
+../tar_texi/tar.texi(,2166) options may be mixed within a single @command{tar}
command. However,
+../tar_texi/tar.texi(,2167) old style options must be introduced as the first
arguments only,
+../tar_texi/tar.texi(,2168) following the rule for old options (old options
must appear directly
+../tar_texi/tar.texi(,2169) after the @command{tar} command and some white
space). Modern options
+../tar_texi/tar.texi(,2170) may be given only after all arguments to the old
options have been
+../tar_texi/tar.texi(,2171) collected. If this rule is not respected, a
modern option might be
+../tar_texi/tar.texi(,2172) falsely interpreted as the value of the argument
to one of the old
+../tar_texi/tar.texi(,2173) style options.
+../tar_texi/tar.texi(,2174)
+../tar_texi/tar.texi(,2175) For example, all the following commands are wholly
equivalent, and
+../tar_texi/tar.texi(,2176) illustrate the many combinations and orderings of
option styles.
+../tar_texi/tar.texi(,2177)
+../tar_texi/tar.texi(,2178) @smallexample
+../tar_texi/tar.texi(,2179) @kbd{tar --create --file=archive.tar}
+../tar_texi/tar.texi(,2180) @kbd{tar --create -f archive.tar}
+../tar_texi/tar.texi(,2181) @kbd{tar --create -farchive.tar}
+../tar_texi/tar.texi(,2182) @kbd{tar --file=archive.tar --create}
+../tar_texi/tar.texi(,2183) @kbd{tar --file=archive.tar -c}
+../tar_texi/tar.texi(,2184) @kbd{tar -c --file=archive.tar}
+../tar_texi/tar.texi(,2185) @kbd{tar -c -f archive.tar}
+../tar_texi/tar.texi(,2186) @kbd{tar -c -farchive.tar}
+../tar_texi/tar.texi(,2187) @kbd{tar -cf archive.tar}
+../tar_texi/tar.texi(,2188) @kbd{tar -cfarchive.tar}
+../tar_texi/tar.texi(,2189) @kbd{tar -f archive.tar --create}
+../tar_texi/tar.texi(,2190) @kbd{tar -f archive.tar -c}
+../tar_texi/tar.texi(,2191) @kbd{tar -farchive.tar --create}
+../tar_texi/tar.texi(,2192) @kbd{tar -farchive.tar -c}
+../tar_texi/tar.texi(,2193) @kbd{tar c --file=archive.tar}
+../tar_texi/tar.texi(,2194) @kbd{tar c -f archive.tar}
+../tar_texi/tar.texi(,2195) @kbd{tar c -farchive.tar}
+../tar_texi/tar.texi(,2196) @kbd{tar cf archive.tar}
+../tar_texi/tar.texi(,2197) @kbd{tar f archive.tar --create}
+../tar_texi/tar.texi(,2198) @kbd{tar f archive.tar -c}
+../tar_texi/tar.texi(,2199) @kbd{tar fc archive.tar}
+../tar_texi/tar.texi(,2200) @end smallexample
+../tar_texi/tar.texi(,2201)
+../tar_texi/tar.texi(,2202) On the other hand, the following commands are
@emph{not} equivalent to
+../tar_texi/tar.texi(,2203) the previous set:
+../tar_texi/tar.texi(,2204)
+../tar_texi/tar.texi(,2205) @smallexample
+../tar_texi/tar.texi(,2206) @kbd{tar -f -c archive.tar}
+../tar_texi/tar.texi(,2207) @kbd{tar -fc archive.tar}
+../tar_texi/tar.texi(,2208) @kbd{tar -fcarchive.tar}
+../tar_texi/tar.texi(,2209) @kbd{tar -farchive.tarc}
+../tar_texi/tar.texi(,2210) @kbd{tar cfarchive.tar}
+../tar_texi/tar.texi(,2211) @end smallexample
+../tar_texi/tar.texi(,2212)
+../tar_texi/tar.texi(,2213) @noindent
+../tar_texi/tar.texi(,2214) These last examples mean something completely
different from what the
+../tar_texi/tar.texi(,2215) user intended (judging based on the example in the
previous set which
+../tar_texi/tar.texi(,2216) uses long options, whose intent is therefore very
clear). The first
+../tar_texi/tar.texi(,2217) four specify that the @command{tar} archive would
be a file named
+../tar_texi/tar.texi(,2218) @option{-c}, @samp{c}, @samp{carchive.tar} or
@samp{archive.tarc},
+../tar_texi/tar.texi(,2219) respectively. The first two examples also specify
a single non-option,
+../tar_texi/tar.texi(,2220) @var{name} argument having the value
@samp{archive.tar}. The last
+../tar_texi/tar.texi(,2221) example contains only old style option letters
(repeating option
+../tar_texi/tar.texi(,2222) @samp{c} twice), not all of which are meaningful
(eg., @samp{.},
+../tar_texi/tar.texi(FIXME,2224) @samp{h}, or @samp{i}), with no argument
value. @allow-recursion
+../tar_texi/tar.texi(FIXME,2224) @quote-arg
+../tar_texi/tar.texi(FIXME,2224)
+../tar_texi/tar.texi(,2225)
+../tar_texi/tar.texi(,2226) @node All Options
+../tar_texi/tar.texi(,2227) @section All @command{tar} Options
+../tar_texi/tar.texi(,2228)
+../tar_texi/tar.texi(,2229) The coming manual sections contain an alphabetical
listing of all
+../tar_texi/tar.texi(,2230) @command{tar} operations and options, with brief
descriptions and cross
+../tar_texi/tar.texi(,2231) references to more in-depth explanations in the
body of the manual.
+../tar_texi/tar.texi(,2232) They also contain an alphabetically arranged table
of the short option
+../tar_texi/tar.texi(,2233) forms with their corresponding long option. You
can use this table as
+../tar_texi/tar.texi(,2234) a reference for deciphering @command{tar} commands
in scripts.
+../tar_texi/tar.texi(,2235)
+../tar_texi/tar.texi(,2236) @menu
+../tar_texi/tar.texi(,2237) * Operation Summary::
+../tar_texi/tar.texi(,2238) * Option Summary::
+../tar_texi/tar.texi(,2239) * Short Option Summary::
+../tar_texi/tar.texi(,2240) @end menu
+../tar_texi/tar.texi(,2241)
+../tar_texi/tar.texi(,2242) @node Operation Summary
+../tar_texi/tar.texi(,2243) @subsection Operations
+../tar_texi/tar.texi(,2244)
+../tar_texi/tar.texi(,2245) @table @option
+../tar_texi/tar.texi(,2246)
+../tar_texi/tar.texi(opsummary,2247) @anchor{--append}
+../tar_texi/tar.texi(opsummary,2247) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2248) @item --append
+../tar_texi/tar.texi(,2249) @itemx -r
+../tar_texi/tar.texi(,2250)
+../tar_texi/tar.texi(,2251) Appends files to the end of the archive.
@xref{append}.
+../tar_texi/tar.texi(,2252)
+../tar_texi/tar.texi(opsummary,2253) @anchor{--catenate}
+../tar_texi/tar.texi(opsummary,2253) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2254) @item --catenate
+../tar_texi/tar.texi(,2255) @itemx -A
+../tar_texi/tar.texi(,2256)
+../tar_texi/tar.texi(,2257) Same as @option{--concatenate}.
@xref{concatenate}.
+../tar_texi/tar.texi(,2258)
+../tar_texi/tar.texi(opsummary,2259) @anchor{--compare}
+../tar_texi/tar.texi(opsummary,2259) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2260) @item --compare
+../tar_texi/tar.texi(,2261) @itemx -d
+../tar_texi/tar.texi(,2262)
+../tar_texi/tar.texi(,2263) Compares archive members with their counterparts
in the file
+../tar_texi/tar.texi(,2264) system, and reports differences in file size,
mode, owner,
+../tar_texi/tar.texi(,2265) modification date and contents. @xref{compare}.
+../tar_texi/tar.texi(,2266)
+../tar_texi/tar.texi(opsummary,2267) @anchor{--concatenate}
+../tar_texi/tar.texi(opsummary,2267) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2268) @item --concatenate
+../tar_texi/tar.texi(,2269) @itemx -A
+../tar_texi/tar.texi(,2270)
+../tar_texi/tar.texi(,2271) Appends other @command{tar} archives to the end of
the archive.
+../tar_texi/tar.texi(,2272) @xref{concatenate}.
+../tar_texi/tar.texi(,2273)
+../tar_texi/tar.texi(opsummary,2274) @anchor{--create}
+../tar_texi/tar.texi(opsummary,2274) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2275) @item --create
+../tar_texi/tar.texi(,2276) @itemx -c
+../tar_texi/tar.texi(,2277)
+../tar_texi/tar.texi(,2278) Creates a new @command{tar} archive.
@xref{create}.
+../tar_texi/tar.texi(,2279)
+../tar_texi/tar.texi(opsummary,2280) @anchor{--delete}
+../tar_texi/tar.texi(opsummary,2280) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2281) @item --delete
+../tar_texi/tar.texi(,2282)
+../tar_texi/tar.texi(,2283) Deletes members from the archive. Don't try this
on a archive on a
+../tar_texi/tar.texi(,2284) tape! @xref{delete}.
+../tar_texi/tar.texi(,2285)
+../tar_texi/tar.texi(opsummary,2286) @anchor{--diff}
+../tar_texi/tar.texi(opsummary,2286) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2287) @item --diff
+../tar_texi/tar.texi(,2288) @itemx -d
+../tar_texi/tar.texi(,2289)
+../tar_texi/tar.texi(,2290) Same @option{--compare}. @xref{compare}.
+../tar_texi/tar.texi(,2291)
+../tar_texi/tar.texi(opsummary,2292) @anchor{--extract}
+../tar_texi/tar.texi(opsummary,2292) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2293) @item --extract
+../tar_texi/tar.texi(,2294) @itemx -x
+../tar_texi/tar.texi(,2295)
+../tar_texi/tar.texi(,2296) Extracts members from the archive into the file
system. @xref{extract}.
+../tar_texi/tar.texi(,2297)
+../tar_texi/tar.texi(opsummary,2298) @anchor{--get}
+../tar_texi/tar.texi(opsummary,2298) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2299) @item --get
+../tar_texi/tar.texi(,2300) @itemx -x
+../tar_texi/tar.texi(,2301)
+../tar_texi/tar.texi(,2302) Same as @option{--extract}. @xref{extract}.
+../tar_texi/tar.texi(,2303)
+../tar_texi/tar.texi(opsummary,2304) @anchor{--list}
+../tar_texi/tar.texi(opsummary,2304) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2305) @item --list
+../tar_texi/tar.texi(,2306) @itemx -t
+../tar_texi/tar.texi(,2307)
+../tar_texi/tar.texi(,2308) Lists the members in an archive. @xref{list}.
+../tar_texi/tar.texi(,2309)
+../tar_texi/tar.texi(opsummary,2310) @anchor{--update}
+../tar_texi/tar.texi(opsummary,2310) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2311) @item --update
+../tar_texi/tar.texi(,2312) @itemx -u
+../tar_texi/tar.texi(,2313)
+../tar_texi/tar.texi(,2314) Adds files to the end of the archive, but only if
they are newer than
+../tar_texi/tar.texi(,2315) their counterparts already in the archive, or if
they do not already
+../tar_texi/tar.texi(,2316) exist in the archive. @xref{update}.
+../tar_texi/tar.texi(,2317)
+../tar_texi/tar.texi(,2318) @end table
+../tar_texi/tar.texi(,2319)
+../tar_texi/tar.texi(,2320) @node Option Summary
+../tar_texi/tar.texi(,2321) @subsection @command{tar} Options
+../tar_texi/tar.texi(,2322)
+../tar_texi/tar.texi(,2323) @table @option
+../tar_texi/tar.texi(,2324)
+../tar_texi/tar.texi(opsummary,2325) @anchor{--absolute-names}
+../tar_texi/tar.texi(opsummary,2325) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2326) @item --absolute-names
+../tar_texi/tar.texi(,2327) @itemx -P
+../tar_texi/tar.texi(,2328)
+../tar_texi/tar.texi(,2329) Normally when creating an archive, @command{tar}
strips an initial
+../tar_texi/tar.texi(,2330) @samp{/} from member names. This option disables
that behavior.
+../tar_texi/tar.texi(,2331) @xref{absolute}.
+../tar_texi/tar.texi(,2332)
+../tar_texi/tar.texi(opsummary,2333) @anchor{--after-date}
+../tar_texi/tar.texi(opsummary,2333) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2334) @item --after-date
+../tar_texi/tar.texi(,2335)
+../tar_texi/tar.texi(,2336) (See @option{--newer}, @pxref{after})
+../tar_texi/tar.texi(,2337)
+../tar_texi/tar.texi(opsummary,2338) @anchor{--anchored}
+../tar_texi/tar.texi(opsummary,2338) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2339) @item --anchored
+../tar_texi/tar.texi(,2340) A pattern must match an initial subsequence of the
name's components.
+../tar_texi/tar.texi(,2341) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2342)
+../tar_texi/tar.texi(opsummary,2343) @anchor{--atime-preserve}
+../tar_texi/tar.texi(opsummary,2343) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2344) @item --atime-preserve
+../tar_texi/tar.texi(,2345) @itemx --atime-preserve=replace
+../tar_texi/tar.texi(,2346) @itemx --atime-preserve=system
+../tar_texi/tar.texi(,2347)
+../tar_texi/tar.texi(,2348) Attempt to preserve the access time of files when
reading them. This
+../tar_texi/tar.texi(,2349) option currently is effective only on files that
you own, unless you
+../tar_texi/tar.texi(,2350) have superuser privileges.
+../tar_texi/tar.texi(,2351)
+../tar_texi/tar.texi(,2352) @option{--atime-preserve=replace} remembers the
access time of a file
+../tar_texi/tar.texi(,2353) before reading it, and then restores the access
time afterwards. This
+../tar_texi/tar.texi(,2354) may cause problems if other programs are reading
the file at the same
+../tar_texi/tar.texi(,2355) time, as the times of their accesses will be lost.
On most platforms
+../tar_texi/tar.texi(,2356) restoring the access time also requires
@command{tar} to restore the
+../tar_texi/tar.texi(,2357) data modification time too, so this option may
also cause problems if
+../tar_texi/tar.texi(,2358) other programs are writing the file at the same
time. (Tar attempts
+../tar_texi/tar.texi(,2359) to detect this situation, but cannot do so
reliably due to race
+../tar_texi/tar.texi(,2360) conditions.) Worse, on most platforms restoring
the access time also
+../tar_texi/tar.texi(,2361) updates the status change time, which means that
this option is
+../tar_texi/tar.texi(,2362) incompatible with incremental backups.
+../tar_texi/tar.texi(,2363)
+../tar_texi/tar.texi(,2364) @option{--atime-preserve=system} avoids changing
time stamps on files,
+../tar_texi/tar.texi(,2365) without interfering with time stamp updates
+../tar_texi/tar.texi(,2366) caused by other programs, so it works better with
incremental backups.
+../tar_texi/tar.texi(,2367) However, it requires a special @code{O_NOATIME}
option from the
+../tar_texi/tar.texi(,2368) underlying operating and file system
implementation, and it also requires
+../tar_texi/tar.texi(,2369) that searching directories does not update their
access times. As of
+../tar_texi/tar.texi(,2370) this writing (November 2005) this works only with
Linux, and only with
+../tar_texi/tar.texi(,2371) Linux kernels 2.6.8 and later. Worse, there is
currently no reliable
+../tar_texi/tar.texi(,2372) way to know whether this feature actually works.
Sometimes
+../tar_texi/tar.texi(,2373) @command{tar} knows that it does not work, and if
you use
+../tar_texi/tar.texi(,2374) @option{--atime-preserve=system} then
@command{tar} complains and
+../tar_texi/tar.texi(,2375) exits right away. But other times @command{tar}
might think that the
+../tar_texi/tar.texi(,2376) option works when it actually does not.
+../tar_texi/tar.texi(,2377)
+../tar_texi/tar.texi(,2378) Currently @option{--atime-preserve} with no
operand defaults to
+../tar_texi/tar.texi(,2379) @option{--atime-preserve=replace}, but this may
change in the future
+../tar_texi/tar.texi(,2380) as support for @option{--atime-preserve=system}
improves.
+../tar_texi/tar.texi(,2381)
+../tar_texi/tar.texi(,2382) If your operating system does not support
+../tar_texi/tar.texi(,2383) @address@hidden, you might be able to preserve
access
+../tar_texi/tar.texi(,2384) times reliably by by using the @command{mount}
command. For example,
+../tar_texi/tar.texi(,2385) you can mount the file system read-only, or access
the file system via
+../tar_texi/tar.texi(,2386) a read-only loopback mount, or use the
@samp{noatime} mount option
+../tar_texi/tar.texi(,2387) available on some systems. However, mounting
typically requires
+../tar_texi/tar.texi(,2388) superuser privileges and can be a pain to manage.
+../tar_texi/tar.texi(,2389)
+../tar_texi/tar.texi(opsummary,2390) @anchor{--backup}
+../tar_texi/tar.texi(opsummary,2390) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2391) @item address@hidden
+../tar_texi/tar.texi(,2392)
+../tar_texi/tar.texi(,2393) Rather than deleting files from the file system,
@command{tar} will
+../tar_texi/tar.texi(,2394) back them up using simple or numbered backups,
depending upon
+../tar_texi/tar.texi(,2395) @var{backup-type}. @xref{backup}.
+../tar_texi/tar.texi(,2396)
+../tar_texi/tar.texi(opsummary,2397) @anchor{--block-number}
+../tar_texi/tar.texi(opsummary,2397) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2398) @item --block-number
+../tar_texi/tar.texi(,2399) @itemx -R
+../tar_texi/tar.texi(,2400)
+../tar_texi/tar.texi(,2401) With this option present, @command{tar} prints
error messages for read errors
+../tar_texi/tar.texi(,2402) with the block number in the archive file.
@xref{block-number}.
+../tar_texi/tar.texi(,2403)
+../tar_texi/tar.texi(opsummary,2404) @anchor{--blocking-factor}
+../tar_texi/tar.texi(opsummary,2404) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2405) @item address@hidden
+../tar_texi/tar.texi(,2406) @itemx -b @var{blocking}
+../tar_texi/tar.texi(,2407)
+../tar_texi/tar.texi(,2408) Sets the blocking factor @command{tar} uses to
@var{blocking} x 512 bytes per
+../tar_texi/tar.texi(,2409) record. @xref{Blocking Factor}.
+../tar_texi/tar.texi(,2410)
+../tar_texi/tar.texi(opsummary,2411) @anchor{--bzip2}
+../tar_texi/tar.texi(opsummary,2411) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2412) @item --bzip2
+../tar_texi/tar.texi(,2413) @itemx -j
+../tar_texi/tar.texi(,2414)
+../tar_texi/tar.texi(,2415) This option tells @command{tar} to read or write
archives through
+../tar_texi/tar.texi(,2416) @code{bzip2}. @xref{gzip}.
+../tar_texi/tar.texi(,2417)
+../tar_texi/tar.texi(opsummary,2418) @anchor{--checkpoint}
+../tar_texi/tar.texi(opsummary,2418) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2419) @item address@hidden
+../tar_texi/tar.texi(,2420)
+../tar_texi/tar.texi(,2421) This option directs @command{tar} to print
periodic checkpoint
+../tar_texi/tar.texi(,2422) messages as it reads through the archive. It is
intended for when you
+../tar_texi/tar.texi(,2423) want a visual indication that @command{tar} is
still running, but
+../tar_texi/tar.texi(,2424) don't want to see @option{--verbose} output. For
a detailed
+../tar_texi/tar.texi(,2425) description, see @ref{Progress information}.
+../tar_texi/tar.texi(,2426)
+../tar_texi/tar.texi(opsummary,2427) @anchor{--check-links}
+../tar_texi/tar.texi(opsummary,2427) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2428) @item --check-links
+../tar_texi/tar.texi(,2429) @itemx -l
+../tar_texi/tar.texi(,2430) If this option was given, @command{tar} will check
the number of links
+../tar_texi/tar.texi(,2431) dumped for each processed file. If this number
does not match the
+../tar_texi/tar.texi(,2432) total number of hard links for the file, a warning
message will be
+../tar_texi/tar.texi(GNUTAR,2433) output @footnote{Earlier versions of
@acronym{GNU} @command{tar} understood @option{-l} as a
+../tar_texi/tar.texi(,2434) synonym for @option{--one-file-system}. The
current semantics, which
+../tar_texi/tar.texi(,2435) complies to UNIX98, was introduced with version
+../tar_texi/tar.texi(,2436) 1.15.91. @xref{Changes}, for more information.}.
+../tar_texi/tar.texi(,2437)
+../tar_texi/tar.texi(opsummary,2438) @anchor{--compress}
+../tar_texi/tar.texi(opsummary,2438) @opindex address@hidden, summary}
+../tar_texi/tar.texi(opsummary,2439) @anchor{--uncompress}
+../tar_texi/tar.texi(opsummary,2439) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2440) @item --compress
+../tar_texi/tar.texi(,2441) @itemx --uncompress
+../tar_texi/tar.texi(,2442) @itemx -Z
+../tar_texi/tar.texi(,2443)
+../tar_texi/tar.texi(,2444) @command{tar} will use the @command{compress}
program when reading or
+../tar_texi/tar.texi(,2445) writing the archive. This allows you to directly
act on archives
+../tar_texi/tar.texi(,2446) while saving space. @xref{gzip}.
+../tar_texi/tar.texi(,2447)
+../tar_texi/tar.texi(opsummary,2448) @anchor{--confirmation}
+../tar_texi/tar.texi(opsummary,2448) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2449) @item --confirmation
+../tar_texi/tar.texi(,2450)
+../tar_texi/tar.texi(,2451) (See @option{--interactive}.) @xref{interactive}.
+../tar_texi/tar.texi(,2452)
+../tar_texi/tar.texi(opsummary,2453) @anchor{--delay-directory-restore}
+../tar_texi/tar.texi(opsummary,2453) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2454) @item --delay-directory-restore
+../tar_texi/tar.texi(,2455)
+../tar_texi/tar.texi(,2456) Delay setting modification times and permissions
of extracted
+../tar_texi/tar.texi(,2457) directories until the end of extraction.
@xref{Directory Modification Times and Permissions}.
+../tar_texi/tar.texi(,2458)
+../tar_texi/tar.texi(opsummary,2459) @anchor{--dereference}
+../tar_texi/tar.texi(opsummary,2459) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2460) @item --dereference
+../tar_texi/tar.texi(,2461) @itemx -h
+../tar_texi/tar.texi(,2462)
+../tar_texi/tar.texi(,2463) When creating a @command{tar} archive,
@command{tar} will archive the
+../tar_texi/tar.texi(,2464) file that a symbolic link points to, rather than
archiving the
+../tar_texi/tar.texi(,2465) symlink. @xref{dereference}.
+../tar_texi/tar.texi(,2466)
+../tar_texi/tar.texi(opsummary,2467) @anchor{--directory}
+../tar_texi/tar.texi(opsummary,2467) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2468) @item address@hidden
+../tar_texi/tar.texi(,2469) @itemx -C @var{dir}
+../tar_texi/tar.texi(,2470)
+../tar_texi/tar.texi(,2471) When this option is specified, @command{tar} will
change its current directory
+../tar_texi/tar.texi(,2472) to @var{dir} before performing any operations.
When this option is used
+../tar_texi/tar.texi(,2473) during archive creation, it is order sensitive.
@xref{directory}.
+../tar_texi/tar.texi(,2474)
+../tar_texi/tar.texi(opsummary,2475) @anchor{--exclude}
+../tar_texi/tar.texi(opsummary,2475) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2476) @item address@hidden
+../tar_texi/tar.texi(,2477)
+../tar_texi/tar.texi(,2478) When performing operations, @command{tar} will
skip files that match
+../tar_texi/tar.texi(,2479) @var{pattern}. @xref{exclude}.
+../tar_texi/tar.texi(,2480)
+../tar_texi/tar.texi(opsummary,2481) @anchor{--exclude-from}
+../tar_texi/tar.texi(opsummary,2481) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2482) @item address@hidden
+../tar_texi/tar.texi(,2483) @itemx -X @var{file}
+../tar_texi/tar.texi(,2484)
+../tar_texi/tar.texi(,2485) Similar to @option{--exclude}, except
@command{tar} will use the list of
+../tar_texi/tar.texi(,2486) patterns in the file @var{file}. @xref{exclude}.
+../tar_texi/tar.texi(,2487)
+../tar_texi/tar.texi(opsummary,2488) @anchor{--exclude-caches}
+../tar_texi/tar.texi(opsummary,2488) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2489) @item --exclude-caches
+../tar_texi/tar.texi(,2490)
+../tar_texi/tar.texi(,2491) Automatically excludes all directories
+../tar_texi/tar.texi(,2492) containing a cache directory tag. @xref{exclude}.
+../tar_texi/tar.texi(,2493)
+../tar_texi/tar.texi(opsummary,2494) @anchor{--file}
+../tar_texi/tar.texi(opsummary,2494) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2495) @item address@hidden
+../tar_texi/tar.texi(,2496) @itemx -f @var{archive}
+../tar_texi/tar.texi(,2497)
+../tar_texi/tar.texi(,2498) @command{tar} will use the file @var{archive} as
the @command{tar} archive it
+../tar_texi/tar.texi(,2499) performs operations on, rather than
@command{tar}'s compilation dependent
+../tar_texi/tar.texi(,2500) default. @xref{file tutorial}.
+../tar_texi/tar.texi(,2501)
+../tar_texi/tar.texi(opsummary,2502) @anchor{--files-from}
+../tar_texi/tar.texi(opsummary,2502) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2503) @item address@hidden
+../tar_texi/tar.texi(,2504) @itemx -T @var{file}
+../tar_texi/tar.texi(,2505)
+../tar_texi/tar.texi(,2506) @command{tar} will use the contents of @var{file}
as a list of archive members
+../tar_texi/tar.texi(,2507) or files to operate on, in addition to those
specified on the
+../tar_texi/tar.texi(,2508) command-line. @xref{files}.
+../tar_texi/tar.texi(,2509)
+../tar_texi/tar.texi(opsummary,2510) @anchor{--force-local}
+../tar_texi/tar.texi(opsummary,2510) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2511) @item --force-local
+../tar_texi/tar.texi(,2512)
+../tar_texi/tar.texi(,2513) Forces @command{tar} to interpret the filename
given to @option{--file}
+../tar_texi/tar.texi(,2514) as a local file, even if it looks like a remote
tape drive name.
+../tar_texi/tar.texi(,2515) @xref{local and remote archives}.
+../tar_texi/tar.texi(,2516)
+../tar_texi/tar.texi(opsummary,2517) @anchor{--format}
+../tar_texi/tar.texi(opsummary,2517) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2518) @item address@hidden
+../tar_texi/tar.texi(,2519) @itemx -H @var{format}
+../tar_texi/tar.texi(,2520)
+../tar_texi/tar.texi(,2521) Selects output archive format. @var{Format} may
be one of the
+../tar_texi/tar.texi(,2522) following:
+../tar_texi/tar.texi(,2523)
+../tar_texi/tar.texi(,2524) @table @samp
+../tar_texi/tar.texi(,2525) @item v7
+../tar_texi/tar.texi(,2526) Creates an archive that is compatible with Unix V7
@command{tar}.
+../tar_texi/tar.texi(,2527)
+../tar_texi/tar.texi(,2528) @item oldgnu
+../tar_texi/tar.texi(,2529) Creates an archive that is compatible with GNU
@command{tar} version
+../tar_texi/tar.texi(,2530) 1.12 or earlier.
+../tar_texi/tar.texi(,2531)
+../tar_texi/tar.texi(,2532) @item gnu
+../tar_texi/tar.texi(,2533) Creates archive in GNU tar 1.13 format. Basically
it is the same as
+../tar_texi/tar.texi(,2534) @samp{oldgnu} with the only difference in the way
it handles long
+../tar_texi/tar.texi(,2535) numeric fields.
+../tar_texi/tar.texi(,2536)
+../tar_texi/tar.texi(,2537) @item ustar
+../tar_texi/tar.texi(,2538) Creates a @acronym{POSIX.1-1988} compatible
archive.
+../tar_texi/tar.texi(,2539)
+../tar_texi/tar.texi(,2540) @item posix
+../tar_texi/tar.texi(,2541) Creates a @acronym{POSIX.1-2001 archive}.
+../tar_texi/tar.texi(,2542)
+../tar_texi/tar.texi(,2543) @end table
+../tar_texi/tar.texi(,2544)
+../tar_texi/tar.texi(,2545) @xref{Formats}, for a detailed discussion of these
formats.
+../tar_texi/tar.texi(,2546)
+../tar_texi/tar.texi(opsummary,2547) @anchor{--group}
+../tar_texi/tar.texi(opsummary,2547) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2548) @item address@hidden
+../tar_texi/tar.texi(,2549)
+../tar_texi/tar.texi(,2550) Files added to the @command{tar} archive will have
a group id of @var{group},
+../tar_texi/tar.texi(,2551) rather than the group from the source file.
@var{group} is first decoded
+../tar_texi/tar.texi(,2552) as a group symbolic name, but if this
interpretation fails, it has to be
+../tar_texi/tar.texi(,2553) a decimal numeric group ID. @xref{override}.
+../tar_texi/tar.texi(,2554)
+../tar_texi/tar.texi(,2555) Also see the comments for the @address@hidden
option.
+../tar_texi/tar.texi(,2556)
+../tar_texi/tar.texi(opsummary,2557) @anchor{--gzip}
+../tar_texi/tar.texi(opsummary,2557) @opindex address@hidden, summary}
+../tar_texi/tar.texi(opsummary,2558) @anchor{--gunzip}
+../tar_texi/tar.texi(opsummary,2558) @opindex address@hidden, summary}
+../tar_texi/tar.texi(opsummary,2559) @anchor{--ungzip}
+../tar_texi/tar.texi(opsummary,2559) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2560) @item --gzip
+../tar_texi/tar.texi(,2561) @itemx --gunzip
+../tar_texi/tar.texi(,2562) @itemx --ungzip
+../tar_texi/tar.texi(,2563) @itemx -z
+../tar_texi/tar.texi(,2564)
+../tar_texi/tar.texi(,2565) This option tells @command{tar} to read or write
archives through
+../tar_texi/tar.texi(,2566) @command{gzip}, allowing @command{tar} to directly
operate on several
+../tar_texi/tar.texi(,2567) kinds of compressed archives transparently.
@xref{gzip}.
+../tar_texi/tar.texi(,2568)
+../tar_texi/tar.texi(opsummary,2569) @anchor{--help}
+../tar_texi/tar.texi(opsummary,2569) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2570) @item --help
+../tar_texi/tar.texi(,2571) @itemx -?
+../tar_texi/tar.texi(,2572)
+../tar_texi/tar.texi(,2573) @command{tar} will print out a short message
summarizing the operations and
+../tar_texi/tar.texi(,2574) options to @command{tar} and exit. @xref{help}.
+../tar_texi/tar.texi(,2575)
+../tar_texi/tar.texi(opsummary,2576) @anchor{--ignore-case}
+../tar_texi/tar.texi(opsummary,2576) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2577) @item --ignore-case
+../tar_texi/tar.texi(,2578) Ignore case when matching member or file names with
+../tar_texi/tar.texi(,2579) patterns. @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2580)
+../tar_texi/tar.texi(opsummary,2581) @anchor{--ignore-command-error}
+../tar_texi/tar.texi(opsummary,2581) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2582) @item --ignore-command-error
+../tar_texi/tar.texi(,2583) Ignore exit codes of subprocesses. @xref{Writing
to an External Program}.
+../tar_texi/tar.texi(,2584)
+../tar_texi/tar.texi(opsummary,2585) @anchor{--ignore-failed-read}
+../tar_texi/tar.texi(opsummary,2585) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2586) @item --ignore-failed-read
+../tar_texi/tar.texi(,2587)
+../tar_texi/tar.texi(,2588) Do not exit unsuccessfully merely because an
unreadable file was encountered.
+../tar_texi/tar.texi(,2589) @xref{Reading}.
+../tar_texi/tar.texi(,2590)
+../tar_texi/tar.texi(opsummary,2591) @anchor{--ignore-zeros}
+../tar_texi/tar.texi(opsummary,2591) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2592) @item --ignore-zeros
+../tar_texi/tar.texi(,2593) @itemx -i
+../tar_texi/tar.texi(,2594)
+../tar_texi/tar.texi(,2595) With this option, @command{tar} will ignore zeroed
blocks in the
+../tar_texi/tar.texi(,2596) archive, which normally signals EOF.
@xref{Reading}.
+../tar_texi/tar.texi(,2597)
+../tar_texi/tar.texi(opsummary,2598) @anchor{--incremental}
+../tar_texi/tar.texi(opsummary,2598) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2599) @item --incremental
+../tar_texi/tar.texi(,2600) @itemx -G
+../tar_texi/tar.texi(,2601)
+../tar_texi/tar.texi(,2602) Used to inform @command{tar} that it is working
with an old
+../tar_texi/tar.texi(,2603) @acronym{GNU}-format incremental backup archive.
It is intended
+../tar_texi/tar.texi(,2604) primarily for backwards compatibility only.
@xref{Incremental Dumps},
+../tar_texi/tar.texi(,2605) for a detailed discussion of incremental archives.
+../tar_texi/tar.texi(,2606)
+../tar_texi/tar.texi(opsummary,2607) @anchor{--index-file}
+../tar_texi/tar.texi(opsummary,2607) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2608) @item address@hidden
+../tar_texi/tar.texi(,2609)
+../tar_texi/tar.texi(,2610) Send verbose output to @var{file} instead of to
standard output.
+../tar_texi/tar.texi(,2611)
+../tar_texi/tar.texi(opsummary,2612) @anchor{--info-script}
+../tar_texi/tar.texi(opsummary,2612) @opindex address@hidden, summary}
+../tar_texi/tar.texi(opsummary,2613) @anchor{--new-volume-script}
+../tar_texi/tar.texi(opsummary,2613) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2614) @item address@hidden
+../tar_texi/tar.texi(,2615) @itemx address@hidden
+../tar_texi/tar.texi(,2616) @itemx -F @var{script-file}
+../tar_texi/tar.texi(,2617)
+../tar_texi/tar.texi(,2618) When @command{tar} is performing multi-tape
backups, @var{script-file} is run
+../tar_texi/tar.texi(,2619) at the end of each tape. If @var{script-file}
exits with nonzero status,
+../tar_texi/tar.texi(,2620) @command{tar} fails immediately.
@xref{info-script}, for a detailed
+../tar_texi/tar.texi(,2621) discussion of @var{script-file}.
+../tar_texi/tar.texi(,2622)
+../tar_texi/tar.texi(opsummary,2623) @anchor{--interactive}
+../tar_texi/tar.texi(opsummary,2623) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2624) @item --interactive
+../tar_texi/tar.texi(,2625) @itemx --confirmation
+../tar_texi/tar.texi(,2626) @itemx -w
+../tar_texi/tar.texi(,2627)
+../tar_texi/tar.texi(,2628) Specifies that @command{tar} should ask the user
for confirmation before
+../tar_texi/tar.texi(,2629) performing potentially destructive options, such
as overwriting files.
+../tar_texi/tar.texi(,2630) @xref{interactive}.
+../tar_texi/tar.texi(,2631)
+../tar_texi/tar.texi(opsummary,2632) @anchor{--keep-newer-files}
+../tar_texi/tar.texi(opsummary,2632) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2633) @item --keep-newer-files
+../tar_texi/tar.texi(,2634)
+../tar_texi/tar.texi(,2635) Do not replace existing files that are newer than
their archive copies
+../tar_texi/tar.texi(,2636) when extracting files from an archive.
+../tar_texi/tar.texi(,2637)
+../tar_texi/tar.texi(opsummary,2638) @anchor{--keep-old-files}
+../tar_texi/tar.texi(opsummary,2638) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2639) @item --keep-old-files
+../tar_texi/tar.texi(,2640) @itemx -k
+../tar_texi/tar.texi(,2641)
+../tar_texi/tar.texi(,2642) Do not overwrite existing files when extracting
files from an archive.
+../tar_texi/tar.texi(,2643) @xref{Keep Old Files}.
+../tar_texi/tar.texi(,2644)
+../tar_texi/tar.texi(opsummary,2645) @anchor{--label}
+../tar_texi/tar.texi(opsummary,2645) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2646) @item address@hidden
+../tar_texi/tar.texi(,2647) @itemx -V @var{name}
+../tar_texi/tar.texi(,2648)
+../tar_texi/tar.texi(,2649) When creating an archive, instructs @command{tar}
to write @var{name}
+../tar_texi/tar.texi(,2650) as a name record in the archive. When extracting
or listing archives,
+../tar_texi/tar.texi(,2651) @command{tar} will only operate on archives that
have a label matching
+../tar_texi/tar.texi(,2652) the pattern specified in @var{name}. @xref{Tape
Files}.
+../tar_texi/tar.texi(,2653)
+../tar_texi/tar.texi(opsummary,2654) @anchor{--listed-incremental}
+../tar_texi/tar.texi(opsummary,2654) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2655) @item address@hidden
+../tar_texi/tar.texi(,2656) @itemx -g @var{snapshot-file}
+../tar_texi/tar.texi(,2657)
+../tar_texi/tar.texi(,2658) During a @option{--create} operation, specifies
that the archive that
+../tar_texi/tar.texi(,2659) @command{tar} creates is a new
@acronym{GNU}-format incremental
+../tar_texi/tar.texi(,2660) backup, using @var{snapshot-file} to determine
which files to backup.
+../tar_texi/tar.texi(,2661) With other operations, informs @command{tar} that
the archive is in
+../tar_texi/tar.texi(,2662) incremental format. @xref{Incremental Dumps}.
+../tar_texi/tar.texi(,2663)
+../tar_texi/tar.texi(opsummary,2664) @anchor{--mode}
+../tar_texi/tar.texi(opsummary,2664) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2665) @item address@hidden
+../tar_texi/tar.texi(,2666)
+../tar_texi/tar.texi(,2667) When adding files to an archive, @command{tar}
will use
+../tar_texi/tar.texi(,2668) @var{permissions} for the archive members, rather
than the permissions
+../tar_texi/tar.texi(,2669) from the files. @var{permissions} can be
specified either as an octal
+../tar_texi/tar.texi(,2670) number or as symbolic permissions, like with
+../tar_texi/tar.texi(,2671) @command{chmod}. @xref{override}.
+../tar_texi/tar.texi(,2672)
+../tar_texi/tar.texi(opsummary,2673) @anchor{--mtime}
+../tar_texi/tar.texi(opsummary,2673) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2674) @item address@hidden
+../tar_texi/tar.texi(,2675)
+../tar_texi/tar.texi(,2676) When adding files to an archive, @command{tar}
will use @var{date} as
+../tar_texi/tar.texi(,2677) the modification time of members when creating
archives, instead of
+../tar_texi/tar.texi(,2678) their actual modification times. The value of
@var{date} can be
+../tar_texi/tar.texi(,2679) either a textual date representation (@pxref{Date
input formats}) or a
+../tar_texi/tar.texi(,2680) name of the existing file, starting with @samp{/}
or @samp{.}. In the
+../tar_texi/tar.texi(,2681) latter case, the modification time of that file is
used. @xref{override}.
+../tar_texi/tar.texi(,2682)
+../tar_texi/tar.texi(opsummary,2683) @anchor{--multi-volume}
+../tar_texi/tar.texi(opsummary,2683) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2684) @item --multi-volume
+../tar_texi/tar.texi(,2685) @itemx -M
+../tar_texi/tar.texi(,2686)
+../tar_texi/tar.texi(,2687) Informs @command{tar} that it should create or
otherwise operate on a
+../tar_texi/tar.texi(,2688) multi-volume @command{tar} archive. @xref{Using
Multiple Tapes}.
+../tar_texi/tar.texi(,2689)
+../tar_texi/tar.texi(opsummary,2690) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2691) @item --new-volume-script
+../tar_texi/tar.texi(,2692)
+../tar_texi/tar.texi(,2693) (see --info-script)
+../tar_texi/tar.texi(,2694)
+../tar_texi/tar.texi(opsummary,2695) @anchor{--seek}
+../tar_texi/tar.texi(opsummary,2695) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2696) @item --seek
+../tar_texi/tar.texi(,2697) @itemx -n
+../tar_texi/tar.texi(,2698)
+../tar_texi/tar.texi(,2699) Assume that the archive media supports seeks to
arbitrary
+../tar_texi/tar.texi(,2700) locations. Usually @command{tar} determines
automatically whether
+../tar_texi/tar.texi(,2701) the archive can be seeked or not. This option is
intended for use
+../tar_texi/tar.texi(,2702) in cases when such recognition fails.
+../tar_texi/tar.texi(,2703)
+../tar_texi/tar.texi(opsummary,2704) @anchor{--newer}
+../tar_texi/tar.texi(opsummary,2704) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2705) @item address@hidden
+../tar_texi/tar.texi(,2706) @itemx address@hidden
+../tar_texi/tar.texi(,2707) @itemx -N
+../tar_texi/tar.texi(,2708)
+../tar_texi/tar.texi(,2709) When creating an archive, @command{tar} will only
add files that have changed
+../tar_texi/tar.texi(,2710) since @var{date}. If @var{date} begins with
@samp{/} or @samp{.}, it
+../tar_texi/tar.texi(,2711) is taken to be the name of a file whose data
modification time specifies
+../tar_texi/tar.texi(,2712) the date. @xref{after}.
+../tar_texi/tar.texi(,2713)
+../tar_texi/tar.texi(opsummary,2714) @anchor{--newer-mtime}
+../tar_texi/tar.texi(opsummary,2714) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2715) @item address@hidden
+../tar_texi/tar.texi(,2716)
+../tar_texi/tar.texi(,2717) Like @option{--newer}, but add only files whose
+../tar_texi/tar.texi(,2718) contents have changed (as opposed to just
@option{--newer}, which will
+../tar_texi/tar.texi(,2719) also back up files for which any status
information has
+../tar_texi/tar.texi(,2720) changed). @xref{after}.
+../tar_texi/tar.texi(,2721)
+../tar_texi/tar.texi(opsummary,2722) @anchor{--no-anchored}
+../tar_texi/tar.texi(opsummary,2722) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2723) @item --no-anchored
+../tar_texi/tar.texi(,2724) An exclude pattern can match any subsequence of
the name's components.
+../tar_texi/tar.texi(,2725) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2726)
+../tar_texi/tar.texi(opsummary,2727) @anchor{--no-delay-directory-restore}
+../tar_texi/tar.texi(opsummary,2727) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2728) @item --no-delay-directory-restore
+../tar_texi/tar.texi(,2729)
+../tar_texi/tar.texi(,2730) Setting modification times and permissions of
extracted
+../tar_texi/tar.texi(,2731) directories when all files from this directory has
been
+../tar_texi/tar.texi(,2732) extracted. This is the default. @xref{Directory
Modification Times and Permissions}.
+../tar_texi/tar.texi(,2733)
+../tar_texi/tar.texi(opsummary,2734) @anchor{--no-ignore-case}
+../tar_texi/tar.texi(opsummary,2734) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2735) @item --no-ignore-case
+../tar_texi/tar.texi(,2736) Use case-sensitive matching.
+../tar_texi/tar.texi(,2737) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2738)
+../tar_texi/tar.texi(opsummary,2739) @anchor{--no-ignore-command-error}
+../tar_texi/tar.texi(opsummary,2739) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2740) @item --no-ignore-command-error
+../tar_texi/tar.texi(,2741) Print warnings about subprocesses terminated with
a non-zero exit
+../tar_texi/tar.texi(,2742) code. @xref{Writing to an External Program}.
+../tar_texi/tar.texi(,2743)
+../tar_texi/tar.texi(opsummary,2744) @anchor{--no-overwrite-dir}
+../tar_texi/tar.texi(opsummary,2744) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2745) @item --no-overwrite-dir
+../tar_texi/tar.texi(,2746)
+../tar_texi/tar.texi(,2747) Preserve metadata of existing directories when
extracting files
+../tar_texi/tar.texi(,2748) from an archive. @xref{Overwrite Old Files}.
+../tar_texi/tar.texi(,2749)
+../tar_texi/tar.texi(opsummary,2750) @anchor{--no-quote-chars}
+../tar_texi/tar.texi(opsummary,2750) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2751) @item address@hidden
+../tar_texi/tar.texi(,2752) Remove characters listed in @var{string} from the
list of quoted
+../tar_texi/tar.texi(,2753) characters set by the previous
@option{--quote-chars} option
+../tar_texi/tar.texi(,2754) (@pxref{quoting styles}).
+../tar_texi/tar.texi(,2755)
+../tar_texi/tar.texi(opsummary,2756) @anchor{--no-recursion}
+../tar_texi/tar.texi(opsummary,2756) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2757) @item --no-recursion
+../tar_texi/tar.texi(,2758)
+../tar_texi/tar.texi(,2759) With this option, @command{tar} will not recurse
into directories.
+../tar_texi/tar.texi(,2760) @xref{recurse}.
+../tar_texi/tar.texi(,2761)
+../tar_texi/tar.texi(opsummary,2762) @anchor{--no-same-owner}
+../tar_texi/tar.texi(opsummary,2762) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2763) @item --no-same-owner
+../tar_texi/tar.texi(,2764) @itemx -o
+../tar_texi/tar.texi(,2765)
+../tar_texi/tar.texi(,2766) When extracting an archive, do not attempt to
preserve the owner
+../tar_texi/tar.texi(,2767) specified in the @command{tar} archive. This the
default behavior
+../tar_texi/tar.texi(,2768) for ordinary users.
+../tar_texi/tar.texi(,2769)
+../tar_texi/tar.texi(opsummary,2770) @anchor{--no-same-permissions}
+../tar_texi/tar.texi(opsummary,2770) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2771) @item --no-same-permissions
+../tar_texi/tar.texi(,2772)
+../tar_texi/tar.texi(,2773) When extracting an archive, subtract the user's
umask from files from
+../tar_texi/tar.texi(,2774) the permissions specified in the archive. This is
the default behavior
+../tar_texi/tar.texi(,2775) for ordinary users.
+../tar_texi/tar.texi(,2776)
+../tar_texi/tar.texi(opsummary,2777) @anchor{--no-unquote}
+../tar_texi/tar.texi(opsummary,2777) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2778) @item --no-unquote
+../tar_texi/tar.texi(,2779) Treat all input file or member names literally, do
not interpret
+../tar_texi/tar.texi(,2780) escape sequences. @xref{input name quoting}.
+../tar_texi/tar.texi(,2781)
+../tar_texi/tar.texi(opsummary,2782) @anchor{--no-wildcards}
+../tar_texi/tar.texi(opsummary,2782) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2783) @item --no-wildcards
+../tar_texi/tar.texi(,2784) Do not use wildcards.
+../tar_texi/tar.texi(,2785) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2786)
+../tar_texi/tar.texi(opsummary,2787) @anchor{--no-wildcards-match-slash}
+../tar_texi/tar.texi(opsummary,2787) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2788) @item --no-wildcards-match-slash
+../tar_texi/tar.texi(,2789) Wildcards do not match @samp{/}.
+../tar_texi/tar.texi(,2790) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2791)
+../tar_texi/tar.texi(opsummary,2792) @anchor{--null}
+../tar_texi/tar.texi(opsummary,2792) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2793) @item --null
+../tar_texi/tar.texi(,2794)
+../tar_texi/tar.texi(,2795) When @command{tar} is using the
@option{--files-from} option, this option
+../tar_texi/tar.texi(,2796) instructs @command{tar} to expect filenames
terminated with @option{NUL}, so
+../tar_texi/tar.texi(,2797) @command{tar} can correctly work with file names
that contain newlines.
+../tar_texi/tar.texi(,2798) @xref{nul}.
+../tar_texi/tar.texi(,2799)
+../tar_texi/tar.texi(opsummary,2800) @anchor{--numeric-owner}
+../tar_texi/tar.texi(opsummary,2800) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2801) @item --numeric-owner
+../tar_texi/tar.texi(,2802)
+../tar_texi/tar.texi(,2803) This option will notify @command{tar} that it
should use numeric user
+../tar_texi/tar.texi(,2804) and group IDs when creating a @command{tar} file,
rather than names.
+../tar_texi/tar.texi(,2805) @xref{Attributes}.
+../tar_texi/tar.texi(,2806)
+../tar_texi/tar.texi(,2807) @item -o
+../tar_texi/tar.texi(,2808) The function of this option depends on the action
@command{tar} is
+../tar_texi/tar.texi(,2809) performing. When extracting files, @option{-o} is
a synonym for
+../tar_texi/tar.texi(,2810) @option{--no-same-owner}, i.e. it prevents
@command{tar} from
+../tar_texi/tar.texi(,2811) restoring ownership of files being extracted.
+../tar_texi/tar.texi(,2812)
+../tar_texi/tar.texi(,2813) When creating an archive, it is a synonym for
+../tar_texi/tar.texi(,2814) @option{--old-archive}. This behavior is for
compatibility
+../tar_texi/tar.texi(GNUTAR,2815) with previous versions of @acronym{GNU}
@command{tar}, and will be
+../tar_texi/tar.texi(,2816) removed in the future releases.
+../tar_texi/tar.texi(,2817)
+../tar_texi/tar.texi(,2818) @xref{Changes}, for more information.
+../tar_texi/tar.texi(,2819)
+../tar_texi/tar.texi(opsummary,2820) @anchor{--occurrence}
+../tar_texi/tar.texi(opsummary,2820) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2821) @item address@hidden
+../tar_texi/tar.texi(,2822)
+../tar_texi/tar.texi(,2823) This option can be used in conjunction with one of
the subcommands
+../tar_texi/tar.texi(,2824) @option{--delete}, @option{--diff},
@option{--extract} or
+../tar_texi/tar.texi(,2825) @option{--list} when a list of files is given
either on the command
+../tar_texi/tar.texi(,2826) line or via @option{-T} option.
+../tar_texi/tar.texi(,2827)
+../tar_texi/tar.texi(,2828) This option instructs @command{tar} to process
only the @var{number}th
+../tar_texi/tar.texi(,2829) occurrence of each named file. @var{Number}
defaults to 1, so
+../tar_texi/tar.texi(,2830)
+../tar_texi/tar.texi(,2831) @smallexample
+../tar_texi/tar.texi(,2832) tar -x -f archive.tar --occurrence filename
+../tar_texi/tar.texi(,2833) @end smallexample
+../tar_texi/tar.texi(,2834)
+../tar_texi/tar.texi(,2835) @noindent
+../tar_texi/tar.texi(,2836) will extract the first occurrence of the member
@file{filename} from @file{archive.tar}
+../tar_texi/tar.texi(,2837) and will terminate without scanning to the end of
the archive.
+../tar_texi/tar.texi(,2838)
+../tar_texi/tar.texi(opsummary,2839) @anchor{--old-archive}
+../tar_texi/tar.texi(opsummary,2839) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2840) @item --old-archive
+../tar_texi/tar.texi(,2841) Synonym for @option{--format=v7}.
+../tar_texi/tar.texi(,2842)
+../tar_texi/tar.texi(opsummary,2843) @anchor{--one-file-system}
+../tar_texi/tar.texi(opsummary,2843) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2844) @item --one-file-system
+../tar_texi/tar.texi(,2845) Used when creating an archive. Prevents
@command{tar} from recursing into
+../tar_texi/tar.texi(,2846) directories that are on different file systems
from the current
+../tar_texi/tar.texi(GNUTAR,2847) directory @footnote{Earlier versions of
@acronym{GNU} @command{tar} understood @option{-l} as a
+../tar_texi/tar.texi(,2848) synonym for @option{--one-file-system}. This has
changed in version
+../tar_texi/tar.texi(,2849) 1.15.91. @xref{Changes}, for more information.}.
+../tar_texi/tar.texi(,2850)
+../tar_texi/tar.texi(opsummary,2851) @anchor{--overwrite}
+../tar_texi/tar.texi(opsummary,2851) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2852) @item --overwrite
+../tar_texi/tar.texi(,2853)
+../tar_texi/tar.texi(,2854) Overwrite existing files and directory metadata
when extracting files
+../tar_texi/tar.texi(,2855) from an archive. @xref{Overwrite Old Files}.
+../tar_texi/tar.texi(,2856)
+../tar_texi/tar.texi(opsummary,2857) @anchor{--overwrite-dir}
+../tar_texi/tar.texi(opsummary,2857) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2858) @item --overwrite-dir
+../tar_texi/tar.texi(,2859)
+../tar_texi/tar.texi(,2860) Overwrite the metadata of existing directories
when extracting files
+../tar_texi/tar.texi(,2861) from an archive. @xref{Overwrite Old Files}.
+../tar_texi/tar.texi(,2862)
+../tar_texi/tar.texi(opsummary,2863) @anchor{--owner}
+../tar_texi/tar.texi(opsummary,2863) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2864) @item address@hidden
+../tar_texi/tar.texi(,2865)
+../tar_texi/tar.texi(,2866) Specifies that @command{tar} should use @var{user}
as the owner of members
+../tar_texi/tar.texi(,2867) when creating archives, instead of the user
associated with the source
+../tar_texi/tar.texi(,2868) file. @var{user} is first decoded as a user
symbolic name, but if
+../tar_texi/tar.texi(,2869) this interpretation fails, it has to be a decimal
numeric user ID.
+../tar_texi/tar.texi(,2870) @xref{override}.
+../tar_texi/tar.texi(,2871)
+../tar_texi/tar.texi(,2872) This option does not affect extraction from
archives.
+../tar_texi/tar.texi(,2873)
+../tar_texi/tar.texi(opsummary,2874) @anchor{--transform}
+../tar_texi/tar.texi(opsummary,2874) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2875) @item address@hidden
+../tar_texi/tar.texi(,2876)
+../tar_texi/tar.texi(,2877) Transform file or member names using @command{sed}
replacement expression
+../tar_texi/tar.texi(,2878) @var{sed-expr}. For example,
+../tar_texi/tar.texi(,2879)
+../tar_texi/tar.texi(,2880) @smallexample
+../tar_texi/tar.texi(,2881) $ @kbd{tar cf archive.tar --transform
's,^\./,usr/,' .}
+../tar_texi/tar.texi(,2882) @end smallexample
+../tar_texi/tar.texi(,2883)
+../tar_texi/tar.texi(,2884) @noindent
+../tar_texi/tar.texi(,2885) will add to @file{archive} files from the current
working directory,
+../tar_texi/tar.texi(,2886) replacing initial @samp{./} prefix with
@samp{usr/}. For the detailed
+../tar_texi/tar.texi(,2887) discussion, @xref{transform}.
+../tar_texi/tar.texi(,2888)
+../tar_texi/tar.texi(,2889) To see transformed member names in verbose
listings, use
+../tar_texi/tar.texi(,2890) @option{--show-transformed-names} option
+../tar_texi/tar.texi(,2891) (@pxref{show-transformed-names}).
+../tar_texi/tar.texi(,2892)
+../tar_texi/tar.texi(opsummary,2893) @anchor{--quote-chars}
+../tar_texi/tar.texi(opsummary,2893) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2894) @item address@hidden
+../tar_texi/tar.texi(,2895) Always quote characters from @var{string}, even if
the selected
+../tar_texi/tar.texi(,2896) quoting style would not quote them (@pxref{quoting
styles}).
+../tar_texi/tar.texi(,2897)
+../tar_texi/tar.texi(opsummary,2898) @anchor{--quoting-style}
+../tar_texi/tar.texi(opsummary,2898) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2899) @item address@hidden
+../tar_texi/tar.texi(,2900) Set quoting style to use when printing member and
file names
+../tar_texi/tar.texi(,2901) (@pxref{quoting styles}). Valid @var{style} values
are:
+../tar_texi/tar.texi(,2902) @code{literal}, @code{shell}, @code{shell-always},
@code{c},
+../tar_texi/tar.texi(,2903) @code{escape}, @code{locale}, and @code{clocale}.
Default quoting
+../tar_texi/tar.texi(,2904) style is @code{escape}, unless overridden while
configuring the
+../tar_texi/tar.texi(,2905) package.
+../tar_texi/tar.texi(,2906)
+../tar_texi/tar.texi(opsummary,2907) @anchor{--pax-option}
+../tar_texi/tar.texi(opsummary,2907) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2908) @item address@hidden
+../tar_texi/tar.texi(,2909) This option is meaningful only with
@acronym{POSIX.1-2001} archives
+../tar_texi/tar.texi(,2910) (@pxref{posix}). It modifies the way
@command{tar} handles the
+../tar_texi/tar.texi(,2911) extended header keywords. @var{Keyword-list} is a
comma-separated
+../tar_texi/tar.texi(,2912) list of keyword options. @xref{PAX keywords}, for
a detailed
+../tar_texi/tar.texi(,2913) discussion.
+../tar_texi/tar.texi(,2914)
+../tar_texi/tar.texi(opsummary,2915) @anchor{--portability}
+../tar_texi/tar.texi(opsummary,2915) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2916) @item --portability
+../tar_texi/tar.texi(,2917) @itemx --old-archive
+../tar_texi/tar.texi(,2918) Synonym for @option{--format=v7}.
+../tar_texi/tar.texi(,2919)
+../tar_texi/tar.texi(opsummary,2920) @anchor{--posix}
+../tar_texi/tar.texi(opsummary,2920) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2921) @item --posix
+../tar_texi/tar.texi(,2922) Same as @option{--format=posix}.
+../tar_texi/tar.texi(,2923)
+../tar_texi/tar.texi(opsummary,2924) @anchor{--preserve}
+../tar_texi/tar.texi(opsummary,2924) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2925) @item --preserve
+../tar_texi/tar.texi(,2926)
+../tar_texi/tar.texi(,2927) Synonymous with specifying both
@option{--preserve-permissions} and
+../tar_texi/tar.texi(,2928) @option{--same-order}. @xref{Setting Access
Permissions}.
+../tar_texi/tar.texi(,2929)
+../tar_texi/tar.texi(opsummary,2930) @anchor{--preserve-order}
+../tar_texi/tar.texi(opsummary,2930) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2931) @item --preserve-order
+../tar_texi/tar.texi(,2932)
+../tar_texi/tar.texi(,2933) (See @option{--same-order}; @pxref{Reading}.)
+../tar_texi/tar.texi(,2934)
+../tar_texi/tar.texi(opsummary,2935) @anchor{--preserve-permissions}
+../tar_texi/tar.texi(opsummary,2935) @opindex address@hidden, summary}
+../tar_texi/tar.texi(opsummary,2936) @anchor{--same-permissions}
+../tar_texi/tar.texi(opsummary,2936) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2937) @item --preserve-permissions
+../tar_texi/tar.texi(,2938) @itemx --same-permissions
+../tar_texi/tar.texi(,2939) @itemx -p
+../tar_texi/tar.texi(,2940)
+../tar_texi/tar.texi(,2941) When @command{tar} is extracting an archive, it
normally subtracts the
+../tar_texi/tar.texi(,2942) users' umask from the permissions specified in the
archive and uses
+../tar_texi/tar.texi(,2943) that number as the permissions to create the
destination file.
+../tar_texi/tar.texi(,2944) Specifying this option instructs @command{tar}
that it should use the
+../tar_texi/tar.texi(,2945) permissions directly from the archive.
@xref{Setting Access Permissions}.
+../tar_texi/tar.texi(,2946)
+../tar_texi/tar.texi(opsummary,2947) @anchor{--read-full-records}
+../tar_texi/tar.texi(opsummary,2947) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2948) @item --read-full-records
+../tar_texi/tar.texi(,2949) @itemx -B
+../tar_texi/tar.texi(,2950)
+../tar_texi/tar.texi(,2951) Specifies that @command{tar} should reblock its
input, for reading
+../tar_texi/tar.texi(,2952) from pipes on systems with buggy implementations.
@xref{Reading}.
+../tar_texi/tar.texi(,2953)
+../tar_texi/tar.texi(opsummary,2954) @anchor{--record-size}
+../tar_texi/tar.texi(opsummary,2954) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2955) @item address@hidden
+../tar_texi/tar.texi(,2956)
+../tar_texi/tar.texi(,2957) Instructs @command{tar} to use @var{size} bytes
per record when accessing the
+../tar_texi/tar.texi(,2958) archive. @xref{Blocking Factor}.
+../tar_texi/tar.texi(,2959)
+../tar_texi/tar.texi(opsummary,2960) @anchor{--recursion}
+../tar_texi/tar.texi(opsummary,2960) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2961) @item --recursion
+../tar_texi/tar.texi(,2962)
+../tar_texi/tar.texi(,2963) With this option, @command{tar} recurses into
directories.
+../tar_texi/tar.texi(,2964) @xref{recurse}.
+../tar_texi/tar.texi(,2965)
+../tar_texi/tar.texi(opsummary,2966) @anchor{--recursive-unlink}
+../tar_texi/tar.texi(opsummary,2966) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2967) @item --recursive-unlink
+../tar_texi/tar.texi(,2968)
+../tar_texi/tar.texi(,2969) Remove existing
+../tar_texi/tar.texi(,2970) directory hierarchies before extracting
directories of the same name
+../tar_texi/tar.texi(,2971) from the archive. @xref{Recursive Unlink}.
+../tar_texi/tar.texi(,2972)
+../tar_texi/tar.texi(opsummary,2973) @anchor{--remove-files}
+../tar_texi/tar.texi(opsummary,2973) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2974) @item --remove-files
+../tar_texi/tar.texi(,2975)
+../tar_texi/tar.texi(,2976) Directs @command{tar} to remove the source file
from the file system after
+../tar_texi/tar.texi(,2977) appending it to an archive. @xref{remove files}.
+../tar_texi/tar.texi(,2978)
+../tar_texi/tar.texi(opsummary,2979) @anchor{--restrict}
+../tar_texi/tar.texi(opsummary,2979) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2980) @item --restrict
+../tar_texi/tar.texi(,2981)
+../tar_texi/tar.texi(,2982) Disable use of some potentially harmful
@command{tar} options.
+../tar_texi/tar.texi(,2983) Currently this option disables shell invocaton
from multi-volume menu
+../tar_texi/tar.texi(,2984) (@pxref{Using Multiple Tapes}).
+../tar_texi/tar.texi(,2985)
+../tar_texi/tar.texi(opsummary,2986) @anchor{--rmt-command}
+../tar_texi/tar.texi(opsummary,2986) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2987) @item address@hidden
+../tar_texi/tar.texi(,2988)
+../tar_texi/tar.texi(,2989) Notifies @command{tar} that it should use
@var{cmd} instead of
+../tar_texi/tar.texi(,2990) the default @file{/usr/libexec/rmt} (@pxref{Remote
Tape Server}).
+../tar_texi/tar.texi(,2991)
+../tar_texi/tar.texi(opsummary,2992) @anchor{--rsh-command}
+../tar_texi/tar.texi(opsummary,2992) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2993) @item address@hidden
+../tar_texi/tar.texi(,2994)
+../tar_texi/tar.texi(,2995) Notifies @command{tar} that is should use
@var{cmd} to communicate with remote
+../tar_texi/tar.texi(,2996) devices. @xref{Device}.
+../tar_texi/tar.texi(,2997)
+../tar_texi/tar.texi(opsummary,2998) @anchor{--same-order}
+../tar_texi/tar.texi(opsummary,2998) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,2999) @item --same-order
+../tar_texi/tar.texi(,3000) @itemx --preserve-order
+../tar_texi/tar.texi(,3001) @itemx -s
+../tar_texi/tar.texi(,3002)
+../tar_texi/tar.texi(,3003) This option is an optimization for @command{tar}
when running on machines with
+../tar_texi/tar.texi(,3004) small amounts of memory. It informs @command{tar}
that the list of file
+../tar_texi/tar.texi(,3005) arguments has already been sorted to match the
order of files in the
+../tar_texi/tar.texi(,3006) archive. @xref{Reading}.
+../tar_texi/tar.texi(,3007)
+../tar_texi/tar.texi(opsummary,3008) @anchor{--same-owner}
+../tar_texi/tar.texi(opsummary,3008) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3009) @item --same-owner
+../tar_texi/tar.texi(,3010)
+../tar_texi/tar.texi(,3011) When extracting an archive, @command{tar} will
attempt to preserve the owner
+../tar_texi/tar.texi(,3012) specified in the @command{tar} archive with this
option present.
+../tar_texi/tar.texi(,3013) This is the default behavior for the superuser;
this option has an
+../tar_texi/tar.texi(,3014) effect only for ordinary users. @xref{Attributes}.
+../tar_texi/tar.texi(,3015)
+../tar_texi/tar.texi(opsummary,3016) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3017) @item --same-permissions
+../tar_texi/tar.texi(,3018)
+../tar_texi/tar.texi(,3019) (See @option{--preserve-permissions};
@pxref{Setting Access Permissions}.)
+../tar_texi/tar.texi(,3020)
+../tar_texi/tar.texi(opsummary,3021) @anchor{--show-defaults}
+../tar_texi/tar.texi(opsummary,3021) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3022) @item --show-defaults
+../tar_texi/tar.texi(,3023)
+../tar_texi/tar.texi(,3024) Displays the default options used by @command{tar}
and exits
+../tar_texi/tar.texi(,3025) successfully. This option is intended for use in
shell scripts.
+../tar_texi/tar.texi(,3026) Here is an example of what you can see using this
option:
+../tar_texi/tar.texi(,3027)
+../tar_texi/tar.texi(,3028) @smallexample
+../tar_texi/tar.texi(,3029) $ tar --show-defaults
+../tar_texi/tar.texi(,3030) --format=gnu -f- -b20 --quoting-style=escape \
+../tar_texi/tar.texi(,3031) --rmt-command=/usr/libexec/rmt
--rsh-command=/usr/bin/rsh
+../tar_texi/tar.texi(,3032) @end smallexample
+../tar_texi/tar.texi(,3033)
+../tar_texi/tar.texi(opsummary,3034) @anchor{--show-omitted-dirs}
+../tar_texi/tar.texi(opsummary,3034) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3035) @item --show-omitted-dirs
+../tar_texi/tar.texi(,3036)
+../tar_texi/tar.texi(,3037) Instructs @command{tar} to mention directories its
skipping over when
+../tar_texi/tar.texi(,3038) operating on a @command{tar} archive.
@xref{show-omitted-dirs}.
+../tar_texi/tar.texi(,3039)
+../tar_texi/tar.texi(opsummary,3040) @anchor{--show-transformed-names}
+../tar_texi/tar.texi(opsummary,3040) @opindex address@hidden, summary}
+../tar_texi/tar.texi(opsummary,3041) @anchor{--show-stored-names}
+../tar_texi/tar.texi(opsummary,3041) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3042) @item --show-transformed-names
+../tar_texi/tar.texi(,3043) @itemx --show-stored-names
+../tar_texi/tar.texi(,3044)
+../tar_texi/tar.texi(,3045) Display file or member names after applying any
transformations
+../tar_texi/tar.texi(,3046) (@pxref{transform}). In particular, when used in
conjunction with one of
+../tar_texi/tar.texi(,3047) archive creation operations it instructs tar to
list the member names
+../tar_texi/tar.texi(,3048) stored in the archive, as opposed to the actual
file
+../tar_texi/tar.texi(,3049) names. @xref{listing member and file names}.
+../tar_texi/tar.texi(,3050)
+../tar_texi/tar.texi(opsummary,3051) @anchor{--sparse}
+../tar_texi/tar.texi(opsummary,3051) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3052) @item --sparse
+../tar_texi/tar.texi(,3053) @itemx -S
+../tar_texi/tar.texi(,3054)
+../tar_texi/tar.texi(,3055) Invokes a @acronym{GNU} extension when adding
files to an archive that handles
+../tar_texi/tar.texi(,3056) sparse files efficiently. @xref{sparse}.
+../tar_texi/tar.texi(,3057)
+../tar_texi/tar.texi(opsummary,3058) @anchor{--sparse-version}
+../tar_texi/tar.texi(opsummary,3058) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3059) @item address@hidden
+../tar_texi/tar.texi(,3060)
+../tar_texi/tar.texi(,3061) Specified the @dfn{format version} to use when
archiving sparse
+../tar_texi/tar.texi(,3062) files. Implies @option{--sparse}. @xref{sparse}.
For the description
+../tar_texi/tar.texi(,3063) of the supported sparse formats, @xref{Sparse
Formats}.
+../tar_texi/tar.texi(,3064)
+../tar_texi/tar.texi(opsummary,3065) @anchor{--starting-file}
+../tar_texi/tar.texi(opsummary,3065) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3066) @item address@hidden
+../tar_texi/tar.texi(,3067) @itemx -K @var{name}
+../tar_texi/tar.texi(,3068)
+../tar_texi/tar.texi(,3069) This option affects extraction only; @command{tar}
will skip extracting
+../tar_texi/tar.texi(,3070) files in the archive until it finds one that
matches @var{name}.
+../tar_texi/tar.texi(,3071) @xref{Scarce}.
+../tar_texi/tar.texi(,3072)
+../tar_texi/tar.texi(opsummary,3073) @anchor{--strip-components}
+../tar_texi/tar.texi(opsummary,3073) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3074) @item address@hidden
+../tar_texi/tar.texi(,3075) Strip given @var{number} of leading components
from file names before
+../tar_texi/tar.texi(,3076) address@hidden option was called
@option{--strip-path} in
+../tar_texi/tar.texi(,3077) version 1.14.} For example, if archive
@file{archive.tar} contained
+../tar_texi/tar.texi(,3078) @file{/some/file/name}, then running
+../tar_texi/tar.texi(,3079)
+../tar_texi/tar.texi(,3080) @smallexample
+../tar_texi/tar.texi(,3081) tar --extract --file archive.tar
--strip-components=2
+../tar_texi/tar.texi(,3082) @end smallexample
+../tar_texi/tar.texi(,3083)
+../tar_texi/tar.texi(,3084) @noindent
+../tar_texi/tar.texi(,3085) would extract this file to file @file{name}.
+../tar_texi/tar.texi(,3086)
+../tar_texi/tar.texi(opsummary,3087) @anchor{--suffix}
+../tar_texi/tar.texi(opsummary,3087) @opindex address@hidden, summary}, summary
+../tar_texi/tar.texi(,3088) @item address@hidden
+../tar_texi/tar.texi(,3089)
+../tar_texi/tar.texi(,3090) Alters the suffix @command{tar} uses when backing
up files from the default
+../tar_texi/tar.texi(,3091) @samp{~}. @xref{backup}.
+../tar_texi/tar.texi(,3092)
+../tar_texi/tar.texi(opsummary,3093) @anchor{--tape-length}
+../tar_texi/tar.texi(opsummary,3093) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3094) @item address@hidden
+../tar_texi/tar.texi(,3095) @itemx -L @var{num}
+../tar_texi/tar.texi(,3096)
+../tar_texi/tar.texi(,3097) Specifies the length of tapes that @command{tar}
is writing as being
+../tar_texi/tar.texi(,3098) @address@hidden x 1024} bytes long. @xref{Using
Multiple Tapes}.
+../tar_texi/tar.texi(,3099)
+../tar_texi/tar.texi(opsummary,3100) @anchor{--test-label}
+../tar_texi/tar.texi(opsummary,3100) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3101) @item --test-label
+../tar_texi/tar.texi(,3102)
+../tar_texi/tar.texi(,3103) Reads the volume label. If an argument is
specified, test whether it
+../tar_texi/tar.texi(,3104) matches the volume label. @xref{--test-label
option}.
+../tar_texi/tar.texi(,3105)
+../tar_texi/tar.texi(opsummary,3106) @anchor{--to-command}
+../tar_texi/tar.texi(opsummary,3106) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3107) @item address@hidden
+../tar_texi/tar.texi(,3108)
+../tar_texi/tar.texi(,3109) During extraction @command{tar} will pipe
extracted files to the
+../tar_texi/tar.texi(,3110) standard input of @var{command}. @xref{Writing to
an External Program}.
+../tar_texi/tar.texi(,3111)
+../tar_texi/tar.texi(opsummary,3112) @anchor{--to-stdout}
+../tar_texi/tar.texi(opsummary,3112) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3113) @item --to-stdout
+../tar_texi/tar.texi(,3114) @itemx -O
+../tar_texi/tar.texi(,3115)
+../tar_texi/tar.texi(,3116) During extraction, @command{tar} will extract
files to stdout rather
+../tar_texi/tar.texi(,3117) than to the file system. @xref{Writing to
Standard Output}.
+../tar_texi/tar.texi(,3118)
+../tar_texi/tar.texi(opsummary,3119) @anchor{--totals}
+../tar_texi/tar.texi(opsummary,3119) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3120) @item address@hidden
+../tar_texi/tar.texi(,3121)
+../tar_texi/tar.texi(,3122) Displays the total number of bytes transferred
when processing an
+../tar_texi/tar.texi(,3123) archive. If an argument is given, these data are
displayed on
+../tar_texi/tar.texi(,3124) request, when signal @var{signo} is delivered to
@command{tar}.
+../tar_texi/tar.texi(,3125) @xref{totals}.
+../tar_texi/tar.texi(,3126)
+../tar_texi/tar.texi(opsummary,3127) @anchor{--touch}
+../tar_texi/tar.texi(opsummary,3127) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3128) @item --touch
+../tar_texi/tar.texi(,3129) @itemx -m
+../tar_texi/tar.texi(,3130)
+../tar_texi/tar.texi(,3131) Sets the data modification time of extracted files
to the extraction time,
+../tar_texi/tar.texi(,3132) rather than the data modification time stored in
the archive.
+../tar_texi/tar.texi(,3133) @xref{Data Modification Times}.
+../tar_texi/tar.texi(,3134)
+../tar_texi/tar.texi(opsummary,3135) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3136) @item --uncompress
+../tar_texi/tar.texi(,3137)
+../tar_texi/tar.texi(,3138) (See @option{--compress}. @pxref{gzip})
+../tar_texi/tar.texi(,3139)
+../tar_texi/tar.texi(opsummary,3140) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3141) @item --ungzip
+../tar_texi/tar.texi(,3142)
+../tar_texi/tar.texi(,3143) (See @option{--gzip}. @pxref{gzip})
+../tar_texi/tar.texi(,3144)
+../tar_texi/tar.texi(opsummary,3145) @anchor{--unlink-first}
+../tar_texi/tar.texi(opsummary,3145) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3146) @item --unlink-first
+../tar_texi/tar.texi(,3147) @itemx -U
+../tar_texi/tar.texi(,3148)
+../tar_texi/tar.texi(,3149) Directs @command{tar} to remove the corresponding
file from the file
+../tar_texi/tar.texi(,3150) system before extracting it from the archive.
@xref{Unlink First}.
+../tar_texi/tar.texi(,3151)
+../tar_texi/tar.texi(opsummary,3152) @anchor{--unquote}
+../tar_texi/tar.texi(opsummary,3152) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3153) @item --unquote
+../tar_texi/tar.texi(,3154) Enable unquoting input file or member names
(default). @xref{input
+../tar_texi/tar.texi(,3155) name quoting}.
+../tar_texi/tar.texi(,3156)
+../tar_texi/tar.texi(opsummary,3157) @anchor{--use-compress-program}
+../tar_texi/tar.texi(opsummary,3157) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3158) @item address@hidden
+../tar_texi/tar.texi(,3159)
+../tar_texi/tar.texi(,3160) Instructs @command{tar} to access the archive
through @var{prog}, which is
+../tar_texi/tar.texi(,3161) presumed to be a compression program of some sort.
@xref{gzip}.
+../tar_texi/tar.texi(,3162)
+../tar_texi/tar.texi(opsummary,3163) @anchor{--utc}
+../tar_texi/tar.texi(opsummary,3163) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3164) @item --utc
+../tar_texi/tar.texi(,3165)
+../tar_texi/tar.texi(,3166) Display file modification dates in @acronym{UTC}.
This option implies
+../tar_texi/tar.texi(,3167) @option{--verbose}.
+../tar_texi/tar.texi(,3168)
+../tar_texi/tar.texi(opsummary,3169) @anchor{--verbose}
+../tar_texi/tar.texi(opsummary,3169) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3170) @item --verbose
+../tar_texi/tar.texi(,3171) @itemx -v
+../tar_texi/tar.texi(,3172)
+../tar_texi/tar.texi(,3173) Specifies that @command{tar} should be more
verbose about the operations its
+../tar_texi/tar.texi(,3174) performing. This option can be specified multiple
times for some
+../tar_texi/tar.texi(,3175) operations to increase the amount of information
displayed.
+../tar_texi/tar.texi(,3176) @xref{verbose}.
+../tar_texi/tar.texi(,3177)
+../tar_texi/tar.texi(opsummary,3178) @anchor{--verify}
+../tar_texi/tar.texi(opsummary,3178) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3179) @item --verify
+../tar_texi/tar.texi(,3180) @itemx -W
+../tar_texi/tar.texi(,3181)
+../tar_texi/tar.texi(,3182) Verifies that the archive was correctly written
when creating an
+../tar_texi/tar.texi(,3183) archive. @xref{verify}.
+../tar_texi/tar.texi(,3184)
+../tar_texi/tar.texi(opsummary,3185) @anchor{--version}
+../tar_texi/tar.texi(opsummary,3185) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3186) @item --version
+../tar_texi/tar.texi(,3187)
+../tar_texi/tar.texi(,3188) Print information about the program's name,
version, origin and legal
+../tar_texi/tar.texi(,3189) status, all on standard output, and then exit
successfully.
+../tar_texi/tar.texi(,3190) @xref{help}.
+../tar_texi/tar.texi(,3191)
+../tar_texi/tar.texi(opsummary,3192) @anchor{--volno-file}
+../tar_texi/tar.texi(opsummary,3192) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3193) @item address@hidden
+../tar_texi/tar.texi(,3194)
+../tar_texi/tar.texi(,3195) Used in conjunction with @option{--multi-volume}.
@command{tar} will
+../tar_texi/tar.texi(,3196) keep track of which volume of a multi-volume
archive its working in
+../tar_texi/tar.texi(,3197) @var{file}. @xref{volno-file}.
+../tar_texi/tar.texi(,3198)
+../tar_texi/tar.texi(opsummary,3199) @anchor{--wildcards}
+../tar_texi/tar.texi(opsummary,3199) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3200) @item --wildcards
+../tar_texi/tar.texi(,3201) Use wildcards when matching member names with
patterns.
+../tar_texi/tar.texi(,3202) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,3203)
+../tar_texi/tar.texi(opsummary,3204) @anchor{--wildcards-match-slash}
+../tar_texi/tar.texi(opsummary,3204) @opindex address@hidden, summary}
+../tar_texi/tar.texi(,3205) @item --wildcards-match-slash
+../tar_texi/tar.texi(,3206) Wildcards match @samp{/}.
+../tar_texi/tar.texi(,3207) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,3208) @end table
+../tar_texi/tar.texi(,3209)
+../tar_texi/tar.texi(,3210) @node Short Option Summary
+../tar_texi/tar.texi(,3211) @subsection Short Options Cross Reference
+../tar_texi/tar.texi(,3212)
+../tar_texi/tar.texi(,3213) Here is an alphabetized list of all of the short
option forms, matching
+../tar_texi/tar.texi(,3214) them with the equivalent long option.
+../tar_texi/tar.texi(,3215)
+../tar_texi/tar.texi(,3216) @multitable @columnfractions 0.20 0.80
+../tar_texi/tar.texi(,3217) @headitem Short Option @tab Reference
+../tar_texi/tar.texi(,3218)
+../tar_texi/tar.texi(,3219) @item -A @tab @ref{--concatenate}.
+../tar_texi/tar.texi(,3220)
+../tar_texi/tar.texi(,3221) @item -B @tab @ref{--read-full-records}.
+../tar_texi/tar.texi(,3222)
+../tar_texi/tar.texi(,3223) @item -C @tab @ref{--directory}.
+../tar_texi/tar.texi(,3224)
+../tar_texi/tar.texi(,3225) @item -F @tab @ref{--info-script}.
+../tar_texi/tar.texi(,3226)
+../tar_texi/tar.texi(,3227) @item -G @tab @ref{--incremental}.
+../tar_texi/tar.texi(,3228)
+../tar_texi/tar.texi(,3229) @item -K @tab @ref{--starting-file}.
+../tar_texi/tar.texi(,3230)
+../tar_texi/tar.texi(,3231) @item -L @tab @ref{--tape-length}.
+../tar_texi/tar.texi(,3232)
+../tar_texi/tar.texi(,3233) @item -M @tab @ref{--multi-volume}.
+../tar_texi/tar.texi(,3234)
+../tar_texi/tar.texi(,3235) @item -N @tab @ref{--newer}.
+../tar_texi/tar.texi(,3236)
+../tar_texi/tar.texi(,3237) @item -O @tab @ref{--to-stdout}.
+../tar_texi/tar.texi(,3238)
+../tar_texi/tar.texi(,3239) @item -P @tab @ref{--absolute-names}.
+../tar_texi/tar.texi(,3240)
+../tar_texi/tar.texi(,3241) @item -R @tab @ref{--block-number}.
+../tar_texi/tar.texi(,3242)
+../tar_texi/tar.texi(,3243) @item -S @tab @ref{--sparse}.
+../tar_texi/tar.texi(,3244)
+../tar_texi/tar.texi(,3245) @item -T @tab @ref{--files-from}.
+../tar_texi/tar.texi(,3246)
+../tar_texi/tar.texi(,3247) @item -U @tab @ref{--unlink-first}.
+../tar_texi/tar.texi(,3248)
+../tar_texi/tar.texi(,3249) @item -V @tab @ref{--label}.
+../tar_texi/tar.texi(,3250)
+../tar_texi/tar.texi(,3251) @item -W @tab @ref{--verify}.
+../tar_texi/tar.texi(,3252)
+../tar_texi/tar.texi(,3253) @item -X @tab @ref{--exclude-from}.
+../tar_texi/tar.texi(,3254)
+../tar_texi/tar.texi(,3255) @item -Z @tab @ref{--compress}.
+../tar_texi/tar.texi(,3256)
+../tar_texi/tar.texi(,3257) @item -b @tab @ref{--blocking-factor}.
+../tar_texi/tar.texi(,3258)
+../tar_texi/tar.texi(,3259) @item -c @tab @ref{--create}.
+../tar_texi/tar.texi(,3260)
+../tar_texi/tar.texi(,3261) @item -d @tab @ref{--compare}.
+../tar_texi/tar.texi(,3262)
+../tar_texi/tar.texi(,3263) @item -f @tab @ref{--file}.
+../tar_texi/tar.texi(,3264)
+../tar_texi/tar.texi(,3265) @item -g @tab @ref{--listed-incremental}.
+../tar_texi/tar.texi(,3266)
+../tar_texi/tar.texi(,3267) @item -h @tab @ref{--dereference}.
+../tar_texi/tar.texi(,3268)
+../tar_texi/tar.texi(,3269) @item -i @tab @ref{--ignore-zeros}.
+../tar_texi/tar.texi(,3270)
+../tar_texi/tar.texi(,3271) @item -j @tab @ref{--bzip2}.
+../tar_texi/tar.texi(,3272)
+../tar_texi/tar.texi(,3273) @item -k @tab @ref{--keep-old-files}.
+../tar_texi/tar.texi(,3274)
+../tar_texi/tar.texi(,3275) @item -l @tab @ref{--check-links}.
+../tar_texi/tar.texi(,3276)
+../tar_texi/tar.texi(,3277) @item -m @tab @ref{--touch}.
+../tar_texi/tar.texi(,3278)
+../tar_texi/tar.texi(,3279) @item -o @tab When creating,
@ref{--no-same-owner}, when extracting ---
+../tar_texi/tar.texi(,3280) @ref{--portability}.
+../tar_texi/tar.texi(,3281)
+../tar_texi/tar.texi(,3282) The later usage is deprecated. It is retained for
compatibility with
+../tar_texi/tar.texi(GNUTAR,3283) the earlier versions of @acronym{GNU}
@command{tar}. In the future releases
+../tar_texi/tar.texi(,3284) @option{-o} will be equivalent to
@option{--no-same-owner} only.
+../tar_texi/tar.texi(,3285)
+../tar_texi/tar.texi(,3286) @item -p @tab @ref{--preserve-permissions}.
+../tar_texi/tar.texi(,3287)
+../tar_texi/tar.texi(,3288) @item -r @tab @ref{--append}.
+../tar_texi/tar.texi(,3289)
+../tar_texi/tar.texi(,3290) @item -s @tab @ref{--same-order}.
+../tar_texi/tar.texi(,3291)
+../tar_texi/tar.texi(,3292) @item -t @tab @ref{--list}.
+../tar_texi/tar.texi(,3293)
+../tar_texi/tar.texi(,3294) @item -u @tab @ref{--update}.
+../tar_texi/tar.texi(,3295)
+../tar_texi/tar.texi(,3296) @item -v @tab @ref{--verbose}.
+../tar_texi/tar.texi(,3297)
+../tar_texi/tar.texi(,3298) @item -w @tab @ref{--interactive}.
+../tar_texi/tar.texi(,3299)
+../tar_texi/tar.texi(,3300) @item -x @tab @ref{--extract}.
+../tar_texi/tar.texi(,3301)
+../tar_texi/tar.texi(,3302) @item -z @tab @ref{--gzip}.
+../tar_texi/tar.texi(,3303)
+../tar_texi/tar.texi(,3304) @end multitable
+../tar_texi/tar.texi(,3305)
+../tar_texi/tar.texi(,3306) @node help
+../tar_texi/tar.texi(GNUTAR,3307) @section @acronym{GNU} @command{tar}
documentation
+../tar_texi/tar.texi(,3308)
+../tar_texi/tar.texi(,3309) @cindex Getting program version number
+../tar_texi/tar.texi(,3310) @opindex version
+../tar_texi/tar.texi(,3311) @cindex Version of the @command{tar} program
+../tar_texi/tar.texi(,3312) Being careful, the first thing is really checking
that you are using
+../tar_texi/tar.texi(GNUTAR,3313) @acronym{GNU} @command{tar}, indeed. The
@option{--version} option
+../tar_texi/tar.texi(,3314) causes @command{tar} to print information about
its name, version,
+../tar_texi/tar.texi(,3315) origin and legal status, all on standard output,
and then exit
+../tar_texi/tar.texi(,3316) successfully. For example, @address@hidden
--version}} might print:
+../tar_texi/tar.texi(,3317)
+../tar_texi/tar.texi(,3318) @smallexample
+../tar_texi/tar.texi(,3319) tar (GNU tar) 1.15.92
+../tar_texi/tar.texi(,3320) Copyright (C) 2006 Free Software Foundation, Inc.
+../tar_texi/tar.texi(,3321) This is free software. You may redistribute
copies of it under the terms
+../tar_texi/tar.texi(,3322) of the GNU General Public License
<http://www.gnu.org/licenses/gpl.html>.
+../tar_texi/tar.texi(,3323) There is NO WARRANTY, to the extent permitted by
law.
+../tar_texi/tar.texi(,3324)
+../tar_texi/tar.texi(,3325) Written by John Gilmore and Jay Fenlason.
+../tar_texi/tar.texi(,3326) @end smallexample
+../tar_texi/tar.texi(,3327)
+../tar_texi/tar.texi(,3328) @noindent
+../tar_texi/tar.texi(,3329) The first occurrence of @samp{tar} in the result
above is the program
+../tar_texi/tar.texi(,3330) name in the package (for example, @command{rmt} is
another program),
+../tar_texi/tar.texi(,3331) while the second occurrence of @samp{tar} is the
name of the package
+../tar_texi/tar.texi(,3332) itself, containing possibly many programs. The
package is currently
+../tar_texi/tar.texi(,3333) named @samp{tar}, after the name of the main
program it
+../tar_texi/tar.texi(,3334) address@hidden are plans to merge the
@command{cpio} and
+../tar_texi/tar.texi(,3335) @command{tar} packages into a single one which
would be called
+../tar_texi/tar.texi(,3336) @code{paxutils}. So, who knows if, one of this
days, the
+../tar_texi/tar.texi(,3337) @option{--version} would not output
@address@hidden (@acronym{GNU}
+../tar_texi/tar.texi(,3338) paxutils) 3.2}}}.
+../tar_texi/tar.texi(,3339)
+../tar_texi/tar.texi(,3340) @cindex Obtaining help
+../tar_texi/tar.texi(,3341) @cindex Listing all @command{tar} options
+../tar_texi/tar.texi(xopindex,3342) @opindex address@hidden, introduction}
+../tar_texi/tar.texi(,3343) Another thing you might want to do is checking the
spelling or meaning
+../tar_texi/tar.texi(,3344) of some particular @command{tar} option, without
resorting to this
+../tar_texi/tar.texi(GNUTAR,3345) manual, for once you have carefully read it.
@acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,3346) has a short help feature, triggerable through the
+../tar_texi/tar.texi(,3347) @option{--help} option. By using this option,
@command{tar} will
+../tar_texi/tar.texi(,3348) print a usage message listing all available
options on standard
+../tar_texi/tar.texi(,3349) output, then exit successfully, without doing
anything else and
+../tar_texi/tar.texi(,3350) ignoring all other options. Even if this is only
a brief summary, it
+../tar_texi/tar.texi(,3351) may be several screens long. So, if you are not
using some kind of
+../tar_texi/tar.texi(,3352) scrollable window, you might prefer to use
something like:
+../tar_texi/tar.texi(,3353)
+../tar_texi/tar.texi(,3354) @smallexample
+../tar_texi/tar.texi(,3355) $ @kbd{tar --help | less}
+../tar_texi/tar.texi(,3356) @end smallexample
+../tar_texi/tar.texi(,3357)
+../tar_texi/tar.texi(,3358) @noindent
+../tar_texi/tar.texi(,3359) presuming, here, that you like using
@command{less} for a pager. Other
+../tar_texi/tar.texi(,3360) popular pagers are @command{more} and
@command{pg}. If you know about some
+../tar_texi/tar.texi(,3361) @var{keyword} which interests you and do not want
to read all the
+../tar_texi/tar.texi(,3362) @option{--help} output, another common idiom is
doing:
+../tar_texi/tar.texi(,3363)
+../tar_texi/tar.texi(,3364) @smallexample
+../tar_texi/tar.texi(,3365) tar --help | grep @var{keyword}
+../tar_texi/tar.texi(,3366) @end smallexample
+../tar_texi/tar.texi(,3367)
+../tar_texi/tar.texi(,3368) @noindent
+../tar_texi/tar.texi(,3369) for getting only the pertinent lines. Notice,
however, that some
+../tar_texi/tar.texi(,3370) @command{tar} options have long description lines
and the above
+../tar_texi/tar.texi(,3371) command will list only the first of them.
+../tar_texi/tar.texi(,3372)
+../tar_texi/tar.texi(,3373) The exact look of the option summary displayed by
@kbd{tar --help} is
+../tar_texi/tar.texi(,3374) configurable. @xref{Configuring Help Summary}, for
a detailed description.
+../tar_texi/tar.texi(,3375)
+../tar_texi/tar.texi(,3376) @opindex usage
+../tar_texi/tar.texi(,3377) If you only wish to check the spelling of an
option, running @kbd{tar
+../tar_texi/tar.texi(,3378) --usage} may be a better choice. This will
display a terse list of
+../tar_texi/tar.texi(,3379) @command{tar} option without accompanying
explanations.
+../tar_texi/tar.texi(,3380)
+../tar_texi/tar.texi(,3381) The short help output is quite succinct, and you
might have to get
+../tar_texi/tar.texi(,3382) back to the full documentation for precise points.
If you are reading
+../tar_texi/tar.texi(,3383) this paragraph, you already have the @command{tar}
manual in some
+../tar_texi/tar.texi(,3384) form. This manual is available in a variety of
forms from
+../tar_texi/tar.texi(GNUTAR,3385)
@url{http://www.gnu.org/software/tar/manual}. It may be printed out of the
@acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,3386) distribution, provided you have @TeX{} already
installed somewhere,
+../tar_texi/tar.texi(,3387) and a laser printer around. Just configure the
distribution, execute
+../tar_texi/tar.texi(,3388) the command @address@hidden dvi}}, then print
@file{doc/tar.dvi} the
+../tar_texi/tar.texi(GNUTAR,3389) usual way (contact your local guru to know
how). If @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,3390) has been conveniently installed at your place, this
+../tar_texi/tar.texi(,3391) manual is also available in interactive,
hypertextual form as an Info
+../tar_texi/tar.texi(,3392) file. Just call @address@hidden tar}} or, if you
do not have the
+../tar_texi/tar.texi(,3393) @command{info} program handy, use the Info reader
provided within
+../tar_texi/tar.texi(,3394) @acronym{GNU} Emacs, calling @samp{tar} from the
main Info menu.
+../tar_texi/tar.texi(,3395)
+../tar_texi/tar.texi(GNUTAR,3396) There is currently no @code{man} page for
@acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,3397) If you observe such a @code{man} page on the
system you are running,
+../tar_texi/tar.texi(GNUTAR,3398) either it does not belong to @acronym{GNU}
@command{tar}, or it has not
+../tar_texi/tar.texi(,3399) been produced by @acronym{GNU}. Some package
maintainers convert
+../tar_texi/tar.texi(,3400) @kbd{tar --help} output to a man page, using
@command{help2man}. In
+../tar_texi/tar.texi(,3401) any case, please bear in mind that the
authoritative source of
+../tar_texi/tar.texi(GNUTAR,3402) information about @acronym{GNU}
@command{tar} is this Texinfo documentation.
+../tar_texi/tar.texi(,3403)
+../tar_texi/tar.texi(,3404) @node defaults
+../tar_texi/tar.texi(GNUTAR,3405) @section Obtaining @acronym{GNU}
@command{tar} default values
+../tar_texi/tar.texi(,3406)
+../tar_texi/tar.texi(,3407) @opindex show-defaults
+../tar_texi/tar.texi(GNUTAR,3408) @acronym{GNU} @command{tar} has some
predefined defaults that are used when you do not
+../tar_texi/tar.texi(,3409) explicitely specify another values. To obtain a
list of such
+../tar_texi/tar.texi(,3410) defaults, use @option{--show-defaults} option.
This will output the
+../tar_texi/tar.texi(,3411) values in the form of @command{tar} command line
options:
+../tar_texi/tar.texi(,3412)
+../tar_texi/tar.texi(,3413) @smallexample
+../tar_texi/tar.texi(,3414) @group
+../tar_texi/tar.texi(,3415) @kbd{tar --show-defaults}
+../tar_texi/tar.texi(,3416) --format=gnu -f- -b20 --quoting-style=escape
+../tar_texi/tar.texi(,3417) --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
+../tar_texi/tar.texi(,3418) @end group
+../tar_texi/tar.texi(,3419) @end smallexample
+../tar_texi/tar.texi(,3420)
+../tar_texi/tar.texi(,3421) @noindent
+../tar_texi/tar.texi(,3422) Notice, that this option outputs only one line.
The example output above
+../tar_texi/tar.texi(,3423) has been split to fit page boundaries.
+../tar_texi/tar.texi(,3424)
+../tar_texi/tar.texi(,3425) @noindent
+../tar_texi/tar.texi(GNUTAR,3426) The above output shows that this version of
@acronym{GNU} @command{tar} defaults to
+../tar_texi/tar.texi(,3427) using @samp{gnu} archive format (@pxref{Formats}),
it uses standard
+../tar_texi/tar.texi(,3428) output as the archive, if no @option{--file}
option has been given
+../tar_texi/tar.texi(,3429) (@pxref{file tutorial}), the default blocking
factor is 20
+../tar_texi/tar.texi(,3430) (@pxref{Blocking Factor}). It also shows the
default locations where
+../tar_texi/tar.texi(,3431) @command{tar} will look for @command{rmt} and
@command{rsh} binaries.
+../tar_texi/tar.texi(,3432)
+../tar_texi/tar.texi(,3433) @node verbose
+../tar_texi/tar.texi(,3434) @section Checking @command{tar} progress
+../tar_texi/tar.texi(,3435)
+../tar_texi/tar.texi(,3436) Typically, @command{tar} performs most operations
without reporting any
+../tar_texi/tar.texi(,3437) information to the user except error messages.
When using @command{tar}
+../tar_texi/tar.texi(,3438) with many options, particularly ones with
complicated or
+../tar_texi/tar.texi(,3439) difficult-to-predict behavior, it is possible to
make serious mistakes.
+../tar_texi/tar.texi(,3440) @command{tar} provides several options that make
observing @command{tar}
+../tar_texi/tar.texi(,3441) easier. These options cause @command{tar} to
print information as it
+../tar_texi/tar.texi(,3442) progresses in its job, and you might want to use
them just for being
+../tar_texi/tar.texi(,3443) more careful about what is going on, or merely for
entertaining
+../tar_texi/tar.texi(,3444) yourself. If you have encountered a problem when
operating on an
+../tar_texi/tar.texi(,3445) archive, however, you may need more information
than just an error
+../tar_texi/tar.texi(,3446) message in order to solve the problem. The
following options can be
+../tar_texi/tar.texi(,3447) helpful diagnostic tools.
+../tar_texi/tar.texi(,3448)
+../tar_texi/tar.texi(,3449) @cindex Verbose operation
+../tar_texi/tar.texi(,3450) @opindex verbose
+../tar_texi/tar.texi(,3451) Normally, the @option{--list} (@option{-t})
command to list an archive
+../tar_texi/tar.texi(,3452) prints just the file names (one per line) and the
other commands are
+../tar_texi/tar.texi(,3453) silent. When used with most operations, the
@option{--verbose}
+../tar_texi/tar.texi(,3454) (@option{-v}) option causes @command{tar} to print
the name of each
+../tar_texi/tar.texi(,3455) file or archive member as it is processed. This
and the other options
+../tar_texi/tar.texi(,3456) which make @command{tar} print status information
can be useful in
+../tar_texi/tar.texi(,3457) monitoring @command{tar}.
+../tar_texi/tar.texi(,3458)
+../tar_texi/tar.texi(,3459) With @option{--create} or @option{--extract},
@option{--verbose} used
+../tar_texi/tar.texi(,3460) once just prints the names of the files or members
as they are processed.
+../tar_texi/tar.texi(,3461) Using it twice causes @command{tar} to print a
longer listing
+../tar_texi/tar.texi(,3462) (@xref{verbose member listing}, for the
description) for each member.
+../tar_texi/tar.texi(,3463) Since @option{--list} already prints the names of
the members,
+../tar_texi/tar.texi(,3464) @option{--verbose} used once with @option{--list}
causes @command{tar}
+../tar_texi/tar.texi(,3465) to print an @samp{ls -l} type listing of the files
in the archive.
+../tar_texi/tar.texi(,3466) The following examples both extract members with
long list output:
+../tar_texi/tar.texi(,3467)
+../tar_texi/tar.texi(,3468) @smallexample
+../tar_texi/tar.texi(,3469) $ @kbd{tar --extract --file=archive.tar --verbose
--verbose}
+../tar_texi/tar.texi(,3470) $ @kbd{tar xvvf archive.tar}
+../tar_texi/tar.texi(,3471) @end smallexample
+../tar_texi/tar.texi(,3472)
+../tar_texi/tar.texi(,3473) Verbose output appears on the standard output
except when an archive is
+../tar_texi/tar.texi(,3474) being written to the standard output, as with
@samp{tar --create
+../tar_texi/tar.texi(,3475) --file=- --verbose} (@samp{tar cfv -}, or even
@samp{tar cv}---if the
+../tar_texi/tar.texi(,3476) installer let standard output be the default
archive). In that case
+../tar_texi/tar.texi(,3477) @command{tar} writes verbose output to the
standard error stream.
+../tar_texi/tar.texi(,3478)
+../tar_texi/tar.texi(,3479) If @address@hidden is specified, @command{tar}
sends
+../tar_texi/tar.texi(,3480) verbose output to @var{file} rather than to
standard output or standard
+../tar_texi/tar.texi(,3481) error.
+../tar_texi/tar.texi(,3482)
+../tar_texi/tar.texi(,3483) @anchor{totals}
+../tar_texi/tar.texi(,3484) @cindex Obtaining total status information
+../tar_texi/tar.texi(,3485) @opindex totals
+../tar_texi/tar.texi(,3486) The @option{--totals} option causes @command{tar}
to print on the
+../tar_texi/tar.texi(,3487) standard error the total amount of bytes
transferred when processing
+../tar_texi/tar.texi(,3488) an archive. When creating or appending to an
archive, this option
+../tar_texi/tar.texi(,3489) prints the number of bytes written to the archive
and the average
+../tar_texi/tar.texi(,3490) speed at which they have been written, e.g.:
+../tar_texi/tar.texi(,3491)
+../tar_texi/tar.texi(,3492) @smallexample
+../tar_texi/tar.texi(,3493) @group
+../tar_texi/tar.texi(,3494) $ @kbd{tar -c -f archive.tar --totals /home}
+../tar_texi/tar.texi(,3495) Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
+../tar_texi/tar.texi(,3496) @end group
+../tar_texi/tar.texi(,3497) @end smallexample
+../tar_texi/tar.texi(,3498)
+../tar_texi/tar.texi(,3499) When reading an archive, this option displays the
number of bytes
+../tar_texi/tar.texi(,3500) read:
+../tar_texi/tar.texi(,3501)
+../tar_texi/tar.texi(,3502) @smallexample
+../tar_texi/tar.texi(,3503) @group
+../tar_texi/tar.texi(,3504) $ @kbd{tar -x -f archive.tar --totals}
+../tar_texi/tar.texi(,3505) Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
+../tar_texi/tar.texi(,3506) @end group
+../tar_texi/tar.texi(,3507) @end smallexample
+../tar_texi/tar.texi(,3508)
+../tar_texi/tar.texi(,3509) Finally, when deleting from an archive, the
@option{--totals} option
+../tar_texi/tar.texi(,3510) displays both numbers plus number of bytes removed
from the archive:
+../tar_texi/tar.texi(,3511)
+../tar_texi/tar.texi(,3512) @smallexample
+../tar_texi/tar.texi(,3513) @group
+../tar_texi/tar.texi(,3514) $ @kbd{tar --delete -f foo.tar --totals
--wildcards '*~'}
+../tar_texi/tar.texi(,3515) Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+../tar_texi/tar.texi(,3516) Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+../tar_texi/tar.texi(,3517) Total bytes deleted: 1474048
+../tar_texi/tar.texi(,3518) @end group
+../tar_texi/tar.texi(,3519) @end smallexample
+../tar_texi/tar.texi(,3520)
+../tar_texi/tar.texi(,3521) You can also obtain this information on request.
When
+../tar_texi/tar.texi(,3522) @option{--totals} is used with an argument, this
argument is
+../tar_texi/tar.texi(,3523) interpreted as a symbolic name of a signal, upon
delivery of which the
+../tar_texi/tar.texi(,3524) statistics is to be printed:
+../tar_texi/tar.texi(,3525)
+../tar_texi/tar.texi(,3526) @table @option
+../tar_texi/tar.texi(,3527) @item address@hidden
+../tar_texi/tar.texi(,3528) Print statistics upon delivery of signal
@var{signo}. Valid arguments
+../tar_texi/tar.texi(,3529) are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT},
@code{SIGUSR1} and
+../tar_texi/tar.texi(,3530) @code{SIGUSR2}. Shortened names without
@samp{SIG} prefix are also
+../tar_texi/tar.texi(,3531) accepted.
+../tar_texi/tar.texi(,3532) @end table
+../tar_texi/tar.texi(,3533)
+../tar_texi/tar.texi(,3534) Both forms of @option{--totals} option can be used
simultaneously.
+../tar_texi/tar.texi(,3535) Thus, @kbd{tar -x --totals --totals=USR1}
instructs @command{tar} to
+../tar_texi/tar.texi(,3536) extract all members from its default archive and
print statistics
+../tar_texi/tar.texi(,3537) after finishing the extraction, as well as when
receiving signal
+../tar_texi/tar.texi(,3538) @code{SIGUSR1}.
+../tar_texi/tar.texi(,3539)
+../tar_texi/tar.texi(,3540) @anchor{Progress information}
+../tar_texi/tar.texi(,3541) @cindex Progress information
+../tar_texi/tar.texi(,3542) @opindex checkpoint
+../tar_texi/tar.texi(,3543) The @option{--checkpoint} option prints an
occasional message
+../tar_texi/tar.texi(,3544) as @command{tar} reads or writes the archive. It
is designed for
+../tar_texi/tar.texi(,3545) those who don't need the more detailed (and
voluminous) output of
+../tar_texi/tar.texi(,3546) @option{--block-number} (@option{-R}), but do want
visual confirmation
+../tar_texi/tar.texi(,3547) that @command{tar} is actually making forward
progress. By default it
+../tar_texi/tar.texi(,3548) prints a message each 10 records read or written.
This can be changed
+../tar_texi/tar.texi(,3549) by giving it a numeric argument after an equal
sign:
+../tar_texi/tar.texi(,3550)
+../tar_texi/tar.texi(,3551) @smallexample
+../tar_texi/tar.texi(,3552) $ @kbd{tar -c --checkpoint=1000} /var
+../tar_texi/tar.texi(,3553) tar: Write checkpoint 1000
+../tar_texi/tar.texi(,3554) tar: Write checkpoint 2000
+../tar_texi/tar.texi(,3555) tar: Write checkpoint 3000
+../tar_texi/tar.texi(,3556) @end smallexample
+../tar_texi/tar.texi(,3557)
+../tar_texi/tar.texi(,3558) This example shows the default checkpoint message
used by
+../tar_texi/tar.texi(,3559) @command{tar}. If you place a dot immediately
after the equal
+../tar_texi/tar.texi(,3560) sign, it will print a @samp{.} at each checkpoint.
For example:
+../tar_texi/tar.texi(,3561)
+../tar_texi/tar.texi(,3562) @smallexample
+../tar_texi/tar.texi(,3563) $ @kbd{tar -c --checkpoint=.1000} /var
+../tar_texi/tar.texi(,3564) ...
+../tar_texi/tar.texi(,3565) @end smallexample
+../tar_texi/tar.texi(,3566)
+../tar_texi/tar.texi(,3567) @opindex show-omitted-dirs
+../tar_texi/tar.texi(,3568) @anchor{show-omitted-dirs}
+../tar_texi/tar.texi(,3569) The @option{--show-omitted-dirs} option, when
reading an archive---with
+../tar_texi/tar.texi(,3570) @option{--list} or @option{--extract}, for
example---causes a message
+../tar_texi/tar.texi(,3571) to be printed for each directory in the archive
which is skipped.
+../tar_texi/tar.texi(,3572) This happens regardless of the reason for
skipping: the directory might
+../tar_texi/tar.texi(,3573) not have been named on the command line
(implicitly or explicitly),
+../tar_texi/tar.texi(,3574) it might be excluded by the use of the
+../tar_texi/tar.texi(,3575) @address@hidden option, or some other reason.
+../tar_texi/tar.texi(,3576)
+../tar_texi/tar.texi(,3577) @opindex block-number
+../tar_texi/tar.texi(,3578) @cindex Block number where error occurred
+../tar_texi/tar.texi(,3579) @anchor{block-number}
+../tar_texi/tar.texi(,3580) If @option{--block-number} (@option{-R}) is used,
@command{tar} prints, along with
+../tar_texi/tar.texi(,3581) every message it would normally produce, the block
number within the
+../tar_texi/tar.texi(,3582) archive where the message was triggered. Also,
supplementary messages
+../tar_texi/tar.texi(,3583) are triggered when reading blocks full of NULs, or
when hitting end of
+../tar_texi/tar.texi(,3584) file on the archive. As of now, if the archive if
properly terminated
+../tar_texi/tar.texi(,3585) with a NUL block, the reading of the file may stop
before end of file
+../tar_texi/tar.texi(,3586) is met, so the position of end of file will not
usually show when
+../tar_texi/tar.texi(GNUTAR,3587) @option{--block-number} (@option{-R}) is
used. Note that @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,3588) drains the archive before exiting when reading the
+../tar_texi/tar.texi(,3589) archive from a pipe.
+../tar_texi/tar.texi(,3590)
+../tar_texi/tar.texi(,3591) @cindex Error message, block number of
+../tar_texi/tar.texi(,3592) This option is especially useful when reading
damaged archives, since
+../tar_texi/tar.texi(,3593) it helps pinpoint the damaged sections. It can
also be used with
+../tar_texi/tar.texi(,3594) @option{--list} (@option{-t}) when listing a
file-system backup tape, allowing you to
+../tar_texi/tar.texi(,3595) choose among several backup tapes when retrieving
a file later, in
+../tar_texi/tar.texi(,3596) favor of the tape where the file appears earliest
(closest to the
+../tar_texi/tar.texi(,3597) front of the tape). @xref{backup}.
+../tar_texi/tar.texi(,3598)
+../tar_texi/tar.texi(,3599) @node interactive
+../tar_texi/tar.texi(,3600) @section Asking for Confirmation During Operations
+../tar_texi/tar.texi(,3601) @cindex Interactive operation
+../tar_texi/tar.texi(,3602)
+../tar_texi/tar.texi(,3603) Typically, @command{tar} carries out a command
without stopping for
+../tar_texi/tar.texi(,3604) further instructions. In some situations however,
you may want to
+../tar_texi/tar.texi(,3605) exclude some files and archive members from the
operation (for instance
+../tar_texi/tar.texi(,3606) if disk or storage space is tight). You can do
this by excluding
+../tar_texi/tar.texi(,3607) certain files automatically (@pxref{Choosing}), or
by performing
+../tar_texi/tar.texi(,3608) an operation interactively, using the
@option{--interactive} (@option{-w}) option.
+../tar_texi/tar.texi(,3609) @command{tar} also accepts @option{--confirmation}
for this option.
+../tar_texi/tar.texi(,3610)
+../tar_texi/tar.texi(,3611) @opindex interactive
+../tar_texi/tar.texi(,3612) When the @option{--interactive} (@option{-w})
option is specified, before
+../tar_texi/tar.texi(,3613) reading, writing, or deleting files, @command{tar}
first prints a message
+../tar_texi/tar.texi(,3614) for each such file, telling what operation it
intends to take, then asks
+../tar_texi/tar.texi(,3615) for confirmation on the terminal. The actions
which require
+../tar_texi/tar.texi(,3616) confirmation include adding a file to the archive,
extracting a file
+../tar_texi/tar.texi(,3617) from the archive, deleting a file from the
archive, and deleting a file
+../tar_texi/tar.texi(,3618) from disk. To confirm the action, you must type a
line of input
+../tar_texi/tar.texi(,3619) beginning with @samp{y}. If your input line
begins with anything other
+../tar_texi/tar.texi(,3620) than @samp{y}, @command{tar} skips that file.
+../tar_texi/tar.texi(,3621)
+../tar_texi/tar.texi(,3622) If @command{tar} is reading the archive from the
standard input,
+../tar_texi/tar.texi(,3623) @command{tar} opens the file @file{/dev/tty} to
support the interactive
+../tar_texi/tar.texi(,3624) communications.
+../tar_texi/tar.texi(,3625)
+../tar_texi/tar.texi(,3626) Verbose output is normally sent to standard
output, separate from
+../tar_texi/tar.texi(,3627) other error messages. However, if the archive is
produced directly
+../tar_texi/tar.texi(,3628) on standard output, then verbose output is mixed
with errors on
+../tar_texi/tar.texi(,3629) @code{stderr}. Producing the archive on standard
output may be used
+../tar_texi/tar.texi(,3630) as a way to avoid using disk space, when the
archive is soon to be
+../tar_texi/tar.texi(,3631) consumed by another process reading it, say. Some
people felt the need
+../tar_texi/tar.texi(,3632) of producing an archive on stdout, still willing
to segregate between
+../tar_texi/tar.texi(,3633) verbose output and error output. A possible
approach would be using a
+../tar_texi/tar.texi(,3634) named pipe to receive the archive, and having the
consumer process to
+../tar_texi/tar.texi(,3635) read from that named pipe. This has the advantage
of letting standard
+../tar_texi/tar.texi(,3636) output free to receive verbose output, all
separate from errors.
+../tar_texi/tar.texi(,3637)
+../tar_texi/tar.texi(,3638) @node operations
+../tar_texi/tar.texi(GNUTAR,3639) @chapter @acronym{GNU} @command{tar}
Operations
+../tar_texi/tar.texi(,3640)
+../tar_texi/tar.texi(,3641) @menu
+../tar_texi/tar.texi(,3642) * Basic tar::
+../tar_texi/tar.texi(,3643) * Advanced tar::
+../tar_texi/tar.texi(,3644) * create options::
+../tar_texi/tar.texi(,3645) * extract options::
+../tar_texi/tar.texi(,3646) * backup::
+../tar_texi/tar.texi(,3647) * Applications::
+../tar_texi/tar.texi(,3648) * looking ahead::
+../tar_texi/tar.texi(,3649) @end menu
+../tar_texi/tar.texi(,3650)
+../tar_texi/tar.texi(,3651) @node Basic tar
+../tar_texi/tar.texi(GNUTAR,3652) @section Basic @acronym{GNU} @command{tar}
Operations
+../tar_texi/tar.texi(,3653)
+../tar_texi/tar.texi(,3654) The basic @command{tar} operations,
@option{--create} (@option{-c}),
+../tar_texi/tar.texi(,3655) @option{--list} (@option{-t}) and
@option{--extract} (@option{--get},
+../tar_texi/tar.texi(,3656) @option{-x}), are currently presented and
described in the tutorial
+../tar_texi/tar.texi(,3657) chapter of this manual. This section provides
some complementary notes
+../tar_texi/tar.texi(,3658) for these operations.
+../tar_texi/tar.texi(,3659)
+../tar_texi/tar.texi(,3660) @table @option
+../tar_texi/tar.texi(xopindex,3661) @opindex address@hidden, complementary
notes}
+../tar_texi/tar.texi(,3662) @item --create
+../tar_texi/tar.texi(,3663) @itemx -c
+../tar_texi/tar.texi(,3664)
+../tar_texi/tar.texi(,3665) Creating an empty archive would have some kind of
elegance. One can
+../tar_texi/tar.texi(,3666) initialize an empty archive and later use
@option{--append}
+../tar_texi/tar.texi(,3667) (@option{-r}) for adding all members. Some
applications would not
+../tar_texi/tar.texi(,3668) welcome making an exception in the way of adding
the first archive
+../tar_texi/tar.texi(,3669) member. On the other hand, many people reported
that it is
+../tar_texi/tar.texi(,3670) dangerously too easy for @command{tar} to destroy
a magnetic tape with
+../tar_texi/tar.texi(,3671) an empty address@hidden is well described in
@cite{Unix-haters
+../tar_texi/tar.texi(,3672) Handbook}, by Simson Garfinkel, Daniel Weise &
Steven Strassmann, IDG
+../tar_texi/tar.texi(,3673) Books, ISBN 1-56884-203-1.}. The two most common
errors are:
+../tar_texi/tar.texi(,3674)
+../tar_texi/tar.texi(,3675) @enumerate
+../tar_texi/tar.texi(,3676) @item
+../tar_texi/tar.texi(,3677) Mistakingly using @code{create} instead of
@code{extract}, when the
+../tar_texi/tar.texi(,3678) intent was to extract the full contents of an
archive. This error
+../tar_texi/tar.texi(,3679) is likely: keys @kbd{c} and @kbd{x} are right next
to each other on
+../tar_texi/tar.texi(,3680) the QWERTY keyboard. Instead of being unpacked,
the archive then
+../tar_texi/tar.texi(,3681) gets wholly destroyed. When users speak about
@dfn{exploding} an
+../tar_texi/tar.texi(,3682) archive, they usually mean something else :-).
+../tar_texi/tar.texi(,3683)
+../tar_texi/tar.texi(,3684) @item
+../tar_texi/tar.texi(,3685) Forgetting the argument to @code{file}, when the
intent was to create
+../tar_texi/tar.texi(,3686) an archive with a single file in it. This error
is likely because a
+../tar_texi/tar.texi(,3687) tired user can easily add the @kbd{f} key to the
cluster of option
+../tar_texi/tar.texi(,3688) letters, by the mere force of habit, without
realizing the full
+../tar_texi/tar.texi(,3689) consequence of doing so. The usual consequence is
that the single
+../tar_texi/tar.texi(,3690) file, which was meant to be saved, is rather
destroyed.
+../tar_texi/tar.texi(,3691) @end enumerate
+../tar_texi/tar.texi(,3692)
+../tar_texi/tar.texi(,3693) So, recognizing the likelihood and the
catastrophical nature of these
+../tar_texi/tar.texi(GNUTAR,3694) errors, @acronym{GNU} @command{tar} now
takes some distance from elegance, and
+../tar_texi/tar.texi(,3695) cowardly refuses to create an archive when
@option{--create} option is
+../tar_texi/tar.texi(,3696) given, there are no arguments besides options, and
+../tar_texi/tar.texi(,3697) @option{--files-from} (@option{-T}) option is
@emph{not} used. To get
+../tar_texi/tar.texi(GNUTAR,3698) around the cautiousness of @acronym{GNU}
@command{tar} and nevertheless create an
+../tar_texi/tar.texi(,3699) archive with nothing in it, one may still use, as
the value for the
+../tar_texi/tar.texi(,3700) @option{--files-from} option, a file with no names
in it, as shown in
+../tar_texi/tar.texi(,3701) the following commands:
+../tar_texi/tar.texi(,3702)
+../tar_texi/tar.texi(,3703) @smallexample
+../tar_texi/tar.texi(,3704) @kbd{tar --create --file=empty-archive.tar
--files-from=/dev/null}
+../tar_texi/tar.texi(,3705) @kbd{tar cfT empty-archive.tar /dev/null}
+../tar_texi/tar.texi(,3706) @end smallexample
+../tar_texi/tar.texi(,3707)
+../tar_texi/tar.texi(xopindex,3708) @opindex address@hidden, complementary
notes}
+../tar_texi/tar.texi(,3709) @item --extract
+../tar_texi/tar.texi(,3710) @itemx --get
+../tar_texi/tar.texi(,3711) @itemx -x
+../tar_texi/tar.texi(,3712)
+../tar_texi/tar.texi(GNUTAR,3713) A socket is stored, within a @acronym{GNU}
@command{tar} archive, as a pipe.
+../tar_texi/tar.texi(,3714)
+../tar_texi/tar.texi(,3715) @item @option{--list} (@option{-t})
+../tar_texi/tar.texi(,3716)
+../tar_texi/tar.texi(GNUTAR,3717) @acronym{GNU} @command{tar} now shows dates
as @samp{1996-08-30},
+../tar_texi/tar.texi(,3718) while it used to show them as @samp{Aug 30 1996}.
Preferably,
+../tar_texi/tar.texi(,3719) people should get used to ISO 8601 dates. Local
American dates should
+../tar_texi/tar.texi(,3720) be made available again with full date
localization support, once
+../tar_texi/tar.texi(,3721) ready. In the meantime, programs not being
localizable for dates
+../tar_texi/tar.texi(,3722) should prefer international dates, that's really
the way to go.
+../tar_texi/tar.texi(,3723)
+../tar_texi/tar.texi(,3724) Look up
@url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you
+../tar_texi/tar.texi(,3725) are curious, it contains a detailed explanation of
the ISO 8601 standard.
+../tar_texi/tar.texi(,3726)
+../tar_texi/tar.texi(,3727) @end table
+../tar_texi/tar.texi(,3728)
+../tar_texi/tar.texi(,3729) @node Advanced tar
+../tar_texi/tar.texi(GNUTAR,3730) @section Advanced @acronym{GNU}
@command{tar} Operations
+../tar_texi/tar.texi(,3731)
+../tar_texi/tar.texi(GNUTAR,3732) Now that you have learned the basics of
using @acronym{GNU} @command{tar}, you may want
+../tar_texi/tar.texi(,3733) to learn about further ways in which @command{tar}
can help you.
+../tar_texi/tar.texi(,3734)
+../tar_texi/tar.texi(,3735) This chapter presents five, more advanced
operations which you probably
+../tar_texi/tar.texi(,3736) won't use on a daily basis, but which serve more
specialized functions.
+../tar_texi/tar.texi(,3737) We also explain the different styles of options
and why you might want
+../tar_texi/tar.texi(,3738) to use one or another, or a combination of them in
your @command{tar}
+../tar_texi/tar.texi(,3739) commands. Additionally, this chapter includes
options which allow you to
+../tar_texi/tar.texi(,3740) define the output from @command{tar} more
carefully, and provide help and
+../tar_texi/tar.texi(,3741) error correction in special circumstances.
+../tar_texi/tar.texi(,3742)
+../tar_texi/tar.texi(FIXME,3744) @allow-recursion
+../tar_texi/tar.texi(FIXME,3744) @quote-arg
+../tar_texi/tar.texi(FIXME,3744)
+../tar_texi/tar.texi(,3745)
+../tar_texi/tar.texi(,3746) @menu
+../tar_texi/tar.texi(,3747) * Operations::
+../tar_texi/tar.texi(,3748) * append::
+../tar_texi/tar.texi(,3749) * update::
+../tar_texi/tar.texi(,3750) * concatenate::
+../tar_texi/tar.texi(,3751) * delete::
+../tar_texi/tar.texi(,3752) * compare::
+../tar_texi/tar.texi(,3753) @end menu
+../tar_texi/tar.texi(,3754)
+../tar_texi/tar.texi(,3755) @node Operations
+../tar_texi/tar.texi(,3756) @subsection The Five Advanced @command{tar}
Operations
+../tar_texi/tar.texi(UNREVISED,3757) @quotation
+../tar_texi/tar.texi(UNREVISED,3757) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,3757) @end quotation
+../tar_texi/tar.texi(UNREVISED,3757)
+../tar_texi/tar.texi(,3758)
+../tar_texi/tar.texi(,3759) In the last chapter, you learned about the first
three operations to
+../tar_texi/tar.texi(,3760) @command{tar}. This chapter presents the
remaining five operations to
+../tar_texi/tar.texi(,3761) @command{tar}: @option{--append},
@option{--update}, @option{--concatenate},
+../tar_texi/tar.texi(,3762) @option{--delete}, and @option{--compare}.
+../tar_texi/tar.texi(,3763)
+../tar_texi/tar.texi(,3764) You are not likely to use these operations as
frequently as those
+../tar_texi/tar.texi(,3765) covered in the last chapter; however, since they
perform specialized
+../tar_texi/tar.texi(,3766) functions, they are quite useful when you do need
to use them. We
+../tar_texi/tar.texi(,3767) will give examples using the same directory and
files that you created
+../tar_texi/tar.texi(,3768) in the last chapter. As you may recall, the
directory is called
+../tar_texi/tar.texi(,3769) @file{practice}, the files are @samp{jazz},
@samp{blues}, @samp{folk},
+../tar_texi/tar.texi(,3770) @samp{rock}, and the two archive files you created
are
+../tar_texi/tar.texi(,3771) @samp{collection.tar} and @samp{music.tar}.
+../tar_texi/tar.texi(,3772)
+../tar_texi/tar.texi(,3773) We will also use the archive files
@samp{afiles.tar} and
+../tar_texi/tar.texi(,3774) @samp{bfiles.tar}. The archive @samp{afiles.tar}
contains the members @samp{apple},
+../tar_texi/tar.texi(,3775) @samp{angst}, and @samp{aspic}; @samp{bfiles.tar}
contains the members
+../tar_texi/tar.texi(,3776) @samp{./birds}, @samp{baboon}, and @samp{./box}.
+../tar_texi/tar.texi(,3777)
+../tar_texi/tar.texi(,3778) Unless we state otherwise, all practicing you do
and examples you follow
+../tar_texi/tar.texi(,3779) in this chapter will take place in the
@file{practice} directory that
+../tar_texi/tar.texi(,3780) you created in the previous chapter; see
@ref{prepare for examples}.
+../tar_texi/tar.texi(,3781) (Below in this section, we will remind you of the
state of the examples
+../tar_texi/tar.texi(,3782) where the last chapter left them.)
+../tar_texi/tar.texi(,3783)
+../tar_texi/tar.texi(,3784) The five operations that we will cover in this
chapter are:
+../tar_texi/tar.texi(,3785)
+../tar_texi/tar.texi(,3786) @table @option
+../tar_texi/tar.texi(,3787) @item --append
+../tar_texi/tar.texi(,3788) @itemx -r
+../tar_texi/tar.texi(,3789) Add new entries to an archive that already exists.
+../tar_texi/tar.texi(,3790) @item --update
+../tar_texi/tar.texi(,3791) @itemx -r
+../tar_texi/tar.texi(,3792) Add more recent copies of archive members to the
end of an archive, if
+../tar_texi/tar.texi(,3793) they exist.
+../tar_texi/tar.texi(,3794) @item --concatenate
+../tar_texi/tar.texi(,3795) @itemx --catenate
+../tar_texi/tar.texi(,3796) @itemx -A
+../tar_texi/tar.texi(,3797) Add one or more pre-existing archives to the end
of another archive.
+../tar_texi/tar.texi(,3798) @item --delete
+../tar_texi/tar.texi(,3799) Delete items from an archive (does not work on
tapes).
+../tar_texi/tar.texi(,3800) @item --compare
+../tar_texi/tar.texi(,3801) @itemx --diff
+../tar_texi/tar.texi(,3802) @itemx -d
+../tar_texi/tar.texi(,3803) Compare archive members to their counterparts in
the file system.
+../tar_texi/tar.texi(,3804) @end table
+../tar_texi/tar.texi(,3805)
+../tar_texi/tar.texi(,3806) @node append
+../tar_texi/tar.texi(,3807) @subsection How to Add Files to Existing Archives:
@option{--append}
+../tar_texi/tar.texi(UNREVISED,3808) @quotation
+../tar_texi/tar.texi(UNREVISED,3808) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,3808) @end quotation
+../tar_texi/tar.texi(UNREVISED,3808)
+../tar_texi/tar.texi(,3809)
+../tar_texi/tar.texi(,3810) @opindex append
+../tar_texi/tar.texi(,3811) If you want to add files to an existing archive,
you don't need to
+../tar_texi/tar.texi(,3812) create a new archive; you can use
@option{--append} (@option{-r}).
+../tar_texi/tar.texi(,3813) The archive must already exist in order to use
@option{--append}. (A
+../tar_texi/tar.texi(,3814) related operation is the @option{--update}
operation; you can use this
+../tar_texi/tar.texi(,3815) to add newer versions of archive members to an
existing archive. To learn how to
+../tar_texi/tar.texi(,3816) do this with @option{--update}, @pxref{update}.)
+../tar_texi/tar.texi(,3817)
+../tar_texi/tar.texi(,3818) If you use @option{--append} to add a file that
has the same name as an
+../tar_texi/tar.texi(,3819) archive member to an archive containing that
archive member, then the
+../tar_texi/tar.texi(,3820) old member is not deleted. What does happen,
however, is somewhat
+../tar_texi/tar.texi(,3821) complex. @command{tar} @emph{allows} you to have
infinite number of files
+../tar_texi/tar.texi(,3822) with the same name. Some operations treat these
same-named members no
+../tar_texi/tar.texi(,3823) differently than any other set of archive members:
for example, if you
+../tar_texi/tar.texi(,3824) view an archive with @option{--list}
(@option{-t}), you will see all
+../tar_texi/tar.texi(,3825) of those members listed, with their data
modification times, owners, etc.
+../tar_texi/tar.texi(,3826)
+../tar_texi/tar.texi(,3827) Other operations don't deal with these members as
perfectly as you might
+../tar_texi/tar.texi(,3828) prefer; if you were to use @option{--extract} to
extract the archive,
+../tar_texi/tar.texi(,3829) only the most recently added copy of a member with
the same name as four
+../tar_texi/tar.texi(,3830) other members would end up in the working
directory. This is because
+../tar_texi/tar.texi(,3831) @option{--extract} extracts an archive in the
order the members appeared
+../tar_texi/tar.texi(,3832) in the archive; the most recently archived members
will be extracted
+../tar_texi/tar.texi(,3833) last. Additionally, an extracted member will
@emph{replace} a file of
+../tar_texi/tar.texi(,3834) the same name which existed in the directory
already, and @command{tar}
+../tar_texi/tar.texi(,3835) will not prompt you about address@hidden you give
it
+../tar_texi/tar.texi(,3836) @option{--keep-old-files} option, or the disk copy
is newer than the
+../tar_texi/tar.texi(,3837) the one in the archive and you invoke
@command{tar} with
+../tar_texi/tar.texi(,3838) @option{--keep-newer-files} option}. Thus, only
the most recently archived
+../tar_texi/tar.texi(,3839) member will end up being extracted, as it will
replace the one
+../tar_texi/tar.texi(,3840) extracted before it, and so on.
+../tar_texi/tar.texi(,3841)
+../tar_texi/tar.texi(,3842) There exists a special option that allows you to
get around this
+../tar_texi/tar.texi(,3843) behavior and extract (or list) only a particular
copy of the file.
+../tar_texi/tar.texi(,3844) This is @option{--occurrence} option. If you run
@command{tar} with
+../tar_texi/tar.texi(,3845) this option, it will extract only the first copy
of the file. You
+../tar_texi/tar.texi(,3846) may also give this option an argument specifying
the number of
+../tar_texi/tar.texi(,3847) copy to be extracted. Thus, for example if the
archive
+../tar_texi/tar.texi(,3848) @file{archive.tar} contained three copies of file
@file{myfile}, then
+../tar_texi/tar.texi(,3849) the command
+../tar_texi/tar.texi(,3850)
+../tar_texi/tar.texi(,3851) @smallexample
+../tar_texi/tar.texi(,3852) tar --extract --file archive.tar --occurrence=2
myfile
+../tar_texi/tar.texi(,3853) @end smallexample
+../tar_texi/tar.texi(,3854)
+../tar_texi/tar.texi(,3855) @noindent
+../tar_texi/tar.texi(,3856) would extract only the second copy. @xref{Option
+../tar_texi/tar.texi(,3857) Summary,---occurrence}, for the description of
@option{--occurrence}
+../tar_texi/tar.texi(,3858) option.
+../tar_texi/tar.texi(,3859)
+../tar_texi/tar.texi(FIXME,3864) @allow-recursion
+../tar_texi/tar.texi(FIXME,3864) @quote-arg
+../tar_texi/tar.texi(FIXME,3864)
+../tar_texi/tar.texi(,3865)
+../tar_texi/tar.texi(,3866) @cindex Members, replacing with other members
+../tar_texi/tar.texi(,3867) @cindex Replacing members with other members
+../tar_texi/tar.texi(,3868) If you want to replace an archive member, use
@option{--delete} to
+../tar_texi/tar.texi(,3869) delete the member you want to remove from the
archive, , and then use
+../tar_texi/tar.texi(,3870) @option{--append} to add the member you want to be
in the archive. Note
+../tar_texi/tar.texi(,3871) that you can not change the order of the archive;
the most recently
+../tar_texi/tar.texi(,3872) added member will still appear last. In this
sense, you cannot truly
+../tar_texi/tar.texi(,3873) ``replace'' one member with another. (Replacing
one member with another
+../tar_texi/tar.texi(,3874) will not work on certain types of media, such as
tapes; see @ref{delete}
+../tar_texi/tar.texi(,3875) and @ref{Media}, for more information.)
+../tar_texi/tar.texi(,3876)
+../tar_texi/tar.texi(,3877) @menu
+../tar_texi/tar.texi(,3878) * appending files:: Appending Files to
an Archive
+../tar_texi/tar.texi(,3879) * multiple::
+../tar_texi/tar.texi(,3880) @end menu
+../tar_texi/tar.texi(,3881)
+../tar_texi/tar.texi(,3882) @node appending files
+../tar_texi/tar.texi(,3883) @subsubsection Appending Files to an Archive
+../tar_texi/tar.texi(UNREVISED,3884) @quotation
+../tar_texi/tar.texi(UNREVISED,3884) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,3884) @end quotation
+../tar_texi/tar.texi(UNREVISED,3884)
+../tar_texi/tar.texi(,3885) @cindex Adding files to an Archive
+../tar_texi/tar.texi(,3886) @cindex Appending files to an Archive
+../tar_texi/tar.texi(,3887) @cindex Archives, Appending files to
+../tar_texi/tar.texi(,3888)
+../tar_texi/tar.texi(,3889) The simplest way to add a file to an already
existing archive is the
+../tar_texi/tar.texi(,3890) @option{--append} (@option{-r}) operation, which
writes specified
+../tar_texi/tar.texi(,3891) files into the archive whether or not they are
already among the
+../tar_texi/tar.texi(,3892) archived files.
+../tar_texi/tar.texi(,3893)
+../tar_texi/tar.texi(,3894) When you use @option{--append}, you @emph{must}
specify file name
+../tar_texi/tar.texi(,3895) arguments, as there is no default. If you specify
a file that already
+../tar_texi/tar.texi(,3896) exists in the archive, another copy of the file
will be added to the
+../tar_texi/tar.texi(,3897) end of the archive. As with other operations, the
member names of the
+../tar_texi/tar.texi(,3898) newly added files will be exactly the same as
their names given on the
+../tar_texi/tar.texi(,3899) command line. The @option{--verbose}
(@option{-v}) option will print
+../tar_texi/tar.texi(,3900) out the names of the files as they are written
into the archive.
+../tar_texi/tar.texi(,3901)
+../tar_texi/tar.texi(,3902) @option{--append} cannot be performed on some tape
drives, unfortunately,
+../tar_texi/tar.texi(,3903) due to deficiencies in the formats those tape
drives use. The archive
+../tar_texi/tar.texi(,3904) must be a valid @command{tar} archive, or else the
results of using this
+../tar_texi/tar.texi(,3905) operation will be unpredictable. @xref{Media}.
+../tar_texi/tar.texi(,3906)
+../tar_texi/tar.texi(,3907) To demonstrate using @option{--append} to add a
file to an archive,
+../tar_texi/tar.texi(,3908) create a file called @file{rock} in the
@file{practice} directory.
+../tar_texi/tar.texi(,3909) Make sure you are in the @file{practice}
directory. Then, run the
+../tar_texi/tar.texi(,3910) following @command{tar} command to add @file{rock}
to
+../tar_texi/tar.texi(,3911) @file{collection.tar}:
+../tar_texi/tar.texi(,3912)
+../tar_texi/tar.texi(,3913) @smallexample
+../tar_texi/tar.texi(,3914) $ @kbd{tar --append --file=collection.tar rock}
+../tar_texi/tar.texi(,3915) @end smallexample
+../tar_texi/tar.texi(,3916)
+../tar_texi/tar.texi(,3917) @noindent
+../tar_texi/tar.texi(,3918) If you now use the @option{--list} (@option{-t})
operation, you will see that
+../tar_texi/tar.texi(,3919) @file{rock} has been added to the archive:
+../tar_texi/tar.texi(,3920)
+../tar_texi/tar.texi(,3921) @smallexample
+../tar_texi/tar.texi(,3922) $ @kbd{tar --list --file=collection.tar}
+../tar_texi/tar.texi(,3923) -rw-r--r-- me user 28 1996-10-18 16:31 jazz
+../tar_texi/tar.texi(,3924) -rw-r--r-- me user 21 1996-09-23 16:44 blues
+../tar_texi/tar.texi(,3925) -rw-r--r-- me user 20 1996-09-23 16:44 folk
+../tar_texi/tar.texi(,3926) -rw-r--r-- me user 20 1996-09-23 16:44 rock
+../tar_texi/tar.texi(,3927) @end smallexample
+../tar_texi/tar.texi(,3928)
+../tar_texi/tar.texi(,3929) @node multiple
+../tar_texi/tar.texi(,3930) @subsubsection Multiple Members with the Same Name
+../tar_texi/tar.texi(,3931)
+../tar_texi/tar.texi(,3932) You can use @option{--append} (@option{-r}) to add
copies of files
+../tar_texi/tar.texi(,3933) which have been updated since the archive was
created. (However, we
+../tar_texi/tar.texi(,3934) do not recommend doing this since there is another
@command{tar}
+../tar_texi/tar.texi(,3935) option called @option{--update}; @xref{update},
for more information.
+../tar_texi/tar.texi(,3936) We describe this use of @option{--append} here for
the sake of
+../tar_texi/tar.texi(,3937) completeness.) When you extract the archive, the
older version will
+../tar_texi/tar.texi(,3938) be effectively lost. This works because files are
extracted from an
+../tar_texi/tar.texi(,3939) archive in the order in which they were archived.
Thus, when the
+../tar_texi/tar.texi(,3940) archive is extracted, a file archived later in
time will replace a
+../tar_texi/tar.texi(,3941) file of the same name which was archived earlier,
even though the
+../tar_texi/tar.texi(,3942) older version of the file will remain in the
archive unless you delete
+../tar_texi/tar.texi(,3943) all versions of the file.
+../tar_texi/tar.texi(,3944)
+../tar_texi/tar.texi(,3945) Supposing you change the file @file{blues} and
then append the changed
+../tar_texi/tar.texi(,3946) version to @file{collection.tar}. As you saw
above, the original
+../tar_texi/tar.texi(,3947) @file{blues} is in the archive
@file{collection.tar}. If you change the
+../tar_texi/tar.texi(,3948) file and append the new version of the file to the
archive, there will
+../tar_texi/tar.texi(,3949) be two copies in the archive. When you extract
the archive, the older
+../tar_texi/tar.texi(,3950) version of the file will be extracted first, and
then replaced by the
+../tar_texi/tar.texi(,3951) newer version when it is extracted.
+../tar_texi/tar.texi(,3952)
+../tar_texi/tar.texi(,3953) You can append the new, changed copy of the file
@file{blues} to the
+../tar_texi/tar.texi(,3954) archive in this way:
+../tar_texi/tar.texi(,3955)
+../tar_texi/tar.texi(,3956) @smallexample
+../tar_texi/tar.texi(,3957) $ @kbd{tar --append --verbose
--file=collection.tar blues}
+../tar_texi/tar.texi(,3958) blues
+../tar_texi/tar.texi(,3959) @end smallexample
+../tar_texi/tar.texi(,3960)
+../tar_texi/tar.texi(,3961) @noindent
+../tar_texi/tar.texi(,3962) Because you specified the @option{--verbose}
option, @command{tar} has
+../tar_texi/tar.texi(,3963) printed the name of the file being appended as it
was acted on. Now
+../tar_texi/tar.texi(,3964) list the contents of the archive:
+../tar_texi/tar.texi(,3965)
+../tar_texi/tar.texi(,3966) @smallexample
+../tar_texi/tar.texi(,3967) $ @kbd{tar --list --verbose --file=collection.tar}
+../tar_texi/tar.texi(,3968) -rw-r--r-- me user 28 1996-10-18 16:31 jazz
+../tar_texi/tar.texi(,3969) -rw-r--r-- me user 21 1996-09-23 16:44 blues
+../tar_texi/tar.texi(,3970) -rw-r--r-- me user 20 1996-09-23 16:44 folk
+../tar_texi/tar.texi(,3971) -rw-r--r-- me user 20 1996-09-23 16:44 rock
+../tar_texi/tar.texi(,3972) -rw-r--r-- me user 58 1996-10-24 18:30 blues
+../tar_texi/tar.texi(,3973) @end smallexample
+../tar_texi/tar.texi(,3974)
+../tar_texi/tar.texi(,3975) @noindent
+../tar_texi/tar.texi(,3976) The newest version of @file{blues} is now at the
end of the archive
+../tar_texi/tar.texi(,3977) (note the different creation dates and file
sizes). If you extract
+../tar_texi/tar.texi(,3978) the archive, the older version of the file
@file{blues} will be
+../tar_texi/tar.texi(,3979) replaced by the newer version. You can confirm
this by extracting
+../tar_texi/tar.texi(,3980) the archive and running @samp{ls} on the directory.
+../tar_texi/tar.texi(,3981)
+../tar_texi/tar.texi(,3982) If you wish to extract the first occurrence of the
file @file{blues}
+../tar_texi/tar.texi(,3983) from the archive, use @option{--occurrence}
option, as shown in
+../tar_texi/tar.texi(,3984) the following example:
+../tar_texi/tar.texi(,3985)
+../tar_texi/tar.texi(,3986) @smallexample
+../tar_texi/tar.texi(,3987) $ @kbd{tar --extract -vv --occurrence
--file=collection.tar blues}
+../tar_texi/tar.texi(,3988) -rw-r--r-- me user 21 1996-09-23 16:44 blues
+../tar_texi/tar.texi(,3989) @end smallexample
+../tar_texi/tar.texi(,3990)
+../tar_texi/tar.texi(,3991) @xref{Writing}, for more information on
@option{--extract} and
+../tar_texi/tar.texi(,3992) @xref{Option Summary, --occurrence}, for the
description of
+../tar_texi/tar.texi(,3993) @option{--occurrence} option.
+../tar_texi/tar.texi(,3994)
+../tar_texi/tar.texi(,3995) @node update
+../tar_texi/tar.texi(,3996) @subsection Updating an Archive
+../tar_texi/tar.texi(UNREVISED,3997) @quotation
+../tar_texi/tar.texi(UNREVISED,3997) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,3997) @end quotation
+../tar_texi/tar.texi(UNREVISED,3997)
+../tar_texi/tar.texi(,3998) @cindex Updating an archive
+../tar_texi/tar.texi(,3999)
+../tar_texi/tar.texi(,4000) @opindex update
+../tar_texi/tar.texi(,4001) In the previous section, you learned how to use
@option{--append} to
+../tar_texi/tar.texi(,4002) add a file to an existing archive. A related
operation is
+../tar_texi/tar.texi(,4003) @option{--update} (@option{-u}). The
@option{--update} operation
+../tar_texi/tar.texi(,4004) updates a @command{tar} archive by comparing the
date of the specified
+../tar_texi/tar.texi(,4005) archive members against the date of the file with
the same name. If
+../tar_texi/tar.texi(,4006) the file has been modified more recently than the
archive member, then
+../tar_texi/tar.texi(,4007) the newer version of the file is added to the
archive (as with
+../tar_texi/tar.texi(,4008) @option{--append}).
+../tar_texi/tar.texi(,4009)
+../tar_texi/tar.texi(,4010) Unfortunately, you cannot use @option{--update}
with magnetic tape drives.
+../tar_texi/tar.texi(,4011) The operation will fail.
+../tar_texi/tar.texi(,4012)
+../tar_texi/tar.texi(FIXME,4014) @allow-recursion
+../tar_texi/tar.texi(FIXME,4014) @quote-arg
+../tar_texi/tar.texi(FIXME,4014)
+../tar_texi/tar.texi(,4015)
+../tar_texi/tar.texi(,4016) Both @option{--update} and @option{--append} work
by adding to the end
+../tar_texi/tar.texi(,4017) of the archive. When you extract a file from the
archive, only the
+../tar_texi/tar.texi(,4018) version stored last will wind up in the file
system, unless you use
+../tar_texi/tar.texi(,4019) the @option{--backup} option. @xref{multiple},
for a detailed discussion.
+../tar_texi/tar.texi(,4020)
+../tar_texi/tar.texi(,4021) @menu
+../tar_texi/tar.texi(,4022) * how to update::
+../tar_texi/tar.texi(,4023) @end menu
+../tar_texi/tar.texi(,4024)
+../tar_texi/tar.texi(,4025) @node how to update
+../tar_texi/tar.texi(,4026) @subsubsection How to Update an Archive Using
@option{--update}
+../tar_texi/tar.texi(,4027)
+../tar_texi/tar.texi(,4028) You must use file name arguments with the
@option{--update}
+../tar_texi/tar.texi(,4029) (@option{-u}) operation. If you don't specify any
files,
+../tar_texi/tar.texi(,4030) @command{tar} won't act on any files and won't
tell you that it didn't
+../tar_texi/tar.texi(,4031) do anything (which may end up confusing you).
+../tar_texi/tar.texi(,4032)
+../tar_texi/tar.texi(,4033) @c note: the above parenthetical added because in
fact, this
+../tar_texi/tar.texi(,4034) @c behavior just confused the author. :-)
+../tar_texi/tar.texi(,4035)
+../tar_texi/tar.texi(,4036) To see the @option{--update} option at work,
create a new file,
+../tar_texi/tar.texi(,4037) @file{classical}, in your practice directory, and
some extra text to the
+../tar_texi/tar.texi(,4038) file @file{blues}, using any text editor. Then
invoke @command{tar} with
+../tar_texi/tar.texi(,4039) the @samp{update} operation and the
@option{--verbose} (@option{-v})
+../tar_texi/tar.texi(,4040) option specified, using the names of all the files
in the practice
+../tar_texi/tar.texi(,4041) directory as file name arguments:
+../tar_texi/tar.texi(,4042)
+../tar_texi/tar.texi(,4043) @smallexample
+../tar_texi/tar.texi(,4044) $ @kbd{tar --update -v -f collection.tar blues
folk rock classical}
+../tar_texi/tar.texi(,4045) blues
+../tar_texi/tar.texi(,4046) classical
+../tar_texi/tar.texi(,4047) $
+../tar_texi/tar.texi(,4048) @end smallexample
+../tar_texi/tar.texi(,4049)
+../tar_texi/tar.texi(,4050) @noindent
+../tar_texi/tar.texi(,4051) Because we have specified verbose mode,
@command{tar} prints out the names
+../tar_texi/tar.texi(,4052) of the files it is working on, which in this case
are the names of the
+../tar_texi/tar.texi(,4053) files that needed to be updated. If you run
@samp{tar --list} and look
+../tar_texi/tar.texi(,4054) at the archive, you will see @file{blues} and
@file{classical} at its
+../tar_texi/tar.texi(,4055) end. There will be a total of two versions of the
member @samp{blues};
+../tar_texi/tar.texi(,4056) the one at the end will be newer and larger, since
you added text before
+../tar_texi/tar.texi(,4057) updating it.
+../tar_texi/tar.texi(,4058)
+../tar_texi/tar.texi(,4059) (The reason @command{tar} does not overwrite the
older file when updating
+../tar_texi/tar.texi(,4060) it is because writing to the middle of a section
of tape is a difficult
+../tar_texi/tar.texi(,4061) process. Tapes are not designed to go backward.
@xref{Media}, for more
+../tar_texi/tar.texi(,4062) information about tapes.
+../tar_texi/tar.texi(,4063)
+../tar_texi/tar.texi(,4064) @option{--update} (@option{-u}) is not suitable
for performing backups for two
+../tar_texi/tar.texi(,4065) reasons: it does not change directory content
entries, and it
+../tar_texi/tar.texi(GNUTAR,4066) lengthens the archive every time it is used.
The @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,4067) options intended specifically for backups are more
+../tar_texi/tar.texi(,4068) efficient. If you need to run backups, please
consult @ref{Backups}.
+../tar_texi/tar.texi(,4069)
+../tar_texi/tar.texi(,4070) @node concatenate
+../tar_texi/tar.texi(,4071) @subsection Combining Archives with
@option{--concatenate}
+../tar_texi/tar.texi(,4072)
+../tar_texi/tar.texi(,4073) @cindex Adding archives to an archive
+../tar_texi/tar.texi(,4074) @cindex Concatenating Archives
+../tar_texi/tar.texi(,4075) @opindex concatenate
+../tar_texi/tar.texi(,4076) @opindex catenate
+../tar_texi/tar.texi(,4077) @c @cindex @option{-A} described
+../tar_texi/tar.texi(,4078) Sometimes it may be convenient to add a second
archive onto the end of
+../tar_texi/tar.texi(,4079) an archive rather than adding individual files to
the archive. To add
+../tar_texi/tar.texi(,4080) one or more archives to the end of another
archive, you should use the
+../tar_texi/tar.texi(,4081) @option{--concatenate} (@option{--catenate},
@option{-A}) operation.
+../tar_texi/tar.texi(,4082)
+../tar_texi/tar.texi(,4083) To use @option{--concatenate}, give the first
archive with
+../tar_texi/tar.texi(,4084) @option{--file} option and name the rest of
archives to be
+../tar_texi/tar.texi(,4085) concatenated on the command line. The members,
and their member
+../tar_texi/tar.texi(,4086) names, will be copied verbatim from those archives
to the first one.
+../tar_texi/tar.texi(,4087) @footnote{This can cause multiple members to have
the same name, for
+../tar_texi/tar.texi(,4088) information on how this affects reading the
archive, @ref{multiple}.}
+../tar_texi/tar.texi(,4089) The new, concatenated archive will be called by
the same name as the
+../tar_texi/tar.texi(,4090) one given with the @option{--file} option. As
usual, if you omit
+../tar_texi/tar.texi(,4091) @option{--file}, @command{tar} will use the value
of the environment
+../tar_texi/tar.texi(,4092) variable @env{TAPE}, or, if this has not been set,
the default archive name.
+../tar_texi/tar.texi(,4093)
+../tar_texi/tar.texi(FIXME,4094) @allow-recursion
+../tar_texi/tar.texi(FIXME,4094) @quote-arg
+../tar_texi/tar.texi(FIXME,4094)
+../tar_texi/tar.texi(,4095)
+../tar_texi/tar.texi(,4096) To demonstrate how @option{--concatenate} works,
create two small archives
+../tar_texi/tar.texi(,4097) called @file{bluesrock.tar} and
@file{folkjazz.tar}, using the relevant
+../tar_texi/tar.texi(,4098) files from @file{practice}:
+../tar_texi/tar.texi(,4099)
+../tar_texi/tar.texi(,4100) @smallexample
+../tar_texi/tar.texi(,4101) $ @kbd{tar -cvf bluesrock.tar blues rock}
+../tar_texi/tar.texi(,4102) blues
+../tar_texi/tar.texi(,4103) rock
+../tar_texi/tar.texi(,4104) $ @kbd{tar -cvf folkjazz.tar folk jazz}
+../tar_texi/tar.texi(,4105) folk
+../tar_texi/tar.texi(,4106) jazz
+../tar_texi/tar.texi(,4107) @end smallexample
+../tar_texi/tar.texi(,4108)
+../tar_texi/tar.texi(,4109) @noindent
+../tar_texi/tar.texi(,4110) If you like, You can run @samp{tar --list} to make
sure the archives
+../tar_texi/tar.texi(,4111) contain what they are supposed to:
+../tar_texi/tar.texi(,4112)
+../tar_texi/tar.texi(,4113) @smallexample
+../tar_texi/tar.texi(,4114) $ @kbd{tar -tvf bluesrock.tar}
+../tar_texi/tar.texi(,4115) -rw-r--r-- melissa user 105 1997-01-21 19:42
blues
+../tar_texi/tar.texi(,4116) -rw-r--r-- melissa user 33 1997-01-20 15:34
rock
+../tar_texi/tar.texi(,4117) $ @kbd{tar -tvf jazzfolk.tar}
+../tar_texi/tar.texi(,4118) -rw-r--r-- melissa user 20 1996-09-23 16:44
folk
+../tar_texi/tar.texi(,4119) -rw-r--r-- melissa user 65 1997-01-30 14:15
jazz
+../tar_texi/tar.texi(,4120) @end smallexample
+../tar_texi/tar.texi(,4121)
+../tar_texi/tar.texi(,4122) We can concatenate these two archives with
@command{tar}:
+../tar_texi/tar.texi(,4123)
+../tar_texi/tar.texi(,4124) @smallexample
+../tar_texi/tar.texi(,4125) $ @kbd{cd ..}
+../tar_texi/tar.texi(,4126) $ @kbd{tar --concatenate --file=bluesrock.tar
jazzfolk.tar}
+../tar_texi/tar.texi(,4127) @end smallexample
+../tar_texi/tar.texi(,4128)
+../tar_texi/tar.texi(,4129) If you now list the contents of the
@file{bluesrock.tar}, you will see
+../tar_texi/tar.texi(,4130) that now it also contains the archive members of
@file{jazzfolk.tar}:
+../tar_texi/tar.texi(,4131)
+../tar_texi/tar.texi(,4132) @smallexample
+../tar_texi/tar.texi(,4133) $ @kbd{tar --list --file=bluesrock.tar}
+../tar_texi/tar.texi(,4134) blues
+../tar_texi/tar.texi(,4135) rock
+../tar_texi/tar.texi(,4136) folk
+../tar_texi/tar.texi(,4137) jazz
+../tar_texi/tar.texi(,4138) @end smallexample
+../tar_texi/tar.texi(,4139)
+../tar_texi/tar.texi(,4140) When you use @option{--concatenate}, the source
and target archives must
+../tar_texi/tar.texi(,4141) already exist and must have been created using
compatible format
+../tar_texi/tar.texi(,4142) parameters. Notice, that @command{tar} does not
check whether the
+../tar_texi/tar.texi(,4143) archives it concatenates have compatible formats,
it does not
+../tar_texi/tar.texi(,4144) even check if the files are really tar archives.
+../tar_texi/tar.texi(,4145)
+../tar_texi/tar.texi(,4146) Like @option{--append} (@option{-r}), this
operation cannot be performed on some
+../tar_texi/tar.texi(,4147) tape drives, due to deficiencies in the formats
those tape drives use.
+../tar_texi/tar.texi(,4148)
+../tar_texi/tar.texi(,4149) @cindex @code{concatenate} vs @command{cat}
+../tar_texi/tar.texi(,4150) @cindex @command{cat} vs @code{concatenate}
+../tar_texi/tar.texi(,4151) It may seem more intuitive to you to want or try
to use @command{cat} to
+../tar_texi/tar.texi(,4152) concatenate two archives instead of using the
@option{--concatenate}
+../tar_texi/tar.texi(,4153) operation; after all, @command{cat} is the utility
for combining files.
+../tar_texi/tar.texi(,4154)
+../tar_texi/tar.texi(,4155) However, @command{tar} archives incorporate an
end-of-file marker which
+../tar_texi/tar.texi(,4156) must be removed if the concatenated archives are
to be read properly as
+../tar_texi/tar.texi(,4157) one archive. @option{--concatenate} removes the
end-of-archive marker
+../tar_texi/tar.texi(,4158) from the target archive before each new archive is
appended. If you use
+../tar_texi/tar.texi(,4159) @command{cat} to combine the archives, the result
will not be a valid
+../tar_texi/tar.texi(,4160) @command{tar} format archive. If you need to
retrieve files from an
+../tar_texi/tar.texi(,4161) archive that was added to using the @command{cat}
utility, use the
+../tar_texi/tar.texi(,4162) @option{--ignore-zeros} (@option{-i}) option.
@xref{Ignore Zeros}, for further
+../tar_texi/tar.texi(,4163) information on dealing with archives improperly
combined using the
+../tar_texi/tar.texi(,4164) @command{cat} shell utility.
+../tar_texi/tar.texi(,4165)
+../tar_texi/tar.texi(,4166) @node delete
+../tar_texi/tar.texi(,4167) @subsection Removing Archive Members Using
@option{--delete}
+../tar_texi/tar.texi(UNREVISED,4168) @quotation
+../tar_texi/tar.texi(UNREVISED,4168) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4168) @end quotation
+../tar_texi/tar.texi(UNREVISED,4168)
+../tar_texi/tar.texi(,4169) @cindex Deleting files from an archive
+../tar_texi/tar.texi(,4170) @cindex Removing files from an archive
+../tar_texi/tar.texi(,4171)
+../tar_texi/tar.texi(,4172) @opindex delete
+../tar_texi/tar.texi(,4173) You can remove members from an archive by using
the @option{--delete}
+../tar_texi/tar.texi(,4174) option. Specify the name of the archive with
@option{--file}
+../tar_texi/tar.texi(,4175) (@option{-f}) and then specify the names of the
members to be deleted;
+../tar_texi/tar.texi(,4176) if you list no member names, nothing will be
deleted. The
+../tar_texi/tar.texi(,4177) @option{--verbose} option will cause @command{tar}
to print the names
+../tar_texi/tar.texi(,4178) of the members as they are deleted. As with
@option{--extract}, you
+../tar_texi/tar.texi(,4179) must give the exact member names when using
@samp{tar --delete}.
+../tar_texi/tar.texi(,4180) @option{--delete} will remove all versions of the
named file from the
+../tar_texi/tar.texi(,4181) archive. The @option{--delete} operation can run
very slowly.
+../tar_texi/tar.texi(,4182)
+../tar_texi/tar.texi(,4183) Unlike other operations, @option{--delete} has no
short form.
+../tar_texi/tar.texi(,4184)
+../tar_texi/tar.texi(,4185) @cindex Tapes, using @option{--delete} and
+../tar_texi/tar.texi(,4186) @cindex Deleting from tape archives
+../tar_texi/tar.texi(,4187) This operation will rewrite the archive. You can
only use
+../tar_texi/tar.texi(,4188) @option{--delete} on an archive if the archive
device allows you to
+../tar_texi/tar.texi(,4189) write to any point on the media, such as a disk;
because of this, it
+../tar_texi/tar.texi(,4190) does not work on magnetic tapes. Do not try to
delete an archive member
+../tar_texi/tar.texi(,4191) from a magnetic tape; the action will not succeed,
and you will be
+../tar_texi/tar.texi(,4192) likely to scramble the archive and damage your
tape. There is no safe
+../tar_texi/tar.texi(,4193) way (except by completely re-writing the archive)
to delete files from
+../tar_texi/tar.texi(,4194) most kinds of magnetic tape. @xref{Media}.
+../tar_texi/tar.texi(,4195)
+../tar_texi/tar.texi(,4196) To delete all versions of the file @file{blues}
from the archive
+../tar_texi/tar.texi(,4197) @file{collection.tar} in the @file{practice}
directory, make sure you
+../tar_texi/tar.texi(,4198) are in that directory, and then,
+../tar_texi/tar.texi(,4199)
+../tar_texi/tar.texi(,4200) @smallexample
+../tar_texi/tar.texi(,4201) $ @kbd{tar --list --file=collection.tar}
+../tar_texi/tar.texi(,4202) blues
+../tar_texi/tar.texi(,4203) folk
+../tar_texi/tar.texi(,4204) jazz
+../tar_texi/tar.texi(,4205) rock
+../tar_texi/tar.texi(,4206) $ @kbd{tar --delete --file=collection.tar blues}
+../tar_texi/tar.texi(,4207) $ @kbd{tar --list --file=collection.tar}
+../tar_texi/tar.texi(,4208) folk
+../tar_texi/tar.texi(,4209) jazz
+../tar_texi/tar.texi(,4210) rock
+../tar_texi/tar.texi(,4211) $
+../tar_texi/tar.texi(,4212) @end smallexample
+../tar_texi/tar.texi(,4213)
+../tar_texi/tar.texi(FIXME,4215) @allow-recursion
+../tar_texi/tar.texi(FIXME,4215) @quote-arg
+../tar_texi/tar.texi(FIXME,4215)
+../tar_texi/tar.texi(,4216)
+../tar_texi/tar.texi(,4217) The @option{--delete} option has been reported to
work properly when
+../tar_texi/tar.texi(,4218) @command{tar} acts as a filter from @code{stdin}
to @code{stdout}.
+../tar_texi/tar.texi(,4219)
+../tar_texi/tar.texi(,4220) @node compare
+../tar_texi/tar.texi(,4221) @subsection Comparing Archive Members with the
File System
+../tar_texi/tar.texi(,4222) @cindex Verifying the currency of an archive
+../tar_texi/tar.texi(UNREVISED,4223) @quotation
+../tar_texi/tar.texi(UNREVISED,4223) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4223) @end quotation
+../tar_texi/tar.texi(UNREVISED,4223)
+../tar_texi/tar.texi(,4224)
+../tar_texi/tar.texi(,4225) @opindex compare
+../tar_texi/tar.texi(,4226) The @option{--compare} (@option{-d}), or
@option{--diff} operation compares
+../tar_texi/tar.texi(,4227) specified archive members against files with the
same names, and then
+../tar_texi/tar.texi(,4228) reports differences in file size, mode, owner,
modification date and
+../tar_texi/tar.texi(,4229) contents. You should @emph{only} specify archive
member names, not file
+../tar_texi/tar.texi(,4230) names. If you do not name any members, then
@command{tar} will compare the
+../tar_texi/tar.texi(,4231) entire archive. If a file is represented in the
archive but does not
+../tar_texi/tar.texi(,4232) exist in the file system, @command{tar} reports a
difference.
+../tar_texi/tar.texi(,4233)
+../tar_texi/tar.texi(,4234) You have to specify the record size of the archive
when modifying an
+../tar_texi/tar.texi(,4235) archive with a non-default record size.
+../tar_texi/tar.texi(,4236)
+../tar_texi/tar.texi(,4237) @command{tar} ignores files in the file system
that do not have
+../tar_texi/tar.texi(,4238) corresponding members in the archive.
+../tar_texi/tar.texi(,4239)
+../tar_texi/tar.texi(,4240) The following example compares the archive members
@file{rock},
+../tar_texi/tar.texi(,4241) @file{blues} and @file{funk} in the archive
@file{bluesrock.tar} with
+../tar_texi/tar.texi(,4242) files of the same name in the file system. (Note
that there is no file,
+../tar_texi/tar.texi(,4243) @file{funk}; @command{tar} will report an error
message.)
+../tar_texi/tar.texi(,4244)
+../tar_texi/tar.texi(,4245) @smallexample
+../tar_texi/tar.texi(,4246) $ @kbd{tar --compare --file=bluesrock.tar rock
blues funk}
+../tar_texi/tar.texi(,4247) rock
+../tar_texi/tar.texi(,4248) blues
+../tar_texi/tar.texi(,4249) tar: funk not found in archive
+../tar_texi/tar.texi(,4250) @end smallexample
+../tar_texi/tar.texi(,4251)
+../tar_texi/tar.texi(,4252) The spirit behind the @option{--compare}
(@option{--diff},
+../tar_texi/tar.texi(,4253) @option{-d}) option is to check whether the
archive represents the
+../tar_texi/tar.texi(,4254) current state of files on disk, more than
validating the integrity of
+../tar_texi/tar.texi(,4255) the archive media. For this later goal,
@xref{verify}.
+../tar_texi/tar.texi(,4256)
+../tar_texi/tar.texi(,4257) @node create options
+../tar_texi/tar.texi(,4258) @section Options Used by @option{--create}
+../tar_texi/tar.texi(,4259)
+../tar_texi/tar.texi(xopindex,4260) @opindex address@hidden, additional
options}
+../tar_texi/tar.texi(,4261) The previous chapter described the basics of how
to use
+../tar_texi/tar.texi(,4262) @option{--create} (@option{-c}) to create an
archive from a set of files.
+../tar_texi/tar.texi(,4263) @xref{create}. This section described advanced
options to be used with
+../tar_texi/tar.texi(,4264) @option{--create}.
+../tar_texi/tar.texi(,4265)
+../tar_texi/tar.texi(,4266) @menu
+../tar_texi/tar.texi(,4267) * override:: Overriding File
Metadata.
+../tar_texi/tar.texi(,4268) * Ignore Failed Read::
+../tar_texi/tar.texi(,4269) @end menu
+../tar_texi/tar.texi(,4270)
+../tar_texi/tar.texi(,4271) @node override
+../tar_texi/tar.texi(,4272) @subsection Overriding File Metadata
+../tar_texi/tar.texi(,4273)
+../tar_texi/tar.texi(,4274) As described above, a @command{tar} archive keeps,
for each member it contains,
+../tar_texi/tar.texi(,4275) its @dfn{metadata}, such as modification time,
mode and ownership of
+../tar_texi/tar.texi(GNUTAR,4276) the file. @acronym{GNU} @command{tar}
allows to replace these data with other values
+../tar_texi/tar.texi(,4277) when adding files to the archive. The options
described in this
+../tar_texi/tar.texi(,4278) section affect creation of archives of any type.
For POSIX archives,
+../tar_texi/tar.texi(,4279) see also @ref{PAX keywords}, for additional ways
of controlling
+../tar_texi/tar.texi(,4280) metadata, stored in the archive.
+../tar_texi/tar.texi(,4281)
+../tar_texi/tar.texi(,4282) @table @option
+../tar_texi/tar.texi(,4283) @opindex mode
+../tar_texi/tar.texi(,4284) @item address@hidden
+../tar_texi/tar.texi(,4285)
+../tar_texi/tar.texi(,4286) When adding files to an archive, @command{tar}
will use
+../tar_texi/tar.texi(,4287) @var{permissions} for the archive members, rather
than the permissions
+../tar_texi/tar.texi(,4288) from the files. @var{permissions} can be
specified either as an octal
+../tar_texi/tar.texi(,4289) number or as symbolic permissions, like with
+../tar_texi/tar.texi(,4290) @command{chmod} (@xref{File permissions,
Permissions, File
+../tar_texi/tar.texi(,4291) permissions, fileutils, @acronym{GNU} file
utilities}. This reference
+../tar_texi/tar.texi(,4292) also has useful information for those not being
overly familiar with
+../tar_texi/tar.texi(,4293) the UNIX permission system). Using latter syntax
allows for
+../tar_texi/tar.texi(,4294) more flexibility. For example, the value
@samp{a+rw} adds read and write
+../tar_texi/tar.texi(,4295) permissions for everybody, while retaining
executable bits on directories
+../tar_texi/tar.texi(,4296) or on any other file already marked as executable:
+../tar_texi/tar.texi(,4297)
+../tar_texi/tar.texi(,4298) @smallexample
+../tar_texi/tar.texi(,4299) $ @kbd{tar -c -f archive.tar --mode='a+rw' .}
+../tar_texi/tar.texi(,4300) @end smallexample
+../tar_texi/tar.texi(,4301)
+../tar_texi/tar.texi(,4302) @item address@hidden
+../tar_texi/tar.texi(,4303) @opindex mtime
+../tar_texi/tar.texi(,4304)
+../tar_texi/tar.texi(,4305) When adding files to an archive, @command{tar}
will use @var{date} as
+../tar_texi/tar.texi(,4306) the modification time of members when creating
archives, instead of
+../tar_texi/tar.texi(,4307) their actual modification times. The argument
@var{date} can be
+../tar_texi/tar.texi(,4308) either a textual date representation in almost
arbitrary format
+../tar_texi/tar.texi(,4309) (@pxref{Date input formats}) or a name of the
existing file, starting
+../tar_texi/tar.texi(,4310) with @samp{/} or @samp{.}. In the latter case,
the modification time
+../tar_texi/tar.texi(,4311) of that file will be used.
+../tar_texi/tar.texi(,4312)
+../tar_texi/tar.texi(,4313) The following example will set the modification
date to 00:00:00 UTC,
+../tar_texi/tar.texi(,4314) January 1, 1970:
+../tar_texi/tar.texi(,4315)
+../tar_texi/tar.texi(,4316) @smallexample
+../tar_texi/tar.texi(,4317) $ @kbd{tar -c -f archive.tar --mtime='1970-01-01'
.}
+../tar_texi/tar.texi(,4318) @end smallexample
+../tar_texi/tar.texi(,4319)
+../tar_texi/tar.texi(,4320) @noindent
+../tar_texi/tar.texi(GNUTAR,4321) When used with @option{--verbose}
(@pxref{verbose tutorial}) @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,4322) will try to convert the specified date back to its
textual
+../tar_texi/tar.texi(,4323) representation and compare it with the one given
with
+../tar_texi/tar.texi(,4324) @option{--mtime} options. If the two dates
differ, @command{tar} will
+../tar_texi/tar.texi(,4325) print a warning saying what date it will use.
This is to help user
+../tar_texi/tar.texi(,4326) ensure he is using the right date.
+../tar_texi/tar.texi(,4327)
+../tar_texi/tar.texi(,4328) For example:
+../tar_texi/tar.texi(,4329)
+../tar_texi/tar.texi(,4330) @smallexample
+../tar_texi/tar.texi(,4331) $ @kbd{tar -c -f archive.tar -v --mtime=yesterday
.}
+../tar_texi/tar.texi(,4332) tar: Option --mtime: Treating date `yesterday' as
2006-06-20
+../tar_texi/tar.texi(,4333) 13:06:29.152478
+../tar_texi/tar.texi(,4334) @dots{}
+../tar_texi/tar.texi(,4335) @end smallexample
+../tar_texi/tar.texi(,4336)
+../tar_texi/tar.texi(,4337) @item address@hidden
+../tar_texi/tar.texi(,4338) @opindex owner
+../tar_texi/tar.texi(,4339)
+../tar_texi/tar.texi(,4340) Specifies that @command{tar} should use @var{user}
as the owner of members
+../tar_texi/tar.texi(,4341) when creating archives, instead of the user
associated with the source
+../tar_texi/tar.texi(,4342) file. The argument @var{user} can be either an
existing user symbolic
+../tar_texi/tar.texi(,4343) name, or a decimal numeric user ID.
+../tar_texi/tar.texi(,4344)
+../tar_texi/tar.texi(,4345) There is no value indicating a missing number, and
@samp{0} usually means
+../tar_texi/tar.texi(,4346) @code{root}. Some people like to force @samp{0}
as the value to offer in
+../tar_texi/tar.texi(,4347) their distributions for the owner of files,
because the @code{root} user is
+../tar_texi/tar.texi(,4348) anonymous anyway, so that might as well be the
owner of anonymous
+../tar_texi/tar.texi(,4349) archives. For example:
+../tar_texi/tar.texi(,4350)
+../tar_texi/tar.texi(,4351) @smallexample
+../tar_texi/tar.texi(,4352) @group
+../tar_texi/tar.texi(,4353) $ @kbd{tar -c -f archive.tar --owner=0 .}
+../tar_texi/tar.texi(,4354) # @r{Or:}
+../tar_texi/tar.texi(,4355) $ @kbd{tar -c -f archive.tar --owner=root .}
+../tar_texi/tar.texi(,4356) @end group
+../tar_texi/tar.texi(,4357) @end smallexample
+../tar_texi/tar.texi(,4358)
+../tar_texi/tar.texi(,4359) @item address@hidden
+../tar_texi/tar.texi(,4360) @opindex group
+../tar_texi/tar.texi(,4361)
+../tar_texi/tar.texi(,4362) Files added to the @command{tar} archive will have
a group id of @var{group},
+../tar_texi/tar.texi(,4363) rather than the group from the source file. The
argument @var{group}
+../tar_texi/tar.texi(,4364) can be either an existing group symbolic name, or
a decimal numeric group ID.
+../tar_texi/tar.texi(,4365) @end table
+../tar_texi/tar.texi(,4366)
+../tar_texi/tar.texi(,4367) @node Ignore Failed Read
+../tar_texi/tar.texi(,4368) @subsection Ignore Fail Read
+../tar_texi/tar.texi(,4369)
+../tar_texi/tar.texi(,4370) @table @option
+../tar_texi/tar.texi(,4371) @item --ignore-failed-read
+../tar_texi/tar.texi(,4372) @opindex ignore-failed-read
+../tar_texi/tar.texi(,4373) Do not exit with nonzero on unreadable files or
directories.
+../tar_texi/tar.texi(,4374) @end table
+../tar_texi/tar.texi(,4375)
+../tar_texi/tar.texi(,4376) @node extract options
+../tar_texi/tar.texi(,4377) @section Options Used by @option{--extract}
+../tar_texi/tar.texi(UNREVISED,4378) @quotation
+../tar_texi/tar.texi(UNREVISED,4378) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4378) @end quotation
+../tar_texi/tar.texi(UNREVISED,4378)
+../tar_texi/tar.texi(,4379)
+../tar_texi/tar.texi(xopindex,4380) @opindex address@hidden, additional
options}
+../tar_texi/tar.texi(,4381) The previous chapter showed how to use
@option{--extract} to extract
+../tar_texi/tar.texi(,4382) an archive into the file system. Various options
cause @command{tar} to
+../tar_texi/tar.texi(,4383) extract more information than just file contents,
such as the owner,
+../tar_texi/tar.texi(,4384) the permissions, the modification date, and so
forth. This section
+../tar_texi/tar.texi(,4385) presents options to be used with
@option{--extract} when certain special
+../tar_texi/tar.texi(,4386) considerations arise. You may review the
information presented in
+../tar_texi/tar.texi(,4387) @ref{extract} for more basic information about the
+../tar_texi/tar.texi(,4388) @option{--extract} operation.
+../tar_texi/tar.texi(,4389)
+../tar_texi/tar.texi(,4390) @menu
+../tar_texi/tar.texi(,4391) * Reading:: Options to Help
Read Archives
+../tar_texi/tar.texi(,4392) * Writing:: Changing How
@command{tar} Writes Files
+../tar_texi/tar.texi(,4393) * Scarce:: Coping with Scarce
Resources
+../tar_texi/tar.texi(,4394) @end menu
+../tar_texi/tar.texi(,4395)
+../tar_texi/tar.texi(,4396) @node Reading
+../tar_texi/tar.texi(,4397) @subsection Options to Help Read Archives
+../tar_texi/tar.texi(,4398) @cindex Options when reading archives
+../tar_texi/tar.texi(UNREVISED,4399) @quotation
+../tar_texi/tar.texi(UNREVISED,4399) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4399) @end quotation
+../tar_texi/tar.texi(UNREVISED,4399)
+../tar_texi/tar.texi(,4400)
+../tar_texi/tar.texi(,4401) @cindex Reading incomplete records
+../tar_texi/tar.texi(,4402) @cindex Records, incomplete
+../tar_texi/tar.texi(,4403) @opindex read-full-records
+../tar_texi/tar.texi(,4404) Normally, @command{tar} will request data in full
record increments from
+../tar_texi/tar.texi(,4405) an archive storage device. If the device cannot
return a full record,
+../tar_texi/tar.texi(,4406) @command{tar} will report an error. However, some
devices do not always
+../tar_texi/tar.texi(,4407) return full records, or do not require the last
record of an archive to
+../tar_texi/tar.texi(,4408) be padded out to the next record boundary. To
keep reading until you
+../tar_texi/tar.texi(,4409) obtain a full record, or to accept an incomplete
record if it contains
+../tar_texi/tar.texi(,4410) an end-of-archive marker, specify the
@option{--read-full-records} (@option{-B}) option
+../tar_texi/tar.texi(,4411) in conjunction with the @option{--extract} or
@option{--list} operations.
+../tar_texi/tar.texi(,4412) @xref{Blocking}.
+../tar_texi/tar.texi(,4413)
+../tar_texi/tar.texi(,4414) The @option{--read-full-records} (@option{-B})
option is turned on by default when
+../tar_texi/tar.texi(,4415) @command{tar} reads an archive from standard
input, or from a remote
+../tar_texi/tar.texi(,4416) machine. This is because on BSD Unix systems,
attempting to read a
+../tar_texi/tar.texi(,4417) pipe returns however much happens to be in the
pipe, even if it is
+../tar_texi/tar.texi(,4418) less than was requested. If this option were not
enabled, @command{tar}
+../tar_texi/tar.texi(,4419) would fail as soon as it read an incomplete record
from the pipe.
+../tar_texi/tar.texi(,4420)
+../tar_texi/tar.texi(,4421) If you're not sure of the blocking factor of an
archive, you can
+../tar_texi/tar.texi(,4422) read the archive by specifying
@option{--read-full-records} (@option{-B}) and
+../tar_texi/tar.texi(,4423) @address@hidden (@option{-b
+../tar_texi/tar.texi(,4424) @var{512-size}}), using a blocking factor larger
than what the archive
+../tar_texi/tar.texi(,4425) uses. This lets you avoid having to determine the
blocking factor
+../tar_texi/tar.texi(,4426) of an archive. @xref{Blocking Factor}.
+../tar_texi/tar.texi(,4427)
+../tar_texi/tar.texi(,4428) @menu
+../tar_texi/tar.texi(,4429) * read full records::
+../tar_texi/tar.texi(,4430) * Ignore Zeros::
+../tar_texi/tar.texi(,4431) @end menu
+../tar_texi/tar.texi(,4432)
+../tar_texi/tar.texi(,4433) @node read full records
+../tar_texi/tar.texi(,4434) @unnumberedsubsubsec Reading Full Records
+../tar_texi/tar.texi(,4435)
+../tar_texi/tar.texi(FIXME,4436) @allow-recursion
+../tar_texi/tar.texi(FIXME,4436) @quote-arg
+../tar_texi/tar.texi(FIXME,4436)
+../tar_texi/tar.texi(,4437)
+../tar_texi/tar.texi(,4438) @table @option
+../tar_texi/tar.texi(,4439) @opindex read-full-records
+../tar_texi/tar.texi(,4440) @item --read-full-records
+../tar_texi/tar.texi(,4441) @item -B
+../tar_texi/tar.texi(,4442) Use in conjunction with @option{--extract}
(@option{--get},
+../tar_texi/tar.texi(,4443) @option{-x}) to read an archive which contains
incomplete records, or
+../tar_texi/tar.texi(,4444) one which has a blocking factor less than the one
specified.
+../tar_texi/tar.texi(,4445) @end table
+../tar_texi/tar.texi(,4446)
+../tar_texi/tar.texi(,4447) @node Ignore Zeros
+../tar_texi/tar.texi(,4448) @unnumberedsubsubsec Ignoring Blocks of Zeros
+../tar_texi/tar.texi(,4449)
+../tar_texi/tar.texi(,4450) @cindex End-of-archive blocks, ignoring
+../tar_texi/tar.texi(,4451) @cindex Ignoring end-of-archive blocks
+../tar_texi/tar.texi(,4452) @opindex ignore-zeros
+../tar_texi/tar.texi(,4453) Normally, @command{tar} stops reading when it
encounters a block of zeros
+../tar_texi/tar.texi(,4454) between file entries (which usually indicates the
end of the archive).
+../tar_texi/tar.texi(,4455) @option{--ignore-zeros} (@option{-i}) allows
@command{tar} to
+../tar_texi/tar.texi(,4456) completely read an archive which contains a block
of zeros before the
+../tar_texi/tar.texi(,4457) end (i.e., a damaged archive, or one that was
created by concatenating
+../tar_texi/tar.texi(,4458) several archives together).
+../tar_texi/tar.texi(,4459)
+../tar_texi/tar.texi(,4460) The @option{--ignore-zeros} (@option{-i}) option
is turned off by default because many
+../tar_texi/tar.texi(,4461) versions of @command{tar} write garbage after the
end-of-archive entry,
+../tar_texi/tar.texi(GNUTAR,4462) since that part of the media is never
supposed to be read. @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,4463) does not write after the end of an archive, but
seeks to
+../tar_texi/tar.texi(,4464) maintain compatiblity among archiving utilities.
+../tar_texi/tar.texi(,4465)
+../tar_texi/tar.texi(,4466) @table @option
+../tar_texi/tar.texi(,4467) @item --ignore-zeros
+../tar_texi/tar.texi(,4468) @itemx -i
+../tar_texi/tar.texi(,4469) To ignore blocks of zeros (i.e., end-of-archive
entries) which may be
+../tar_texi/tar.texi(,4470) encountered while reading an archive. Use in
conjunction with
+../tar_texi/tar.texi(,4471) @option{--extract} or @option{--list}.
+../tar_texi/tar.texi(,4472) @end table
+../tar_texi/tar.texi(,4473)
+../tar_texi/tar.texi(,4474) @node Writing
+../tar_texi/tar.texi(,4475) @subsection Changing How @command{tar} Writes Files
+../tar_texi/tar.texi(UNREVISED,4476) @quotation
+../tar_texi/tar.texi(UNREVISED,4476) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4476) @end quotation
+../tar_texi/tar.texi(UNREVISED,4476)
+../tar_texi/tar.texi(,4477)
+../tar_texi/tar.texi(FIXME,4478) @allow-recursion
+../tar_texi/tar.texi(FIXME,4478) @quote-arg
+../tar_texi/tar.texi(FIXME,4478)
+../tar_texi/tar.texi(,4479)
+../tar_texi/tar.texi(,4480) @menu
+../tar_texi/tar.texi(,4481) * Dealing with Old Files::
+../tar_texi/tar.texi(,4482) * Overwrite Old Files::
+../tar_texi/tar.texi(,4483) * Keep Old Files::
+../tar_texi/tar.texi(,4484) * Keep Newer Files::
+../tar_texi/tar.texi(,4485) * Unlink First::
+../tar_texi/tar.texi(,4486) * Recursive Unlink::
+../tar_texi/tar.texi(,4487) * Data Modification Times::
+../tar_texi/tar.texi(,4488) * Setting Access Permissions::
+../tar_texi/tar.texi(,4489) * Directory Modification Times and Permissions::
+../tar_texi/tar.texi(,4490) * Writing to Standard Output::
+../tar_texi/tar.texi(,4491) * Writing to an External Program::
+../tar_texi/tar.texi(,4492) * remove files::
+../tar_texi/tar.texi(,4493) @end menu
+../tar_texi/tar.texi(,4494)
+../tar_texi/tar.texi(,4495) @node Dealing with Old Files
+../tar_texi/tar.texi(,4496) @unnumberedsubsubsec Options Controlling the
Overwriting of Existing Files
+../tar_texi/tar.texi(,4497)
+../tar_texi/tar.texi(xopindex,4498) @opindex address@hidden, introduced}
+../tar_texi/tar.texi(,4499) When extracting files, if @command{tar} discovers
that the extracted
+../tar_texi/tar.texi(,4500) file already exists, it normally replaces the file
by removing it before
+../tar_texi/tar.texi(,4501) extracting it, to prevent confusion in the
presence of hard or symbolic
+../tar_texi/tar.texi(,4502) links. (If the existing file is a symbolic link,
it is removed, not
+../tar_texi/tar.texi(,4503) followed.) However, if a directory cannot be
removed because it is
+../tar_texi/tar.texi(,4504) nonempty, @command{tar} normally overwrites its
metadata (ownership,
+../tar_texi/tar.texi(,4505) permission, etc.). The @option{--overwrite-dir}
option enables this
+../tar_texi/tar.texi(,4506) default behavior. To be more cautious and
preserve the metadata of
+../tar_texi/tar.texi(,4507) such a directory, use the
@option{--no-overwrite-dir} option.
+../tar_texi/tar.texi(,4508)
+../tar_texi/tar.texi(,4509) @cindex Overwriting old files, prevention
+../tar_texi/tar.texi(xopindex,4510) @opindex address@hidden, introduced}
+../tar_texi/tar.texi(,4511) To be even more cautious and prevent existing
files from being replaced, use
+../tar_texi/tar.texi(,4512) the @option{--keep-old-files} (@option{-k})
option. It causes @command{tar} to refuse
+../tar_texi/tar.texi(,4513) to replace or update a file that already exists,
i.e., a file with the
+../tar_texi/tar.texi(,4514) same name as an archive member prevents extraction
of that archive
+../tar_texi/tar.texi(,4515) member. Instead, it reports an error.
+../tar_texi/tar.texi(,4516)
+../tar_texi/tar.texi(xopindex,4517) @opindex address@hidden, introduced}
+../tar_texi/tar.texi(,4518) To be more aggressive about altering existing
files, use the
+../tar_texi/tar.texi(,4519) @option{--overwrite} option. It causes
@command{tar} to overwrite
+../tar_texi/tar.texi(,4520) existing files and to follow existing symbolic
links when extracting.
+../tar_texi/tar.texi(,4521)
+../tar_texi/tar.texi(,4522) @cindex Protecting old files
+../tar_texi/tar.texi(GNUTAR,4523) Some people argue that @acronym{GNU}
@command{tar} should not hesitate
+../tar_texi/tar.texi(,4524) to overwrite files with other files when
extracting. When extracting
+../tar_texi/tar.texi(,4525) a @command{tar} archive, they expect to see a
faithful copy of the
+../tar_texi/tar.texi(,4526) state of the file system when the archive was
created. It is debatable
+../tar_texi/tar.texi(,4527) that this would always be a proper behavior. For
example, suppose one
+../tar_texi/tar.texi(,4528) has an archive in which @file{usr/local} is a link
to
+../tar_texi/tar.texi(,4529) @file{usr/local2}. Since then, maybe the site
removed the link and
+../tar_texi/tar.texi(,4530) renamed the whole hierarchy from
@file{/usr/local2} to
+../tar_texi/tar.texi(,4531) @file{/usr/local}. Such things happen all the
time. I guess it would
+../tar_texi/tar.texi(GNUTAR,4532) not be welcome at all that @acronym{GNU}
@command{tar} removes the
+../tar_texi/tar.texi(,4533) whole hierarchy just to make room for the link to
be reinstated
+../tar_texi/tar.texi(,4534) (unless it @emph{also} simultaneously restores the
full
+../tar_texi/tar.texi(GNUTAR,4535) @file{/usr/local2}, of course!)
@acronym{GNU} @command{tar} is indeed
+../tar_texi/tar.texi(,4536) able to remove a whole hierarchy to reestablish a
symbolic link, for
+../tar_texi/tar.texi(,4537) example, but @emph{only if}
@option{--recursive-unlink} is specified
+../tar_texi/tar.texi(,4538) to allow this behavior. In any case, single files
are silently
+../tar_texi/tar.texi(,4539) removed.
+../tar_texi/tar.texi(,4540)
+../tar_texi/tar.texi(xopindex,4541) @opindex address@hidden, introduced}
+../tar_texi/tar.texi(,4542) Finally, the @option{--unlink-first} (@option{-U})
option can improve performance in
+../tar_texi/tar.texi(,4543) some cases by causing @command{tar} to remove
files unconditionally
+../tar_texi/tar.texi(,4544) before extracting them.
+../tar_texi/tar.texi(,4545)
+../tar_texi/tar.texi(,4546) @node Overwrite Old Files
+../tar_texi/tar.texi(,4547) @unnumberedsubsubsec Overwrite Old Files
+../tar_texi/tar.texi(,4548)
+../tar_texi/tar.texi(,4549) @table @option
+../tar_texi/tar.texi(,4550) @opindex overwrite
+../tar_texi/tar.texi(,4551) @item --overwrite
+../tar_texi/tar.texi(,4552) Overwrite existing files and directory metadata
when extracting files
+../tar_texi/tar.texi(,4553) from an archive.
+../tar_texi/tar.texi(,4554)
+../tar_texi/tar.texi(,4555) This causes @command{tar} to write extracted files
into the file system without
+../tar_texi/tar.texi(,4556) regard to the files already on the system; i.e.,
files with the same
+../tar_texi/tar.texi(,4557) names as archive members are overwritten when the
archive is extracted.
+../tar_texi/tar.texi(,4558) It also causes @command{tar} to extract the
ownership, permissions,
+../tar_texi/tar.texi(,4559) and time stamps onto any preexisting files or
directories.
+../tar_texi/tar.texi(,4560) If the name of a corresponding file name is a
symbolic link, the file
+../tar_texi/tar.texi(,4561) pointed to by the symbolic link will be
overwritten instead of the
+../tar_texi/tar.texi(,4562) symbolic link itself (if this is possible).
Moreover, special devices,
+../tar_texi/tar.texi(,4563) empty directories and even symbolic links are
automatically removed if
+../tar_texi/tar.texi(,4564) they are in the way of extraction.
+../tar_texi/tar.texi(,4565)
+../tar_texi/tar.texi(,4566) Be careful when using the @option{--overwrite}
option, particularly when
+../tar_texi/tar.texi(,4567) combined with the @option{--absolute-names}
(@option{-P}) option, as this combination
+../tar_texi/tar.texi(,4568) can change the contents, ownership or permissions
of any file on your
+../tar_texi/tar.texi(,4569) system. Also, many systems do not take kindly to
overwriting files that
+../tar_texi/tar.texi(,4570) are currently being executed.
+../tar_texi/tar.texi(,4571)
+../tar_texi/tar.texi(,4572) @opindex overwrite-dir
+../tar_texi/tar.texi(,4573) @item --overwrite-dir
+../tar_texi/tar.texi(,4574) Overwrite the metadata of directories when
extracting files from an
+../tar_texi/tar.texi(,4575) archive, but remove other files before extracting.
+../tar_texi/tar.texi(,4576) @end table
+../tar_texi/tar.texi(,4577)
+../tar_texi/tar.texi(,4578) @node Keep Old Files
+../tar_texi/tar.texi(,4579) @unnumberedsubsubsec Keep Old Files
+../tar_texi/tar.texi(,4580)
+../tar_texi/tar.texi(,4581) @table @option
+../tar_texi/tar.texi(,4582) @opindex keep-old-files
+../tar_texi/tar.texi(,4583) @item --keep-old-files
+../tar_texi/tar.texi(,4584) @itemx -k
+../tar_texi/tar.texi(,4585) Do not replace existing files from archive. The
+../tar_texi/tar.texi(,4586) @option{--keep-old-files} (@option{-k}) option
prevents @command{tar}
+../tar_texi/tar.texi(,4587) from replacing existing files with files with the
same name from the
+../tar_texi/tar.texi(,4588) archive. The @option{--keep-old-files} option is
meaningless with
+../tar_texi/tar.texi(,4589) @option{--list} (@option{-t}). Prevents
@command{tar} from replacing
+../tar_texi/tar.texi(,4590) files in the file system during extraction.
+../tar_texi/tar.texi(,4591) @end table
+../tar_texi/tar.texi(,4592)
+../tar_texi/tar.texi(,4593) @node Keep Newer Files
+../tar_texi/tar.texi(,4594) @unnumberedsubsubsec Keep Newer Files
+../tar_texi/tar.texi(,4595)
+../tar_texi/tar.texi(,4596) @table @option
+../tar_texi/tar.texi(,4597) @opindex keep-newer-files
+../tar_texi/tar.texi(,4598) @item --keep-newer-files
+../tar_texi/tar.texi(,4599) Do not replace existing files that are newer than
their archive
+../tar_texi/tar.texi(,4600) copies. This option is meaningless with
@option{--list} (@option{-t}).
+../tar_texi/tar.texi(,4601) @end table
+../tar_texi/tar.texi(,4602)
+../tar_texi/tar.texi(,4603) @node Unlink First
+../tar_texi/tar.texi(,4604) @unnumberedsubsubsec Unlink First
+../tar_texi/tar.texi(,4605)
+../tar_texi/tar.texi(,4606) @table @option
+../tar_texi/tar.texi(,4607) @opindex unlink-first
+../tar_texi/tar.texi(,4608) @item --unlink-first
+../tar_texi/tar.texi(,4609) @itemx -U
+../tar_texi/tar.texi(,4610) Remove files before extracting over them.
+../tar_texi/tar.texi(,4611) This can make @command{tar} run a bit faster if
you know in advance
+../tar_texi/tar.texi(,4612) that the extracted files all need to be removed.
Normally this option
+../tar_texi/tar.texi(,4613) slows @command{tar} down slightly, so it is
disabled by default.
+../tar_texi/tar.texi(,4614) @end table
+../tar_texi/tar.texi(,4615)
+../tar_texi/tar.texi(,4616) @node Recursive Unlink
+../tar_texi/tar.texi(,4617) @unnumberedsubsubsec Recursive Unlink
+../tar_texi/tar.texi(,4618)
+../tar_texi/tar.texi(,4619) @table @option
+../tar_texi/tar.texi(,4620) @opindex recursive-unlink
+../tar_texi/tar.texi(,4621) @item --recursive-unlink
+../tar_texi/tar.texi(,4622) When this option is specified, try removing files
and directory hierarchies
+../tar_texi/tar.texi(,4623) before extracting over them. @emph{This is a
dangerous option!}
+../tar_texi/tar.texi(,4624) @end table
+../tar_texi/tar.texi(,4625)
+../tar_texi/tar.texi(,4626) If you specify the @option{--recursive-unlink}
option,
+../tar_texi/tar.texi(,4627) @command{tar} removes @emph{anything} that keeps
you from extracting a file
+../tar_texi/tar.texi(,4628) as far as current permissions will allow it. This
could include removal
+../tar_texi/tar.texi(,4629) of the contents of a full directory hierarchy.
+../tar_texi/tar.texi(,4630)
+../tar_texi/tar.texi(,4631) @node Data Modification Times
+../tar_texi/tar.texi(,4632) @unnumberedsubsubsec Setting Data Modification
Times
+../tar_texi/tar.texi(,4633)
+../tar_texi/tar.texi(,4634) @cindex Data modification times of extracted files
+../tar_texi/tar.texi(,4635) @cindex Modification times of extracted files
+../tar_texi/tar.texi(,4636) Normally, @command{tar} sets the data modification
times of extracted
+../tar_texi/tar.texi(,4637) files to the corresponding times recorded for the
files in the archive, but
+../tar_texi/tar.texi(,4638) limits the permissions of extracted files by the
current @code{umask}
+../tar_texi/tar.texi(,4639) setting.
+../tar_texi/tar.texi(,4640)
+../tar_texi/tar.texi(,4641) To set the data modification times of extracted
files to the time when
+../tar_texi/tar.texi(,4642) the files were extracted, use the @option{--touch}
(@option{-m}) option in
+../tar_texi/tar.texi(,4643) conjunction with @option{--extract}
(@option{--get}, @option{-x}).
+../tar_texi/tar.texi(,4644)
+../tar_texi/tar.texi(,4645) @table @option
+../tar_texi/tar.texi(,4646) @opindex touch
+../tar_texi/tar.texi(,4647) @item --touch
+../tar_texi/tar.texi(,4648) @itemx -m
+../tar_texi/tar.texi(,4649) Sets the data modification time of extracted
archive members to the time
+../tar_texi/tar.texi(,4650) they were extracted, not the time recorded for
them in the archive.
+../tar_texi/tar.texi(,4651) Use in conjunction with @option{--extract}
(@option{--get}, @option{-x}).
+../tar_texi/tar.texi(,4652) @end table
+../tar_texi/tar.texi(,4653)
+../tar_texi/tar.texi(,4654) @node Setting Access Permissions
+../tar_texi/tar.texi(,4655) @unnumberedsubsubsec Setting Access Permissions
+../tar_texi/tar.texi(,4656)
+../tar_texi/tar.texi(,4657) @cindex Permissions of extracted files
+../tar_texi/tar.texi(,4658) @cindex Modes of extracted files
+../tar_texi/tar.texi(,4659) To set the modes (access permissions) of extracted
files to those
+../tar_texi/tar.texi(,4660) recorded for those files in the archive, use
@option{--same-permissions}
+../tar_texi/tar.texi(,4661) in conjunction with the @option{--extract}
(@option{--get},
+../tar_texi/tar.texi(,4662) @option{-x}) operation.
+../tar_texi/tar.texi(,4663)
+../tar_texi/tar.texi(,4664) @table @option
+../tar_texi/tar.texi(,4665) @opindex preserve-permissions
+../tar_texi/tar.texi(,4666) @opindex same-permissions
+../tar_texi/tar.texi(,4667) @item --preserve-permissions
+../tar_texi/tar.texi(,4668) @itemx --same-permissions
+../tar_texi/tar.texi(,4669) @c @itemx --ignore-umask
+../tar_texi/tar.texi(,4670) @itemx -p
+../tar_texi/tar.texi(,4671) Set modes of extracted archive members to those
recorded in the
+../tar_texi/tar.texi(,4672) archive, instead of current umask settings. Use
in conjunction with
+../tar_texi/tar.texi(,4673) @option{--extract} (@option{--get}, @option{-x}).
+../tar_texi/tar.texi(,4674) @end table
+../tar_texi/tar.texi(,4675)
+../tar_texi/tar.texi(,4676) @node Directory Modification Times and Permissions
+../tar_texi/tar.texi(,4677) @unnumberedsubsubsec Directory Modification Times
and Permissions
+../tar_texi/tar.texi(,4678)
+../tar_texi/tar.texi(GNUTAR,4679) After sucessfully extracting a file member,
@acronym{GNU} @command{tar} normally
+../tar_texi/tar.texi(,4680) restores its permissions and modification times,
as described in the
+../tar_texi/tar.texi(,4681) previous sections. This cannot be done for
directories, because
+../tar_texi/tar.texi(,4682) after extracting a directory @command{tar} will
almost certainly
+../tar_texi/tar.texi(,4683) extract files into that directory and this will
cause the directory
+../tar_texi/tar.texi(,4684) modification time to be updated. Moreover,
restoring that directory
+../tar_texi/tar.texi(,4685) permissions may not permit file creation within
it. Thus, restoring
+../tar_texi/tar.texi(,4686) directory permissions and modification times must
be delayed at least
+../tar_texi/tar.texi(GNUTAR,4687) until all files have been extracted into
that directory. @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,4688) restores directories using the following approach.
+../tar_texi/tar.texi(,4689)
+../tar_texi/tar.texi(,4690) The extracted directories are created with the
mode specified in the
+../tar_texi/tar.texi(,4691) archive, as modified by the umask of the user,
which gives sufficient
+../tar_texi/tar.texi(,4692) permissions to allow file creation. The
meta-information about the
+../tar_texi/tar.texi(,4693) directory is recorded in the temporary list of
directories. When
+../tar_texi/tar.texi(GNUTAR,4694) preparing to extract next archive member,
@acronym{GNU} @command{tar} checks if the
+../tar_texi/tar.texi(,4695) directory prefix of this file contains the
remembered directory. If
+../tar_texi/tar.texi(,4696) it does not, the program assumes that all files
have been extracted
+../tar_texi/tar.texi(,4697) into that directory, restores its modification
time and permissions
+../tar_texi/tar.texi(,4698) and removes its entry from the internal list.
This approach allows
+../tar_texi/tar.texi(,4699) to correctly restore directory meta-information in
the majority of
+../tar_texi/tar.texi(,4700) cases, while keeping memory requirements
sufficiently small. It is
+../tar_texi/tar.texi(,4701) based on the fact, that most @command{tar}
archives use the predefined
+../tar_texi/tar.texi(,4702) order of members: first the directory, then all
the files and
+../tar_texi/tar.texi(,4703) subdirectories in that directory.
+../tar_texi/tar.texi(,4704)
+../tar_texi/tar.texi(,4705) However, this is not always true. The most
important exception are
+../tar_texi/tar.texi(,4706) incremental archives (@pxref{Incremental Dumps}).
The member order in
+../tar_texi/tar.texi(,4707) an incremental archive is reversed: first all
directory members are
+../tar_texi/tar.texi(,4708) stored, followed by other (non-directory) members.
So, when extracting
+../tar_texi/tar.texi(GNUTAR,4709) from incremental archives, @acronym{GNU}
@command{tar} alters the above procedure. It
+../tar_texi/tar.texi(,4710) remebers all restored directories, and restores
their meta-data
+../tar_texi/tar.texi(,4711) only after the entire archive has been processed.
Notice, that you do
+../tar_texi/tar.texi(GNUTAR,4712) not need to specity any special options for
that, as @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,4713) automatically detects archives in incremental
format.
+../tar_texi/tar.texi(,4714)
+../tar_texi/tar.texi(,4715) There may be cases, when such processing is
required for normal archives
+../tar_texi/tar.texi(,4716) too. Consider the following example:
+../tar_texi/tar.texi(,4717)
+../tar_texi/tar.texi(,4718) @smallexample
+../tar_texi/tar.texi(,4719) @group
+../tar_texi/tar.texi(,4720) $ @kbd{tar --no-recursion -cvf archive \
+../tar_texi/tar.texi(,4721) foo foo/file1 bar bar/file foo/file2}
+../tar_texi/tar.texi(,4722) foo/
+../tar_texi/tar.texi(,4723) foo/file1
+../tar_texi/tar.texi(,4724) bar/
+../tar_texi/tar.texi(,4725) bar/file
+../tar_texi/tar.texi(,4726) foo/file2
+../tar_texi/tar.texi(,4727) @end group
+../tar_texi/tar.texi(,4728) @end smallexample
+../tar_texi/tar.texi(,4729)
+../tar_texi/tar.texi(,4730) During the normal operation, after encountering
@file{bar}
+../tar_texi/tar.texi(GNUTAR,4731) @acronym{GNU} @command{tar} will assume that
all files from the directory @file{foo}
+../tar_texi/tar.texi(,4732) were already extracted and will therefore restore
its timestamp and
+../tar_texi/tar.texi(,4733) permission bits. However, after extracting
@file{foo/file2} the
+../tar_texi/tar.texi(,4734) directory timestamp will be offset again.
+../tar_texi/tar.texi(,4735)
+../tar_texi/tar.texi(,4736) To correctly restore directory meta-information in
such cases, use
+../tar_texi/tar.texi(,4737) @option{delay-directory-restore} command line
option:
+../tar_texi/tar.texi(,4738)
+../tar_texi/tar.texi(,4739) @table @option
+../tar_texi/tar.texi(,4740) @opindex delay-directory-restore
+../tar_texi/tar.texi(,4741) @item --delay-directory-restore
+../tar_texi/tar.texi(,4742) Delays restoring of the modification times and
permissions of extracted
+../tar_texi/tar.texi(,4743) directories until the end of extraction. This
way, correct
+../tar_texi/tar.texi(,4744) meta-information is restored even if the archive
has unusual member
+../tar_texi/tar.texi(,4745) ordering.
+../tar_texi/tar.texi(,4746)
+../tar_texi/tar.texi(,4747) @opindex no-delay-directory-restore
+../tar_texi/tar.texi(,4748) @item --no-delay-directory-restore
+../tar_texi/tar.texi(,4749) Cancel the effect of the previous
@option{--delay-directory-restore}.
+../tar_texi/tar.texi(,4750) Use this option if you have used
@option{--delay-directory-restore} in
+../tar_texi/tar.texi(,4751) @env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS})
and wish to
+../tar_texi/tar.texi(,4752) temporarily disable it.
+../tar_texi/tar.texi(,4753) @end table
+../tar_texi/tar.texi(,4754)
+../tar_texi/tar.texi(,4755) @node Writing to Standard Output
+../tar_texi/tar.texi(,4756) @unnumberedsubsubsec Writing to Standard Output
+../tar_texi/tar.texi(,4757)
+../tar_texi/tar.texi(,4758) @cindex Writing extracted files to standard output
+../tar_texi/tar.texi(,4759) @cindex Standard output, writing extracted files to
+../tar_texi/tar.texi(,4760) To write the extracted files to the standard
output, instead of
+../tar_texi/tar.texi(,4761) creating the files on the file system, use
@option{--to-stdout} (@option{-O}) in
+../tar_texi/tar.texi(,4762) conjunction with @option{--extract}
(@option{--get}, @option{-x}). This option is useful if you are
+../tar_texi/tar.texi(,4763) extracting files to send them through a pipe, and
do not need to
+../tar_texi/tar.texi(,4764) preserve them in the file system. If you extract
multiple members,
+../tar_texi/tar.texi(,4765) they appear on standard output concatenated, in
the order they are
+../tar_texi/tar.texi(,4766) found in the archive.
+../tar_texi/tar.texi(,4767)
+../tar_texi/tar.texi(,4768) @table @option
+../tar_texi/tar.texi(,4769) @opindex to-stdout
+../tar_texi/tar.texi(,4770) @item --to-stdout
+../tar_texi/tar.texi(,4771) @itemx -O
+../tar_texi/tar.texi(,4772) Writes files to the standard output. Use only in
conjunction with
+../tar_texi/tar.texi(,4773) @option{--extract} (@option{--get}, @option{-x}).
When this option is
+../tar_texi/tar.texi(,4774) used, instead of creating the files specified,
@command{tar} writes
+../tar_texi/tar.texi(,4775) the contents of the files extracted to its
standard output. This may
+../tar_texi/tar.texi(,4776) be useful if you are only extracting the files in
order to send them
+../tar_texi/tar.texi(,4777) through a pipe. This option is meaningless with
@option{--list}
+../tar_texi/tar.texi(,4778) (@option{-t}).
+../tar_texi/tar.texi(,4779) @end table
+../tar_texi/tar.texi(,4780)
+../tar_texi/tar.texi(,4781) This can be useful, for example, if you have a tar
archive containing
+../tar_texi/tar.texi(,4782) a big file and don't want to store the file on
disk before processing
+../tar_texi/tar.texi(,4783) it. You can use a command like this:
+../tar_texi/tar.texi(,4784)
+../tar_texi/tar.texi(,4785) @smallexample
+../tar_texi/tar.texi(,4786) tar -xOzf foo.tgz bigfile | process
+../tar_texi/tar.texi(,4787) @end smallexample
+../tar_texi/tar.texi(,4788)
+../tar_texi/tar.texi(,4789) or even like this if you want to process the
concatenation of the files:
+../tar_texi/tar.texi(,4790)
+../tar_texi/tar.texi(,4791) @smallexample
+../tar_texi/tar.texi(,4792) tar -xOzf foo.tgz bigfile1 bigfile2 | process
+../tar_texi/tar.texi(,4793) @end smallexample
+../tar_texi/tar.texi(,4794)
+../tar_texi/tar.texi(,4795) Hovewer, @option{--to-command} may be more
convenient for use with
+../tar_texi/tar.texi(,4796) multiple files. See the next section.
+../tar_texi/tar.texi(,4797)
+../tar_texi/tar.texi(,4798) @node Writing to an External Program
+../tar_texi/tar.texi(,4799) @unnumberedsubsubsec Writing to an External Program
+../tar_texi/tar.texi(,4800)
+../tar_texi/tar.texi(,4801) You can instruct @command{tar} to send the
contents of each extracted
+../tar_texi/tar.texi(,4802) file to the standard input of an external program:
+../tar_texi/tar.texi(,4803)
+../tar_texi/tar.texi(,4804) @table @option
+../tar_texi/tar.texi(,4805) @opindex to-command
+../tar_texi/tar.texi(,4806) @item address@hidden
+../tar_texi/tar.texi(,4807) Extract files and pipe their contents to the
standard input of
+../tar_texi/tar.texi(,4808) @var{command}. When this option is used, instead
of creating the
+../tar_texi/tar.texi(,4809) files specified, @command{tar} invokes
@var{command} and pipes the
+../tar_texi/tar.texi(,4810) contents of the files to its standard output.
@var{Command} may
+../tar_texi/tar.texi(,4811) contain command line arguments. The program is
executed via
+../tar_texi/tar.texi(,4812) @code{sh -c}. Notice, that @var{command} is
executed once for each regular file
+../tar_texi/tar.texi(,4813) extracted. Non-regular files (directories, etc.)
are ignored when this
+../tar_texi/tar.texi(,4814) option is used.
+../tar_texi/tar.texi(,4815) @end table
+../tar_texi/tar.texi(,4816)
+../tar_texi/tar.texi(,4817) The command can obtain the information about the
file it processes
+../tar_texi/tar.texi(,4818) from the following environment variables:
+../tar_texi/tar.texi(,4819)
+../tar_texi/tar.texi(,4820) @table @var
+../tar_texi/tar.texi(,4821) @vrindex TAR_FILETYPE, to-command environment
+../tar_texi/tar.texi(,4822) @item TAR_FILETYPE
+../tar_texi/tar.texi(,4823) Type of the file. It is a single letter with the
following meaning:
+../tar_texi/tar.texi(,4824)
+../tar_texi/tar.texi(,4825) @multitable @columnfractions 0.10 0.90
+../tar_texi/tar.texi(,4826) @item f @tab Regular file
+../tar_texi/tar.texi(,4827) @item d @tab Directory
+../tar_texi/tar.texi(,4828) @item l @tab Symbolic link
+../tar_texi/tar.texi(,4829) @item h @tab Hard link
+../tar_texi/tar.texi(,4830) @item b @tab Block device
+../tar_texi/tar.texi(,4831) @item c @tab Character device
+../tar_texi/tar.texi(,4832) @end multitable
+../tar_texi/tar.texi(,4833)
+../tar_texi/tar.texi(,4834) Currently only regular files are supported.
+../tar_texi/tar.texi(,4835)
+../tar_texi/tar.texi(,4836) @vrindex TAR_MODE, to-command environment
+../tar_texi/tar.texi(,4837) @item TAR_MODE
+../tar_texi/tar.texi(,4838) File mode, an octal number.
+../tar_texi/tar.texi(,4839)
+../tar_texi/tar.texi(,4840) @vrindex TAR_FILENAME, to-command environment
+../tar_texi/tar.texi(,4841) @item TAR_FILENAME
+../tar_texi/tar.texi(,4842) The name of the file.
+../tar_texi/tar.texi(,4843)
+../tar_texi/tar.texi(,4844) @vrindex TAR_REALNAME, to-command environment
+../tar_texi/tar.texi(,4845) @item TAR_REALNAME
+../tar_texi/tar.texi(,4846) Name of the file as stored in the archive.
+../tar_texi/tar.texi(,4847)
+../tar_texi/tar.texi(,4848) @vrindex TAR_UNAME, to-command environment
+../tar_texi/tar.texi(,4849) @item TAR_UNAME
+../tar_texi/tar.texi(,4850) Name of the file owner.
+../tar_texi/tar.texi(,4851)
+../tar_texi/tar.texi(,4852) @vrindex TAR_GNAME, to-command environment
+../tar_texi/tar.texi(,4853) @item TAR_GNAME
+../tar_texi/tar.texi(,4854) Name of the file owner group.
+../tar_texi/tar.texi(,4855)
+../tar_texi/tar.texi(,4856) @vrindex TAR_ATIME, to-command environment
+../tar_texi/tar.texi(,4857) @item TAR_ATIME
+../tar_texi/tar.texi(,4858) Time of last access. It is a decimal number,
representing seconds
+../tar_texi/tar.texi(,4859) since the epoch. If the archive provides times
with nanosecond
+../tar_texi/tar.texi(,4860) precision, the nanoseconds are appended to the
timestamp after a
+../tar_texi/tar.texi(,4861) decimal point.
+../tar_texi/tar.texi(,4862)
+../tar_texi/tar.texi(,4863) @vrindex TAR_MTIME, to-command environment
+../tar_texi/tar.texi(,4864) @item TAR_MTIME
+../tar_texi/tar.texi(,4865) Time of last modification.
+../tar_texi/tar.texi(,4866)
+../tar_texi/tar.texi(,4867) @vrindex TAR_CTIME, to-command environment
+../tar_texi/tar.texi(,4868) @item TAR_CTIME
+../tar_texi/tar.texi(,4869) Time of last status change.
+../tar_texi/tar.texi(,4870)
+../tar_texi/tar.texi(,4871) @vrindex TAR_SIZE, to-command environment
+../tar_texi/tar.texi(,4872) @item TAR_SIZE
+../tar_texi/tar.texi(,4873) Size of the file.
+../tar_texi/tar.texi(,4874)
+../tar_texi/tar.texi(,4875) @vrindex TAR_UID, to-command environment
+../tar_texi/tar.texi(,4876) @item TAR_UID
+../tar_texi/tar.texi(,4877) UID of the file owner.
+../tar_texi/tar.texi(,4878)
+../tar_texi/tar.texi(,4879) @vrindex TAR_GID, to-command environment
+../tar_texi/tar.texi(,4880) @item TAR_GID
+../tar_texi/tar.texi(,4881) GID of the file owner.
+../tar_texi/tar.texi(,4882) @end table
+../tar_texi/tar.texi(,4883)
+../tar_texi/tar.texi(,4884) In addition to these variables, @env{TAR_VERSION}
contains the
+../tar_texi/tar.texi(GNUTAR,4885) @acronym{GNU} @command{tar} version number.
+../tar_texi/tar.texi(,4886)
+../tar_texi/tar.texi(,4887) If @var{command} exits with a non-0 status,
@command{tar} will print
+../tar_texi/tar.texi(,4888) an error message similar to the following:
+../tar_texi/tar.texi(,4889)
+../tar_texi/tar.texi(,4890) @smallexample
+../tar_texi/tar.texi(,4891) tar: 2345: Child returned status 1
+../tar_texi/tar.texi(,4892) @end smallexample
+../tar_texi/tar.texi(,4893)
+../tar_texi/tar.texi(,4894) Here, @samp{2345} is the PID of the finished
process.
+../tar_texi/tar.texi(,4895)
+../tar_texi/tar.texi(,4896) If this behavior is not wanted, use
@option{--ignore-command-error}:
+../tar_texi/tar.texi(,4897)
+../tar_texi/tar.texi(,4898) @table @option
+../tar_texi/tar.texi(,4899) @opindex ignore-command-error
+../tar_texi/tar.texi(,4900) @item --ignore-command-error
+../tar_texi/tar.texi(,4901) Ignore exit codes of subprocesses. Notice that if
the program
+../tar_texi/tar.texi(,4902) exits on signal or otherwise terminates
abnormally, the error message
+../tar_texi/tar.texi(,4903) will be printed even if this option is used.
+../tar_texi/tar.texi(,4904)
+../tar_texi/tar.texi(,4905) @opindex no-ignore-command-error
+../tar_texi/tar.texi(,4906) @item --no-ignore-command-error
+../tar_texi/tar.texi(,4907) Cancel the effect of any previous
@option{--ignore-command-error}
+../tar_texi/tar.texi(,4908) option. This option is useful if you have set
+../tar_texi/tar.texi(,4909) @option{--ignore-command-error} in
@env{TAR_OPTIONS}
+../tar_texi/tar.texi(,4910) (@pxref{TAR_OPTIONS}) and wish to temporarily
cancel it.
+../tar_texi/tar.texi(,4911) @end table
+../tar_texi/tar.texi(,4912)
+../tar_texi/tar.texi(,4913) @node remove files
+../tar_texi/tar.texi(,4914) @unnumberedsubsubsec Removing Files
+../tar_texi/tar.texi(,4915)
+../tar_texi/tar.texi(FIXME,4917) @allow-recursion
+../tar_texi/tar.texi(FIXME,4917) @quote-arg
+../tar_texi/tar.texi(FIXME,4917)
+../tar_texi/tar.texi(,4918)
+../tar_texi/tar.texi(,4919) @table @option
+../tar_texi/tar.texi(,4920) @opindex remove-files
+../tar_texi/tar.texi(,4921) @item --remove-files
+../tar_texi/tar.texi(,4922) Remove files after adding them to the archive.
+../tar_texi/tar.texi(,4923) @end table
+../tar_texi/tar.texi(,4924)
+../tar_texi/tar.texi(,4925) @node Scarce
+../tar_texi/tar.texi(,4926) @subsection Coping with Scarce Resources
+../tar_texi/tar.texi(UNREVISED,4927) @quotation
+../tar_texi/tar.texi(UNREVISED,4927) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4927) @end quotation
+../tar_texi/tar.texi(UNREVISED,4927)
+../tar_texi/tar.texi(,4928)
+../tar_texi/tar.texi(,4929) @cindex Small memory
+../tar_texi/tar.texi(,4930) @cindex Running out of space
+../tar_texi/tar.texi(,4931)
+../tar_texi/tar.texi(,4932) @menu
+../tar_texi/tar.texi(,4933) * Starting File::
+../tar_texi/tar.texi(,4934) * Same Order::
+../tar_texi/tar.texi(,4935) @end menu
+../tar_texi/tar.texi(,4936)
+../tar_texi/tar.texi(,4937) @node Starting File
+../tar_texi/tar.texi(,4938) @unnumberedsubsubsec Starting File
+../tar_texi/tar.texi(,4939)
+../tar_texi/tar.texi(,4940) @table @option
+../tar_texi/tar.texi(,4941) @opindex starting-file
+../tar_texi/tar.texi(,4942) @item address@hidden
+../tar_texi/tar.texi(,4943) @itemx -K @var{name}
+../tar_texi/tar.texi(,4944) Starts an operation in the middle of an archive.
Use in conjunction
+../tar_texi/tar.texi(,4945) with @option{--extract} (@option{--get},
@option{-x}) or @option{--list} (@option{-t}).
+../tar_texi/tar.texi(,4946) @end table
+../tar_texi/tar.texi(,4947)
+../tar_texi/tar.texi(,4948) @cindex Middle of the archive, starting in the
+../tar_texi/tar.texi(,4949) If a previous attempt to extract files failed due
to lack of disk
+../tar_texi/tar.texi(,4950) space, you can use @address@hidden (@option{-K
+../tar_texi/tar.texi(,4951) @var{name}}) to start extracting only after member
@var{name} of the
+../tar_texi/tar.texi(,4952) archive. This assumes, of course, that there is
now free space, or
+../tar_texi/tar.texi(,4953) that you are now extracting into a different file
system. (You could
+../tar_texi/tar.texi(,4954) also choose to suspend @command{tar}, remove
unnecessary files from
+../tar_texi/tar.texi(,4955) the file system, and then restart the same
@command{tar} operation.
+../tar_texi/tar.texi(,4956) In this case, @option{--starting-file} is not
necessary.
+../tar_texi/tar.texi(,4957) @xref{Incremental Dumps}, @xref{interactive}, and
@ref{exclude}.)
+../tar_texi/tar.texi(,4958)
+../tar_texi/tar.texi(,4959) @node Same Order
+../tar_texi/tar.texi(,4960) @unnumberedsubsubsec Same Order
+../tar_texi/tar.texi(,4961)
+../tar_texi/tar.texi(,4962) @table @option
+../tar_texi/tar.texi(,4963) @cindex Large lists of file names on small machines
+../tar_texi/tar.texi(,4964) @opindex same-order
+../tar_texi/tar.texi(,4965) @opindex preserve-order
+../tar_texi/tar.texi(,4966) @item --same-order
+../tar_texi/tar.texi(,4967) @itemx --preserve-order
+../tar_texi/tar.texi(,4968) @itemx -s
+../tar_texi/tar.texi(,4969) To process large lists of file names on machines
with small amounts of
+../tar_texi/tar.texi(,4970) memory. Use in conjunction with
@option{--compare} (@option{--diff},
+../tar_texi/tar.texi(,4971) @option{-d}), @option{--list} (@option{-t}) or
@option{--extract}
+../tar_texi/tar.texi(,4972) (@option{--get}, @option{-x}).
+../tar_texi/tar.texi(,4973) @end table
+../tar_texi/tar.texi(,4974)
+../tar_texi/tar.texi(,4975) The @option{--same-order}
(@option{--preserve-order}, @option{-s}) option tells @command{tar} that the
list of file
+../tar_texi/tar.texi(,4976) names to be listed or extracted is sorted in the
same order as the
+../tar_texi/tar.texi(,4977) files in the archive. This allows a large list of
names to be used,
+../tar_texi/tar.texi(,4978) even on a small machine that would not otherwise
be able to hold all
+../tar_texi/tar.texi(,4979) the names in memory at the same time. Such a
sorted list can easily be
+../tar_texi/tar.texi(,4980) created by running @samp{tar -t} on the archive
and editing its output.
+../tar_texi/tar.texi(,4981)
+../tar_texi/tar.texi(,4982) This option is probably never needed on modern
computer systems.
+../tar_texi/tar.texi(,4983)
+../tar_texi/tar.texi(,4984) @node backup
+../tar_texi/tar.texi(,4985) @section Backup options
+../tar_texi/tar.texi(,4986)
+../tar_texi/tar.texi(,4987) @cindex backup options
+../tar_texi/tar.texi(,4988)
+../tar_texi/tar.texi(GNUTAR,4989) @acronym{GNU} @command{tar} offers options
for making backups of files
+../tar_texi/tar.texi(,4990) before writing new versions. These options
control the details of
+../tar_texi/tar.texi(,4991) these backups. They may apply to the archive
itself before it is
+../tar_texi/tar.texi(,4992) created or rewritten, as well as individual
extracted members. Other
+../tar_texi/tar.texi(,4993) @acronym{GNU} programs (@command{cp},
@command{install}, @command{ln},
+../tar_texi/tar.texi(,4994) and @command{mv}, for example) offer similar
options.
+../tar_texi/tar.texi(,4995)
+../tar_texi/tar.texi(,4996) Backup options may prove unexpectedly useful when
extracting archives
+../tar_texi/tar.texi(,4997) containing many members having identical name, or
when extracting archives
+../tar_texi/tar.texi(,4998) on systems having file name limitations, making
different members appear
+../tar_texi/tar.texi(,4999) has having similar names through the side-effect
of name truncation.
+../tar_texi/tar.texi(,5000) (This is true only if we have a good scheme for
truncated backup names,
+../tar_texi/tar.texi(,5001) which I'm not sure at all: I suspect work is
needed in this area.)
+../tar_texi/tar.texi(,5002) When any existing file is backed up before being
overwritten by extraction,
+../tar_texi/tar.texi(,5003) then clashing files are automatically be renamed
to be unique, and the
+../tar_texi/tar.texi(,5004) true name is kept for only the last file of a
series of clashing files.
+../tar_texi/tar.texi(,5005) By using verbose mode, users may track exactly
what happens.
+../tar_texi/tar.texi(,5006)
+../tar_texi/tar.texi(,5007) At the detail level, some decisions are still
experimental, and may
+../tar_texi/tar.texi(,5008) change in the future, we are waiting comments from
our users. So, please
+../tar_texi/tar.texi(,5009) do not learn to depend blindly on the details of
the backup features.
+../tar_texi/tar.texi(,5010) For example, currently, directories themselves are
never renamed through
+../tar_texi/tar.texi(,5011) using these options, so, extracting a file over a
directory still has
+../tar_texi/tar.texi(,5012) good chances to fail. Also, backup options apply
to created archives,
+../tar_texi/tar.texi(,5013) not only to extracted members. For created
archives, backups will not
+../tar_texi/tar.texi(,5014) be attempted when the archive is a block or
character device, or when it
+../tar_texi/tar.texi(,5015) refers to a remote file.
+../tar_texi/tar.texi(,5016)
+../tar_texi/tar.texi(,5017) For the sake of simplicity and efficiency, backups
are made by renaming old
+../tar_texi/tar.texi(,5018) files prior to creation or extraction, and not by
copying. The original
+../tar_texi/tar.texi(,5019) name is restored if the file creation fails. If a
failure occurs after a
+../tar_texi/tar.texi(,5020) partial extraction of a file, both the backup and
the partially extracted
+../tar_texi/tar.texi(,5021) file are kept.
+../tar_texi/tar.texi(,5022)
+../tar_texi/tar.texi(,5023) @table @samp
+../tar_texi/tar.texi(,5024) @item address@hidden
+../tar_texi/tar.texi(,5025) @opindex backup
+../tar_texi/tar.texi(,5026) @vindex VERSION_CONTROL
+../tar_texi/tar.texi(,5027) @cindex backups
+../tar_texi/tar.texi(,5028) Back up files that are about to be overwritten or
removed.
+../tar_texi/tar.texi(,5029) Without this option, the original versions are
destroyed.
+../tar_texi/tar.texi(,5030)
+../tar_texi/tar.texi(,5031) Use @var{method} to determine the type of backups
made.
+../tar_texi/tar.texi(,5032) If @var{method} is not specified, use the value of
the @env{VERSION_CONTROL}
+../tar_texi/tar.texi(,5033) environment variable. And if
@env{VERSION_CONTROL} is not set,
+../tar_texi/tar.texi(,5034) use the @samp{existing} method.
+../tar_texi/tar.texi(,5035)
+../tar_texi/tar.texi(,5036) @vindex version-control @r{Emacs variable}
+../tar_texi/tar.texi(,5037) This option corresponds to the Emacs variable
@samp{version-control};
+../tar_texi/tar.texi(,5038) the same values for @var{method} are accepted as
in Emacs. This option
+../tar_texi/tar.texi(,5039) also allows more descriptive names. The valid
@var{method}s are:
+../tar_texi/tar.texi(,5040)
+../tar_texi/tar.texi(,5041) @table @samp
+../tar_texi/tar.texi(,5042) @item t
+../tar_texi/tar.texi(,5043) @itemx numbered
+../tar_texi/tar.texi(,5044) @cindex numbered @r{backup method}
+../tar_texi/tar.texi(,5045) Always make numbered backups.
+../tar_texi/tar.texi(,5046)
+../tar_texi/tar.texi(,5047) @item nil
+../tar_texi/tar.texi(,5048) @itemx existing
+../tar_texi/tar.texi(,5049) @cindex existing @r{backup method}
+../tar_texi/tar.texi(,5050) Make numbered backups of files that already have
them, simple backups
+../tar_texi/tar.texi(,5051) of the others.
+../tar_texi/tar.texi(,5052)
+../tar_texi/tar.texi(,5053) @item never
+../tar_texi/tar.texi(,5054) @itemx simple
+../tar_texi/tar.texi(,5055) @cindex simple @r{backup method}
+../tar_texi/tar.texi(,5056) Always make simple backups.
+../tar_texi/tar.texi(,5057)
+../tar_texi/tar.texi(,5058) @end table
+../tar_texi/tar.texi(,5059)
+../tar_texi/tar.texi(,5060) @item address@hidden
+../tar_texi/tar.texi(,5061) @opindex suffix
+../tar_texi/tar.texi(,5062) @cindex backup suffix
+../tar_texi/tar.texi(,5063) @vindex SIMPLE_BACKUP_SUFFIX
+../tar_texi/tar.texi(,5064) Append @var{suffix} to each backup file made with
@option{--backup}. If this
+../tar_texi/tar.texi(,5065) option is not specified, the value of the
@env{SIMPLE_BACKUP_SUFFIX}
+../tar_texi/tar.texi(,5066) environment variable is used. And if
@env{SIMPLE_BACKUP_SUFFIX} is not
+../tar_texi/tar.texi(,5067) set, the default is @samp{~}, just as in Emacs.
+../tar_texi/tar.texi(,5068)
+../tar_texi/tar.texi(,5069) @end table
+../tar_texi/tar.texi(,5070)
+../tar_texi/tar.texi(,5071) @node Applications
+../tar_texi/tar.texi(,5072) @section Notable @command{tar} Usages
+../tar_texi/tar.texi(UNREVISED,5073) @quotation
+../tar_texi/tar.texi(UNREVISED,5073) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,5073) @end quotation
+../tar_texi/tar.texi(UNREVISED,5073)
+../tar_texi/tar.texi(,5074)
+../tar_texi/tar.texi(FIXME,5077) @allow-recursion
+../tar_texi/tar.texi(FIXME,5077) @quote-arg
+../tar_texi/tar.texi(FIXME,5077)
+../tar_texi/tar.texi(,5078)
+../tar_texi/tar.texi(FIXME,5079) @allow-recursion
+../tar_texi/tar.texi(FIXME,5079) @quote-arg
+../tar_texi/tar.texi(FIXME,5079)
+../tar_texi/tar.texi(,5080)
+../tar_texi/tar.texi(,5081) @findex uuencode
+../tar_texi/tar.texi(,5082) You can easily use archive files to transport a
group of files from
+../tar_texi/tar.texi(,5083) one system to another: put all relevant files into
an archive on one
+../tar_texi/tar.texi(,5084) computer system, transfer the archive to another
system, and extract
+../tar_texi/tar.texi(,5085) the contents there. The basic transfer medium
might be magnetic tape,
+../tar_texi/tar.texi(,5086) Internet FTP, or even electronic mail (though you
must encode the
+../tar_texi/tar.texi(,5087) archive with @command{uuencode} in order to
transport it properly by
+../tar_texi/tar.texi(,5088) mail). Both machines do not have to use the same
operating system, as
+../tar_texi/tar.texi(,5089) long as they both support the @command{tar}
program.
+../tar_texi/tar.texi(,5090)
+../tar_texi/tar.texi(,5091) For example, here is how you might copy a
directory's contents from
+../tar_texi/tar.texi(,5092) one disk to another, while preserving the dates,
modes, owners and
+../tar_texi/tar.texi(,5093) link-structure of all the files therein. In this
case, the transfer
+../tar_texi/tar.texi(,5094) medium is a @dfn{pipe}, which is one a Unix
redirection mechanism:
+../tar_texi/tar.texi(,5095)
+../tar_texi/tar.texi(,5096) @smallexample
+../tar_texi/tar.texi(,5097) $ @kbd{(cd sourcedir; tar -cf - .) | (cd
targetdir; tar -xf -)}
+../tar_texi/tar.texi(,5098) @end smallexample
+../tar_texi/tar.texi(,5099)
+../tar_texi/tar.texi(,5100) @noindent
+../tar_texi/tar.texi(,5101) You can avoid subshells by using @option{-C}
option:
+../tar_texi/tar.texi(,5102)
+../tar_texi/tar.texi(,5103) @smallexample
+../tar_texi/tar.texi(,5104) $ @kbd{tar -C sourcedir -cf - . | tar -C targetdir
-xf -}
+../tar_texi/tar.texi(,5105) @end smallexample
+../tar_texi/tar.texi(,5106)
+../tar_texi/tar.texi(,5107) @noindent
+../tar_texi/tar.texi(,5108) The command also works using short option forms:
+../tar_texi/tar.texi(,5109)
+../tar_texi/tar.texi(,5110) @smallexample
+../tar_texi/tar.texi(,5111) $ @kbd{(cd sourcedir; tar --create --file=- . ) \
+../tar_texi/tar.texi(,5112) | (cd targetdir; tar --extract --file=-)}
+../tar_texi/tar.texi(,5113) # Or:
+../tar_texi/tar.texi(,5114) $ @kbd{tar --directory sourcedir --create --file=-
. ) \
+../tar_texi/tar.texi(,5115) | tar --directory targetdir --extract
--file=-}
+../tar_texi/tar.texi(,5116) @end smallexample
+../tar_texi/tar.texi(,5117)
+../tar_texi/tar.texi(,5118) @noindent
+../tar_texi/tar.texi(,5119) This is one of the easiest methods to transfer a
@command{tar} archive.
+../tar_texi/tar.texi(,5120)
+../tar_texi/tar.texi(,5121) @node looking ahead
+../tar_texi/tar.texi(,5122) @section Looking Ahead: The Rest of this Manual
+../tar_texi/tar.texi(,5123)
+../tar_texi/tar.texi(,5124) You have now seen how to use all eight of the
operations available to
+../tar_texi/tar.texi(,5125) @command{tar}, and a number of the possible
options. The next chapter
+../tar_texi/tar.texi(,5126) explains how to choose and change file and archive
names, how to use
+../tar_texi/tar.texi(,5127) files to store names of other files which you can
then call as
+../tar_texi/tar.texi(,5128) arguments to @command{tar} (this can help you save
time if you expect to
+../tar_texi/tar.texi(,5129) archive the same list of files a number of times),
and so forth.
+../tar_texi/tar.texi(FIXME,5133) @allow-recursion
+../tar_texi/tar.texi(FIXME,5133) @quote-arg
+../tar_texi/tar.texi(FIXME,5133)
+../tar_texi/tar.texi(,5134)
+../tar_texi/tar.texi(,5135) If there are too many files to conveniently list
on the command line,
+../tar_texi/tar.texi(,5136) you can list the names in a file, and
@command{tar} will read that file.
+../tar_texi/tar.texi(,5137) @xref{files}.
+../tar_texi/tar.texi(,5138)
+../tar_texi/tar.texi(,5139) There are various ways of causing @command{tar} to
skip over some files,
+../tar_texi/tar.texi(,5140) and not archive them. @xref{Choosing}.
+../tar_texi/tar.texi(,5141)
+../tar_texi/tar.texi(,5142) @node Backups
+../tar_texi/tar.texi(,5143) @chapter Performing Backups and Restoring Files
+../tar_texi/tar.texi(UNREVISED,5144) @quotation
+../tar_texi/tar.texi(UNREVISED,5144) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,5144) @end quotation
+../tar_texi/tar.texi(UNREVISED,5144)
+../tar_texi/tar.texi(,5145)
+../tar_texi/tar.texi(GNUTAR,5146) @acronym{GNU} @command{tar} is distributed
along with the scripts
+../tar_texi/tar.texi(,5147) which the Free Software Foundation uses for
performing backups. There
+../tar_texi/tar.texi(,5148) is no corresponding scripts available yet for
doing restoration of
+../tar_texi/tar.texi(,5149) files. Even if there is a good chance those
scripts may be satisfying
+../tar_texi/tar.texi(,5150) to you, they are not the only scripts or methods
available for doing
+../tar_texi/tar.texi(,5151) backups and restore. You may well create your
own, or use more
+../tar_texi/tar.texi(,5152) sophisticated packages dedicated to that purpose.
+../tar_texi/tar.texi(,5153)
+../tar_texi/tar.texi(,5154) Some users are enthusiastic about @code{Amanda}
(The Advanced Maryland
+../tar_texi/tar.texi(,5155) Automatic Network Disk Archiver), a backup system
developed by James
+../tar_texi/tar.texi(,5156) da Silva @file{jds@@cs.umd.edu} and available on
many Unix systems.
+../tar_texi/tar.texi(,5157) This is free software, and it is available at
these places:
+../tar_texi/tar.texi(,5158)
+../tar_texi/tar.texi(,5159) @smallexample
+../tar_texi/tar.texi(,5160) http://www.cs.umd.edu/projects/amanda/amanda.html
+../tar_texi/tar.texi(,5161) ftp://ftp.cs.umd.edu/pub/amanda
+../tar_texi/tar.texi(,5162) @end smallexample
+../tar_texi/tar.texi(,5163)
+../tar_texi/tar.texi(FIXME,5209) @allow-recursion
+../tar_texi/tar.texi(FIXME,5209) @quote-arg
+../tar_texi/tar.texi(FIXME,5209)
+../tar_texi/tar.texi(,5210)
+../tar_texi/tar.texi(,5211) This chapter documents both the provided shell
scripts and @command{tar}
+../tar_texi/tar.texi(,5212) options which are more specific to usage as a
backup tool.
+../tar_texi/tar.texi(,5213)
+../tar_texi/tar.texi(,5214) To @dfn{back up} a file system means to create
archives that contain
+../tar_texi/tar.texi(,5215) all the files in that file system. Those archives
can then be used to
+../tar_texi/tar.texi(,5216) restore any or all of those files (for instance if
a disk crashes or a
+../tar_texi/tar.texi(,5217) file is accidentally deleted). File system
@dfn{backups} are also
+../tar_texi/tar.texi(,5218) called @dfn{dumps}.
+../tar_texi/tar.texi(,5219)
+../tar_texi/tar.texi(,5220) @menu
+../tar_texi/tar.texi(,5221) * Full Dumps:: Using
@command{tar} to Perform Full Dumps
+../tar_texi/tar.texi(,5222) * Incremental Dumps:: Using
@command{tar} to Perform Incremental Dumps
+../tar_texi/tar.texi(,5223) * Backup Levels:: Levels of Backups
+../tar_texi/tar.texi(,5224) * Backup Parameters:: Setting Parameters
for Backups and Restoration
+../tar_texi/tar.texi(,5225) * Scripted Backups:: Using the Backup
Scripts
+../tar_texi/tar.texi(,5226) * Scripted Restoration:: Using the Restore
Script
+../tar_texi/tar.texi(,5227) @end menu
+../tar_texi/tar.texi(,5228)
+../tar_texi/tar.texi(,5229) @node Full Dumps
+../tar_texi/tar.texi(,5230) @section Using @command{tar} to Perform Full Dumps
+../tar_texi/tar.texi(UNREVISED,5231) @quotation
+../tar_texi/tar.texi(UNREVISED,5231) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,5231) @end quotation
+../tar_texi/tar.texi(UNREVISED,5231)
+../tar_texi/tar.texi(,5232)
+../tar_texi/tar.texi(,5233) @cindex full dumps
+../tar_texi/tar.texi(,5234) @cindex dumps, full
+../tar_texi/tar.texi(,5235)
+../tar_texi/tar.texi(,5236) @cindex corrupted archives
+../tar_texi/tar.texi(,5237) Full dumps should only be made when no other
people or programs
+../tar_texi/tar.texi(,5238) are modifying files in the file system. If files
are modified while
+../tar_texi/tar.texi(,5239) @command{tar} is making the backup, they may not
be stored properly in
+../tar_texi/tar.texi(,5240) the archive, in which case you won't be able to
restore them if you
+../tar_texi/tar.texi(,5241) have to. (Files not being modified are written
with no trouble, and do
+../tar_texi/tar.texi(,5242) not corrupt the entire archive.)
+../tar_texi/tar.texi(,5243)
+../tar_texi/tar.texi(,5244) You will want to use the @address@hidden
+../tar_texi/tar.texi(,5245) (@option{-V @var{archive-label}}) option to give
the archive a
+../tar_texi/tar.texi(,5246) volume label, so you can tell what this archive is
even if the label
+../tar_texi/tar.texi(,5247) falls off the tape, or anything like that.
+../tar_texi/tar.texi(,5248)
+../tar_texi/tar.texi(,5249) Unless the file system you are dumping is
guaranteed to fit on
+../tar_texi/tar.texi(,5250) one volume, you will need to use the
@option{--multi-volume} (@option{-M}) option.
+../tar_texi/tar.texi(,5251) Make sure you have enough tapes on hand to
complete the backup.
+../tar_texi/tar.texi(,5252)
+../tar_texi/tar.texi(,5253) If you want to dump each file system separately
you will need to use
+../tar_texi/tar.texi(,5254) the @option{--one-file-system} option to prevent
+../tar_texi/tar.texi(,5255) @command{tar} from crossing file system boundaries
when storing
+../tar_texi/tar.texi(,5256) (sub)directories.
+../tar_texi/tar.texi(,5257)
+../tar_texi/tar.texi(,5258) The @option{--incremental} (@option{-G})
(@pxref{Incremental Dumps})
+../tar_texi/tar.texi(,5259) option is not needed, since this is a complete
copy of everything in
+../tar_texi/tar.texi(,5260) the file system, and a full restore from this
backup would only be
+../tar_texi/tar.texi(,5261) done onto a completely
+../tar_texi/tar.texi(,5262) empty disk.
+../tar_texi/tar.texi(,5263)
+../tar_texi/tar.texi(,5264) Unless you are in a hurry, and trust the
@command{tar} program (and your
+../tar_texi/tar.texi(,5265) tapes), it is a good idea to use the
@option{--verify} (@option{-W})
+../tar_texi/tar.texi(,5266) option, to make sure your files really made it
onto the dump properly.
+../tar_texi/tar.texi(,5267) This will also detect cases where the file was
modified while (or just
+../tar_texi/tar.texi(,5268) after) it was being archived. Not all media
(notably cartridge tapes)
+../tar_texi/tar.texi(,5269) are capable of being verified, unfortunately.
+../tar_texi/tar.texi(,5270)
+../tar_texi/tar.texi(,5271) @node Incremental Dumps
+../tar_texi/tar.texi(,5272) @section Using @command{tar} to Perform
Incremental Dumps
+../tar_texi/tar.texi(,5273)
+../tar_texi/tar.texi(GNUTAR,5274) @dfn{Incremental backup} is a special form
of @acronym{GNU} @command{tar} archive that
+../tar_texi/tar.texi(,5275) stores additional metadata so that exact state of
the file system
+../tar_texi/tar.texi(,5276) can be restored when extracting the archive.
+../tar_texi/tar.texi(,5277)
+../tar_texi/tar.texi(GNUTAR,5278) @acronym{GNU} @command{tar} currently offers
two options for handling incremental
+../tar_texi/tar.texi(,5279) backups: @address@hidden (@option{-g
+../tar_texi/tar.texi(,5280) @var{snapshot-file}}) and @option{--incremental}
(@option{-G}).
+../tar_texi/tar.texi(,5281)
+../tar_texi/tar.texi(,5282) @opindex listed-incremental
+../tar_texi/tar.texi(,5283) The option @option{--listed-incremental} instructs
tar to operate on
+../tar_texi/tar.texi(,5284) an incremental archive with additional metadata
stored in a standalone
+../tar_texi/tar.texi(,5285) file, called a @dfn{snapshot file}. The purpose
of this file is to help
+../tar_texi/tar.texi(,5286) determine which files have been changed, added or
deleted since the
+../tar_texi/tar.texi(,5287) last backup, so that the next incremental backup
will contain only
+../tar_texi/tar.texi(,5288) modified files. The name of the snapshot file is
given as an argument
+../tar_texi/tar.texi(,5289) to the option:
+../tar_texi/tar.texi(,5290)
+../tar_texi/tar.texi(,5291) @table @option
+../tar_texi/tar.texi(,5292) @item address@hidden
+../tar_texi/tar.texi(,5293) @itemx -g @var{file}
+../tar_texi/tar.texi(,5294) Handle incremental backups with snapshot data in
@var{file}.
+../tar_texi/tar.texi(,5295) @end table
+../tar_texi/tar.texi(,5296)
+../tar_texi/tar.texi(,5297) To create an incremental backup, you would use
+../tar_texi/tar.texi(,5298) @option{--listed-incremental} together with
@option{--create}
+../tar_texi/tar.texi(,5299) (@pxref{create}). For example:
+../tar_texi/tar.texi(,5300)
+../tar_texi/tar.texi(,5301) @smallexample
+../tar_texi/tar.texi(,5302) $ @kbd{tar --create \
+../tar_texi/tar.texi(,5303) --file=archive.1.tar \
+../tar_texi/tar.texi(,5304) --listed-incremental=/var/log/usr.snar \
+../tar_texi/tar.texi(,5305) /usr}
+../tar_texi/tar.texi(,5306) @end smallexample
+../tar_texi/tar.texi(,5307)
+../tar_texi/tar.texi(,5308) This will create in @file{archive.1.tar} an
incremental backup of
+../tar_texi/tar.texi(,5309) the @file{/usr} file system, storing additional
metadata in the file
+../tar_texi/tar.texi(,5310) @file{/var/log/usr.snar}. If this file does not
exist, it will be
+../tar_texi/tar.texi(,5311) created. The created archive will then be a
@dfn{level 0 backup};
+../tar_texi/tar.texi(,5312) please see the next section for more on backup
levels.
+../tar_texi/tar.texi(,5313)
+../tar_texi/tar.texi(,5314) Otherwise, if the file @file{/var/log/usr.snar}
exists, it
+../tar_texi/tar.texi(,5315) determines which files are modified. In this case
only these files will be
+../tar_texi/tar.texi(,5316) stored in the archive. Suppose, for example, that
after running the
+../tar_texi/tar.texi(,5317) above command, you delete file @file{/usr/doc/old}
and create
+../tar_texi/tar.texi(,5318) directory @file{/usr/local/db} with the following
contents:
+../tar_texi/tar.texi(,5319)
+../tar_texi/tar.texi(,5320) @smallexample
+../tar_texi/tar.texi(,5321) $ @kbd{ls /usr/local/db}
+../tar_texi/tar.texi(,5322) /usr/local/db/data
+../tar_texi/tar.texi(,5323) /usr/local/db/index
+../tar_texi/tar.texi(,5324) @end smallexample
+../tar_texi/tar.texi(,5325)
+../tar_texi/tar.texi(,5326) Some time later you create another incremental
backup. You will
+../tar_texi/tar.texi(,5327) then see:
+../tar_texi/tar.texi(,5328)
+../tar_texi/tar.texi(,5329) @smallexample
+../tar_texi/tar.texi(,5330) $ @kbd{tar --create \
+../tar_texi/tar.texi(,5331) --file=archive.2.tar \
+../tar_texi/tar.texi(,5332) --listed-incremental=/var/log/usr.snar \
+../tar_texi/tar.texi(,5333) /usr}
+../tar_texi/tar.texi(,5334) tar: usr/local/db: Directory is new
+../tar_texi/tar.texi(,5335) usr/local/db/
+../tar_texi/tar.texi(,5336) usr/local/db/data
+../tar_texi/tar.texi(,5337) usr/local/db/index
+../tar_texi/tar.texi(,5338) @end smallexample
+../tar_texi/tar.texi(,5339)
+../tar_texi/tar.texi(,5340) @noindent
+../tar_texi/tar.texi(,5341) The created archive @file{archive.2.tar} will
contain only these
+../tar_texi/tar.texi(,5342) three members. This archive is called a
@dfn{level 1 backup}. Notice
+../tar_texi/tar.texi(,5343) that @file{/var/log/usr.snar} will be updated with
the new data, so if
+../tar_texi/tar.texi(,5344) you plan to create more @samp{level 1} backups, it
is necessary to
+../tar_texi/tar.texi(,5345) create a working copy of the snapshot file before
running
+../tar_texi/tar.texi(,5346) @command{tar}. The above example will then be
modified as follows:
+../tar_texi/tar.texi(,5347)
+../tar_texi/tar.texi(,5348) @smallexample
+../tar_texi/tar.texi(,5349) $ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+../tar_texi/tar.texi(,5350) $ @kbd{tar --create \
+../tar_texi/tar.texi(,5351) --file=archive.2.tar \
+../tar_texi/tar.texi(,5352)
--listed-incremental=/var/log/usr.snar-1 \
+../tar_texi/tar.texi(,5353) /usr}
+../tar_texi/tar.texi(,5354) @end smallexample
+../tar_texi/tar.texi(,5355)
+../tar_texi/tar.texi(,5356) Incremental dumps depend crucially on time stamps,
so the results are
+../tar_texi/tar.texi(,5357) unreliable if you modify a file's time stamps
during dumping (e.g.,
+../tar_texi/tar.texi(,5358) with the @option{--atime-preserve=replace}
option), or if you set the clock
+../tar_texi/tar.texi(,5359) backwards.
+../tar_texi/tar.texi(,5360)
+../tar_texi/tar.texi(,5361) Metadata stored in snapshot files include device
numbers, which,
+../tar_texi/tar.texi(,5362) obviously is supposed to be a non-volatile value.
However, it turns
+../tar_texi/tar.texi(,5363) out that NFS devices have undependable values when
an automounter
+../tar_texi/tar.texi(,5364) gets in the picture. This can lead to a great
deal of spurious
+../tar_texi/tar.texi(,5365) redumping in incremental dumps, so it is somewhat
useless to compare
+../tar_texi/tar.texi(,5366) two NFS devices numbers over time. The solution
implemented currently
+../tar_texi/tar.texi(,5367) is to considers all NFS devices as being equal
when it comes to
+../tar_texi/tar.texi(,5368) comparing directories; this is fairly gross, but
there does not seem
+../tar_texi/tar.texi(,5369) to be a better way to go.
+../tar_texi/tar.texi(,5370)
+../tar_texi/tar.texi(,5371) Note that incremental archives use @command{tar}
extensions and may
+../tar_texi/tar.texi(,5372) not be readable by address@hidden versions of the
@command{tar} program.
+../tar_texi/tar.texi(,5373)
+../tar_texi/tar.texi(xopindex,5374) @opindex address@hidden, using with
@option{--extract}}
+../tar_texi/tar.texi(xopindex,5375) @opindex address@hidden, using with
@option{--listed-incremental}}
+../tar_texi/tar.texi(,5376) To extract from the incremental dumps, use
+../tar_texi/tar.texi(,5377) @option{--listed-incremental} together with
@option{--extract}
+../tar_texi/tar.texi(,5378) option (@pxref{extracting files}). In this case,
@command{tar} does
+../tar_texi/tar.texi(,5379) not need to access snapshot file, since all the
data necessary for
+../tar_texi/tar.texi(,5380) extraction are stored in the archive itself. So,
when extracting, you
+../tar_texi/tar.texi(,5381) can give whatever argument to
@option{--listed-incremental}, the usual
+../tar_texi/tar.texi(,5382) practice is to use
@option{--listed-incremental=/dev/null}.
+../tar_texi/tar.texi(,5383) Alternatively, you can use @option{--incremental},
which needs no
+../tar_texi/tar.texi(,5384) arguments. In general, @option{--incremental}
(@option{-G}) can be
+../tar_texi/tar.texi(,5385) used as a shortcut for
@option{--listed-incremental} when listing or
+../tar_texi/tar.texi(,5386) extracting incremental backups (for more
information, regarding this
+../tar_texi/tar.texi(,5387) option, @pxref{incremental-op}).
+../tar_texi/tar.texi(,5388)
+../tar_texi/tar.texi(GNUTAR,5389) When extracting from the incremental backup
@acronym{GNU} @command{tar} attempts to
+../tar_texi/tar.texi(,5390) restore the exact state the file system had when
the archive was
+../tar_texi/tar.texi(,5391) created. In particular, it will @emph{delete}
those files in the file
+../tar_texi/tar.texi(,5392) system that did not exist in their directories
when the archive was
+../tar_texi/tar.texi(,5393) created. If you have created several levels of
incremental files,
+../tar_texi/tar.texi(,5394) then in order to restore the exact contents the
file system had when
+../tar_texi/tar.texi(,5395) the last level was created, you will need to
restore from all backups
+../tar_texi/tar.texi(,5396) in turn. Continuing our example, to restore the
state of @file{/usr}
+../tar_texi/tar.texi(,5397) file system, one would address@hidden, that since
both archives
+../tar_texi/tar.texi(,5398) were created withouth @option{-P} option
(@pxref{absolute}), these
+../tar_texi/tar.texi(,5399) commands should be run from the root file system.}:
+../tar_texi/tar.texi(,5400)
+../tar_texi/tar.texi(,5401) @smallexample
+../tar_texi/tar.texi(,5402) $ @kbd{tar --extract \
+../tar_texi/tar.texi(,5403) --listed-incremental=/dev/null \
+../tar_texi/tar.texi(,5404) --file archive.1.tar}
+../tar_texi/tar.texi(,5405) $ @kbd{tar --extract \
+../tar_texi/tar.texi(,5406) --listed-incremental=/dev/null \
+../tar_texi/tar.texi(,5407) --file archive.2.tar}
+../tar_texi/tar.texi(,5408) @end smallexample
+../tar_texi/tar.texi(,5409)
+../tar_texi/tar.texi(,5410) To list the contents of an incremental archive,
use @option{--list}
+../tar_texi/tar.texi(,5411) (@pxref{list}), as usual. To obtain more
information about the
+../tar_texi/tar.texi(,5412) archive, use @option{--listed-incremental} or
@option{--incremental}
+../tar_texi/tar.texi(,5413) combined with two @option{--verbose} address@hidden
+../tar_texi/tar.texi(,5414) @option{--verbose} options were selected to avoid
breaking usual
+../tar_texi/tar.texi(,5415) verbose listing output (@option{--list --verbose})
when using in
+../tar_texi/tar.texi(,5416) scripts.
+../tar_texi/tar.texi(,5417)
+../tar_texi/tar.texi(xopindex,5418) @opindex address@hidden, using with
@option{--list}}
+../tar_texi/tar.texi(xopindex,5419) @opindex address@hidden, using with
@option{--list}}
+../tar_texi/tar.texi(xopindex,5420) @opindex address@hidden, using with
@option{--incremental}}
+../tar_texi/tar.texi(xopindex,5421) @opindex address@hidden, using with
@option{--listed-incremental}}
+../tar_texi/tar.texi(GNUTAR,5422) Versions of @acronym{GNU} @command{tar} up
to 1.15.1 used to dump verbatim binary
+../tar_texi/tar.texi(,5423) contents of the DUMPDIR header (with terminating
nulls) when
+../tar_texi/tar.texi(,5424) @option{--incremental} or
@option{--listed-incremental} option was
+../tar_texi/tar.texi(,5425) given, no matter what the verbosity level. This
behavior, and,
+../tar_texi/tar.texi(,5426) especially, the binary output it produced were
considered incovenient
+../tar_texi/tar.texi(,5427) and were changed in version 1.16}:
+../tar_texi/tar.texi(,5428)
+../tar_texi/tar.texi(,5429) @smallexample
+../tar_texi/tar.texi(,5430) @kbd{tar --list --incremental --verbose --verbose
archive.tar}
+../tar_texi/tar.texi(,5431) @end smallexample
+../tar_texi/tar.texi(,5432)
+../tar_texi/tar.texi(,5433) This command will print, for each directory in the
archive, the list
+../tar_texi/tar.texi(,5434) of files in that directory at the time the archive
was created. This
+../tar_texi/tar.texi(,5435) information is put out in a format which is both
human-readable and
+../tar_texi/tar.texi(,5436) unambiguous for a program: each file name is
printed as
+../tar_texi/tar.texi(,5437)
+../tar_texi/tar.texi(,5438) @smallexample
+../tar_texi/tar.texi(,5439) @var{x} @var{file}
+../tar_texi/tar.texi(,5440) @end smallexample
+../tar_texi/tar.texi(,5441)
+../tar_texi/tar.texi(,5442) @noindent
+../tar_texi/tar.texi(,5443) where @var{x} is a letter describing the status of
the file: @samp{Y}
+../tar_texi/tar.texi(,5444) if the file is present in the archive, @samp{N}
if the file is not
+../tar_texi/tar.texi(,5445) included in the archive, or a @samp{D} if the file
is a directory (and
+../tar_texi/tar.texi(,5446) is included in the archive). @xref{Dumpdir}, for
the detailed
+../tar_texi/tar.texi(,5447) description of dumpdirs and status codes. Each
such
+../tar_texi/tar.texi(,5448) line is terminated by a newline character. The
last line is followed
+../tar_texi/tar.texi(,5449) by an additional newline to indicate the end of
the data.
+../tar_texi/tar.texi(,5450)
+../tar_texi/tar.texi(,5451) @anchor{incremental-op}The option
@option{--incremental} (@option{-G})
+../tar_texi/tar.texi(,5452) gives the same behavior as
@option{--listed-incremental} when used
+../tar_texi/tar.texi(,5453) with @option{--list} and @option{--extract}
options. When used with
+../tar_texi/tar.texi(,5454) @option{--create} option, it creates an
incremental archive without
+../tar_texi/tar.texi(,5455) creating snapshot file. Thus, it is impossible to
create several
+../tar_texi/tar.texi(,5456) levels of incremental backups with
@option{--incremental} option.
+../tar_texi/tar.texi(,5457)
+../tar_texi/tar.texi(,5458) @node Backup Levels
+../tar_texi/tar.texi(,5459) @section Levels of Backups
+../tar_texi/tar.texi(,5460)
+../tar_texi/tar.texi(,5461) An archive containing all the files in the file
system is called a
+../tar_texi/tar.texi(,5462) @dfn{full backup} or @dfn{full dump}. You could
insure your data by
+../tar_texi/tar.texi(,5463) creating a full dump every day. This strategy,
however, would waste a
+../tar_texi/tar.texi(,5464) substantial amount of archive media and user time,
as unchanged files
+../tar_texi/tar.texi(,5465) are daily re-archived.
+../tar_texi/tar.texi(,5466)
+../tar_texi/tar.texi(,5467) It is more efficient to do a full dump only
occasionally. To back up
+../tar_texi/tar.texi(,5468) files between full dumps, you can use
@dfn{incremental dumps}. A @dfn{level
+../tar_texi/tar.texi(,5469) one} dump archives all the files that have changed
since the last full
+../tar_texi/tar.texi(,5470) dump.
+../tar_texi/tar.texi(,5471)
+../tar_texi/tar.texi(,5472) A typical dump strategy would be to perform a full
dump once a week,
+../tar_texi/tar.texi(,5473) and a level one dump once a day. This means some
versions of files
+../tar_texi/tar.texi(,5474) will in fact be archived more than once, but this
dump strategy makes
+../tar_texi/tar.texi(,5475) it possible to restore a file system to within one
day of accuracy by
+../tar_texi/tar.texi(,5476) only extracting two archives---the last weekly
(full) dump and the
+../tar_texi/tar.texi(,5477) last daily (level one) dump. The only information
lost would be in
+../tar_texi/tar.texi(,5478) files changed or created since the last daily
backup. (Doing dumps
+../tar_texi/tar.texi(,5479) more than once a day is usually not worth the
trouble).
+../tar_texi/tar.texi(,5480)
+../tar_texi/tar.texi(GNUTAR,5481) @acronym{GNU} @command{tar} comes with
scripts you can use to do full
+../tar_texi/tar.texi(,5482) and level-one (actually, even level-two and so on)
dumps. Using
+../tar_texi/tar.texi(,5483) scripts (shell programs) to perform backups and
restoration is a
+../tar_texi/tar.texi(,5484) convenient and reliable alternative to typing out
file name lists
+../tar_texi/tar.texi(,5485) and @command{tar} commands by hand.
+../tar_texi/tar.texi(,5486)
+../tar_texi/tar.texi(,5487) Before you use these scripts, you need to edit the
file
+../tar_texi/tar.texi(,5488) @file{backup-specs}, which specifies parameters
used by the backup
+../tar_texi/tar.texi(,5489) scripts and by the restore script. This file is
usually located
+../tar_texi/tar.texi(,5490) in @file{/etc/backup} directory. @xref{Backup
Parameters}, for its
+../tar_texi/tar.texi(,5491) detailed description. Once the backup parameters
are set, you can
+../tar_texi/tar.texi(,5492) perform backups or restoration by running the
appropriate script.
+../tar_texi/tar.texi(,5493)
+../tar_texi/tar.texi(,5494) The name of the backup script is @code{backup}.
The name of the
+../tar_texi/tar.texi(,5495) restore script is @code{restore}. The following
sections describe
+../tar_texi/tar.texi(,5496) their use in detail.
+../tar_texi/tar.texi(,5497)
+../tar_texi/tar.texi(,5498) @emph{Please Note:} The backup and restoration
scripts are
+../tar_texi/tar.texi(,5499) designed to be used together. While it is
possible to restore files by
+../tar_texi/tar.texi(,5500) hand from an archive which was created using a
backup script, and to create
+../tar_texi/tar.texi(,5501) an archive by hand which could then be extracted
using the restore script,
+../tar_texi/tar.texi(,5502) it is easier to use the scripts.
@xref{Incremental Dumps}, before
+../tar_texi/tar.texi(,5503) making such an attempt.
+../tar_texi/tar.texi(,5504)
+../tar_texi/tar.texi(,5505) @node Backup Parameters
+../tar_texi/tar.texi(,5506) @section Setting Parameters for Backups and
Restoration
+../tar_texi/tar.texi(,5507)
+../tar_texi/tar.texi(,5508) The file @file{backup-specs} specifies backup
parameters for the
+../tar_texi/tar.texi(,5509) backup and restoration scripts provided with
@command{tar}. You must
+../tar_texi/tar.texi(,5510) edit @file{backup-specs} to fit your system
configuration and schedule
+../tar_texi/tar.texi(,5511) before using these scripts.
+../tar_texi/tar.texi(,5512)
+../tar_texi/tar.texi(,5513) Syntactically, @file{backup-specs} is a shell
script, containing
+../tar_texi/tar.texi(,5514) mainly variable assignments. However, any valid
shell construct
+../tar_texi/tar.texi(,5515) is allowed in this file. Particularly, you may
wish to define
+../tar_texi/tar.texi(,5516) functions within that script (e.g., see
@code{RESTORE_BEGIN} below).
+../tar_texi/tar.texi(,5517) For more information about shell script syntax,
please refer to
+../tar_texi/tar.texi(,5518)
@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+../tar_texi/tar.texi(,5519) g_02, the definition of the Shell Command
Language}. See also
+../tar_texi/tar.texi(,5520) @ref{Top,,Bash Features,bashref,Bash Reference
Manual}.
+../tar_texi/tar.texi(,5521)
+../tar_texi/tar.texi(,5522) The shell variables controlling behavior of
@code{backup} and
+../tar_texi/tar.texi(,5523) @code{restore} are described in the following
subsections.
+../tar_texi/tar.texi(,5524)
+../tar_texi/tar.texi(,5525) @menu
+../tar_texi/tar.texi(,5526) * General-Purpose Variables::
+../tar_texi/tar.texi(,5527) * Magnetic Tape Control::
+../tar_texi/tar.texi(,5528) * User Hooks::
+../tar_texi/tar.texi(,5529) * backup-specs example:: An Example Text of
@file{Backup-specs}
+../tar_texi/tar.texi(,5530) @end menu
+../tar_texi/tar.texi(,5531)
+../tar_texi/tar.texi(,5532) @node General-Purpose Variables
+../tar_texi/tar.texi(,5533) @subsection General-Purpose Variables
+../tar_texi/tar.texi(,5534)
+../tar_texi/tar.texi(,5535) @defvr {Backup variable} ADMINISTRATOR
+../tar_texi/tar.texi(,5536) The user name of the backup administrator.
@code{Backup} scripts
+../tar_texi/tar.texi(,5537) sends a backup report to this address.
+../tar_texi/tar.texi(,5538) @end defvr
+../tar_texi/tar.texi(,5539)
+../tar_texi/tar.texi(,5540) @defvr {Backup variable} BACKUP_HOUR
+../tar_texi/tar.texi(,5541) The hour at which the backups are done. This can
be a number from 0
+../tar_texi/tar.texi(,5542) to 23, or the time specification in form
@var{hours}:@var{minutes},
+../tar_texi/tar.texi(,5543) or the string @samp{now}.
+../tar_texi/tar.texi(,5544)
+../tar_texi/tar.texi(,5545) This variable is used by @code{backup}. Its value
may be overridden
+../tar_texi/tar.texi(,5546) using @option{--time} option (@pxref{Scripted
Backups}).
+../tar_texi/tar.texi(,5547) @end defvr
+../tar_texi/tar.texi(,5548)
+../tar_texi/tar.texi(,5549) @defvr {Backup variable} TAPE_FILE
+../tar_texi/tar.texi(,5550)
+../tar_texi/tar.texi(,5551) The device @command{tar} writes the archive to.
If @var{TAPE_FILE}
+../tar_texi/tar.texi(,5552) is a remote archive (@pxref{remote-dev}), backup
script will suppose
+../tar_texi/tar.texi(,5553) that your @command{mt} is able to access remote
devices. If @var{RSH}
+../tar_texi/tar.texi(,5554) (@pxref{RSH}) is set, @option{--rsh-command}
option will be added to
+../tar_texi/tar.texi(,5555) invocations of @command{mt}.
+../tar_texi/tar.texi(,5556) @end defvr
+../tar_texi/tar.texi(,5557)
+../tar_texi/tar.texi(,5558) @defvr {Backup variable} BLOCKING
+../tar_texi/tar.texi(,5559)
+../tar_texi/tar.texi(,5560) The blocking factor @command{tar} will use when
writing the dump archive.
+../tar_texi/tar.texi(,5561) @xref{Blocking Factor}.
+../tar_texi/tar.texi(,5562) @end defvr
+../tar_texi/tar.texi(,5563)
+../tar_texi/tar.texi(,5564) @defvr {Backup variable} BACKUP_DIRS
+../tar_texi/tar.texi(,5565)
+../tar_texi/tar.texi(,5566) A list of file systems to be dumped (for
@code{backup}), or restored
+../tar_texi/tar.texi(,5567) (for @code{restore}). You can include any
directory
+../tar_texi/tar.texi(,5568) name in the list --- subdirectories on that file
system will be
+../tar_texi/tar.texi(,5569) included, regardless of how they may look to other
networked machines.
+../tar_texi/tar.texi(,5570) Subdirectories on other file systems will be
ignored.
+../tar_texi/tar.texi(,5571)
+../tar_texi/tar.texi(,5572) The host name specifies which host to run
@command{tar} on, and should
+../tar_texi/tar.texi(,5573) normally be the host that actually contains the
file system. However,
+../tar_texi/tar.texi(GNUTAR,5574) the host machine must have @acronym{GNU}
@command{tar} installed, and
+../tar_texi/tar.texi(,5575) must be able to access the directory containing
the backup scripts and
+../tar_texi/tar.texi(,5576) their support files using the same file name that
is used on the
+../tar_texi/tar.texi(,5577) machine where the scripts are run (i.e. what
@command{pwd} will print
+../tar_texi/tar.texi(,5578) when in that directory on that machine). If the
host that contains
+../tar_texi/tar.texi(,5579) the file system does not have this capability, you
can specify another
+../tar_texi/tar.texi(,5580) host as long as it can access the file system
through NFS.
+../tar_texi/tar.texi(,5581)
+../tar_texi/tar.texi(,5582) If the list of file systems is very long you may
wish to put it
+../tar_texi/tar.texi(,5583) in a separate file. This file is usually named
+../tar_texi/tar.texi(,5584) @file{/etc/backup/dirs}, but this name may be
overridden in
+../tar_texi/tar.texi(,5585) @file{backup-specs} using @code{DIRLIST} variable.
+../tar_texi/tar.texi(,5586) @end defvr
+../tar_texi/tar.texi(,5587)
+../tar_texi/tar.texi(,5588) @defvr {Backup variable} DIRLIST
+../tar_texi/tar.texi(,5589)
+../tar_texi/tar.texi(,5590) A path to the file containing the list of the file
systems to backup
+../tar_texi/tar.texi(,5591) or restore. By default it is
@file{/etc/backup/dirs}.
+../tar_texi/tar.texi(,5592) @end defvr
+../tar_texi/tar.texi(,5593)
+../tar_texi/tar.texi(,5594) @defvr {Backup variable} BACKUP_FILES
+../tar_texi/tar.texi(,5595)
+../tar_texi/tar.texi(,5596) A list of individual files to be dumped (for
@code{backup}), or restored
+../tar_texi/tar.texi(,5597) (for @code{restore}). These should be accessible
from the machine on
+../tar_texi/tar.texi(,5598) which the backup script is run.
+../tar_texi/tar.texi(,5599)
+../tar_texi/tar.texi(,5600) If the list of file systems is very long you may
wish to store it
+../tar_texi/tar.texi(,5601) in a separate file. This file is usually named
+../tar_texi/tar.texi(,5602) @file{/etc/backup/files}, but this name may be
overridden in
+../tar_texi/tar.texi(,5603) @file{backup-specs} using @code{FILELIST} variable.
+../tar_texi/tar.texi(,5604) @end defvr
+../tar_texi/tar.texi(,5605)
+../tar_texi/tar.texi(,5606) @defvr {Backup variable} FILELIST
+../tar_texi/tar.texi(,5607)
+../tar_texi/tar.texi(,5608) A path to the file containing the list of the
individual files to backup
+../tar_texi/tar.texi(,5609) or restore. By default it is
@file{/etc/backup/files}.
+../tar_texi/tar.texi(,5610) @end defvr
+../tar_texi/tar.texi(,5611)
+../tar_texi/tar.texi(,5612) @defvr {Backup variable} MT
+../tar_texi/tar.texi(,5613)
+../tar_texi/tar.texi(,5614) Full file name of @command{mt} binary.
+../tar_texi/tar.texi(,5615) @end defvr
+../tar_texi/tar.texi(,5616)
+../tar_texi/tar.texi(,5617) @defvr {Backup variable} RSH
+../tar_texi/tar.texi(,5618) @anchor{RSH}
+../tar_texi/tar.texi(,5619) Full file name of @command{rsh} binary or its
equivalent. You may wish to
+../tar_texi/tar.texi(,5620) set it to @code{ssh}, to improve security. In
this case you will have
+../tar_texi/tar.texi(,5621) to use public key authentication.
+../tar_texi/tar.texi(,5622) @end defvr
+../tar_texi/tar.texi(,5623)
+../tar_texi/tar.texi(,5624) @defvr {Backup variable} RSH_COMMAND
+../tar_texi/tar.texi(,5625)
+../tar_texi/tar.texi(,5626) Full file name of @command{rsh} binary on remote
mashines. This will
+../tar_texi/tar.texi(,5627) be passed via @option{--rsh-command} option to the
remote invocation
+../tar_texi/tar.texi(GNUTAR,5628) of @acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,5629) @end defvr
+../tar_texi/tar.texi(,5630)
+../tar_texi/tar.texi(,5631) @defvr {Backup variable} VOLNO_FILE
+../tar_texi/tar.texi(,5632)
+../tar_texi/tar.texi(,5633) Name of temporary file to hold volume numbers.
This needs to be accessible
+../tar_texi/tar.texi(,5634) by all the machines which have file systems to be
dumped.
+../tar_texi/tar.texi(,5635) @end defvr
+../tar_texi/tar.texi(,5636)
+../tar_texi/tar.texi(,5637) @defvr {Backup variable} XLIST
+../tar_texi/tar.texi(,5638)
+../tar_texi/tar.texi(,5639) Name of @dfn{exclude file list}. An @dfn{exclude
file list} is a file
+../tar_texi/tar.texi(,5640) located on the remote machine and containing the
list of files to
+../tar_texi/tar.texi(,5641) be excluded from the backup. Exclude file lists
are searched in
+../tar_texi/tar.texi(,5642) /etc/tar-backup directory. A common use for
exclude file lists
+../tar_texi/tar.texi(,5643) is to exclude files containing security-sensitive
information
+../tar_texi/tar.texi(,5644) (e.g., @file{/etc/shadow} from backups).
+../tar_texi/tar.texi(,5645)
+../tar_texi/tar.texi(,5646) This variable affects only @code{backup}.
+../tar_texi/tar.texi(,5647) @end defvr
+../tar_texi/tar.texi(,5648)
+../tar_texi/tar.texi(,5649) @defvr {Backup variable} SLEEP_TIME
+../tar_texi/tar.texi(,5650)
+../tar_texi/tar.texi(,5651) Time to sleep between dumps of any two successive
file systems
+../tar_texi/tar.texi(,5652)
+../tar_texi/tar.texi(,5653) This variable affects only @code{backup}.
+../tar_texi/tar.texi(,5654) @end defvr
+../tar_texi/tar.texi(,5655)
+../tar_texi/tar.texi(,5656) @defvr {Backup variable} DUMP_REMIND_SCRIPT
+../tar_texi/tar.texi(,5657)
+../tar_texi/tar.texi(,5658) Script to be run when it's time to insert a new
tape in for the next
+../tar_texi/tar.texi(,5659) volume. Administrators may want to tailor this
script for their site.
+../tar_texi/tar.texi(GNUTAR,5660) If this variable isn't set, @acronym{GNU}
@command{tar} will display its built-in
+../tar_texi/tar.texi(,5661) prompt, and will expect confirmation from the
console. For the
+../tar_texi/tar.texi(,5662) description of the default prompt, see @ref{change
volume prompt}.
+../tar_texi/tar.texi(,5663)
+../tar_texi/tar.texi(,5664) @end defvr
+../tar_texi/tar.texi(,5665)
+../tar_texi/tar.texi(,5666) @defvr {Backup variable} SLEEP_MESSAGE
+../tar_texi/tar.texi(,5667)
+../tar_texi/tar.texi(,5668) Message to display on the terminal while waiting
for dump time. Usually
+../tar_texi/tar.texi(,5669) this will just be some literal text.
+../tar_texi/tar.texi(,5670) @end defvr
+../tar_texi/tar.texi(,5671)
+../tar_texi/tar.texi(,5672) @defvr {Backup variable} TAR
+../tar_texi/tar.texi(,5673)
+../tar_texi/tar.texi(GNUTAR,5674) Full file name of the @acronym{GNU}
@command{tar} executable. If this is not set, backup
+../tar_texi/tar.texi(,5675) scripts will search @command{tar} in the current
shell path.
+../tar_texi/tar.texi(,5676) @end defvr
+../tar_texi/tar.texi(,5677)
+../tar_texi/tar.texi(,5678) @node Magnetic Tape Control
+../tar_texi/tar.texi(,5679) @subsection Magnetic Tape Control
+../tar_texi/tar.texi(,5680)
+../tar_texi/tar.texi(,5681) Backup scripts access tape device using special
@dfn{hook functions}.
+../tar_texi/tar.texi(,5682) These functions take a single argument -- the name
of the tape
+../tar_texi/tar.texi(,5683) device. Their names are kept in the following
variables:
+../tar_texi/tar.texi(,5684)
+../tar_texi/tar.texi(,5685) @defvr {Backup variable} MT_BEGIN
+../tar_texi/tar.texi(,5686) The name of @dfn{begin} function. This function
is called before
+../tar_texi/tar.texi(,5687) accessing the drive. By default it retensions the
tape:
+../tar_texi/tar.texi(,5688)
+../tar_texi/tar.texi(,5689) @smallexample
+../tar_texi/tar.texi(,5690) MT_BEGIN=mt_begin
+../tar_texi/tar.texi(,5691)
+../tar_texi/tar.texi(,5692) mt_begin() @{
+../tar_texi/tar.texi(,5693) mt -f "$1" retension
+../tar_texi/tar.texi(,5694) @}
+../tar_texi/tar.texi(,5695) @end smallexample
+../tar_texi/tar.texi(,5696) @end defvr
+../tar_texi/tar.texi(,5697)
+../tar_texi/tar.texi(,5698) @defvr {Backup variable} MT_REWIND
+../tar_texi/tar.texi(,5699) The name of @dfn{rewind} function. The default
definition is as
+../tar_texi/tar.texi(,5700) follows:
+../tar_texi/tar.texi(,5701)
+../tar_texi/tar.texi(,5702) @smallexample
+../tar_texi/tar.texi(,5703) MT_REWIND=mt_rewind
+../tar_texi/tar.texi(,5704)
+../tar_texi/tar.texi(,5705) mt_rewind() @{
+../tar_texi/tar.texi(,5706) mt -f "$1" rewind
+../tar_texi/tar.texi(,5707) @}
+../tar_texi/tar.texi(,5708) @end smallexample
+../tar_texi/tar.texi(,5709)
+../tar_texi/tar.texi(,5710) @end defvr
+../tar_texi/tar.texi(,5711)
+../tar_texi/tar.texi(,5712) @defvr {Backup variable} MT_OFFLINE
+../tar_texi/tar.texi(,5713) The name of the function switching the tape off
line. By default
+../tar_texi/tar.texi(,5714) it is defined as follows:
+../tar_texi/tar.texi(,5715)
+../tar_texi/tar.texi(,5716) @smallexample
+../tar_texi/tar.texi(,5717) MT_OFFLINE=mt_offline
+../tar_texi/tar.texi(,5718)
+../tar_texi/tar.texi(,5719) mt_offline() @{
+../tar_texi/tar.texi(,5720) mt -f "$1" offl
+../tar_texi/tar.texi(,5721) @}
+../tar_texi/tar.texi(,5722) @end smallexample
+../tar_texi/tar.texi(,5723) @end defvr
+../tar_texi/tar.texi(,5724)
+../tar_texi/tar.texi(,5725) @defvr {Backup variable} MT_STATUS
+../tar_texi/tar.texi(,5726) The name of the function used to obtain the status
of the archive device,
+../tar_texi/tar.texi(,5727) including error count. Default definition:
+../tar_texi/tar.texi(,5728)
+../tar_texi/tar.texi(,5729) @smallexample
+../tar_texi/tar.texi(,5730) MT_STATUS=mt_status
+../tar_texi/tar.texi(,5731)
+../tar_texi/tar.texi(,5732) mt_status() @{
+../tar_texi/tar.texi(,5733) mt -f "$1" status
+../tar_texi/tar.texi(,5734) @}
+../tar_texi/tar.texi(,5735) @end smallexample
+../tar_texi/tar.texi(,5736) @end defvr
+../tar_texi/tar.texi(,5737)
+../tar_texi/tar.texi(,5738) @node User Hooks
+../tar_texi/tar.texi(,5739) @subsection User Hooks
+../tar_texi/tar.texi(,5740)
+../tar_texi/tar.texi(,5741) @dfn{User hooks} are shell functions executed
before and after
+../tar_texi/tar.texi(,5742) each @command{tar} invocation. Thus, there are
@dfn{backup
+../tar_texi/tar.texi(,5743) hooks}, which are executed before and after
dumping each file
+../tar_texi/tar.texi(,5744) system, and @dfn{restore hooks}, executed before
and
+../tar_texi/tar.texi(,5745) after restoring a file system. Each user hook is
a shell function
+../tar_texi/tar.texi(,5746) taking four arguments:
+../tar_texi/tar.texi(,5747)
+../tar_texi/tar.texi(,5748) @deffn {User Hook Function} hook @var{level}
@var{host} @var{fs} @var{fsname}
+../tar_texi/tar.texi(,5749) Its arguments are:
+../tar_texi/tar.texi(,5750)
+../tar_texi/tar.texi(,5751) @table @var
+../tar_texi/tar.texi(,5752) @item level
+../tar_texi/tar.texi(,5753) Current backup or restore level.
+../tar_texi/tar.texi(,5754)
+../tar_texi/tar.texi(,5755) @item host
+../tar_texi/tar.texi(,5756) Name or IP address of the host machine being
dumped or restored.
+../tar_texi/tar.texi(,5757)
+../tar_texi/tar.texi(,5758) @item fs
+../tar_texi/tar.texi(,5759) Full path name to the file system being dumped or
restored.
+../tar_texi/tar.texi(,5760)
+../tar_texi/tar.texi(,5761) @item fsname
+../tar_texi/tar.texi(,5762) File system name with directory separators
replaced with colons. This
+../tar_texi/tar.texi(,5763) is useful, e.g., for creating unique files.
+../tar_texi/tar.texi(,5764) @end table
+../tar_texi/tar.texi(,5765) @end deffn
+../tar_texi/tar.texi(,5766)
+../tar_texi/tar.texi(,5767) Following variables keep the names of user hook
functions
+../tar_texi/tar.texi(,5768)
+../tar_texi/tar.texi(,5769) @defvr {Backup variable} DUMP_BEGIN
+../tar_texi/tar.texi(,5770) Dump begin function. It is executed before
dumping the file system.
+../tar_texi/tar.texi(,5771) @end defvr
+../tar_texi/tar.texi(,5772)
+../tar_texi/tar.texi(,5773) @defvr {Backup variable} DUMP_END
+../tar_texi/tar.texi(,5774) Executed after dumping the file system.
+../tar_texi/tar.texi(,5775) @end defvr
+../tar_texi/tar.texi(,5776)
+../tar_texi/tar.texi(,5777) @defvr {Backup variable} RESTORE_BEGIN
+../tar_texi/tar.texi(,5778) Executed before restoring the file system.
+../tar_texi/tar.texi(,5779) @end defvr
+../tar_texi/tar.texi(,5780)
+../tar_texi/tar.texi(,5781) @defvr {Backup variable} RESTORE_END
+../tar_texi/tar.texi(,5782) Executed after restoring the file system.
+../tar_texi/tar.texi(,5783) @end defvr
+../tar_texi/tar.texi(,5784)
+../tar_texi/tar.texi(,5785) @node backup-specs example
+../tar_texi/tar.texi(,5786) @subsection An Example Text of @file{Backup-specs}
+../tar_texi/tar.texi(,5787)
+../tar_texi/tar.texi(,5788) The following is an example of @file{backup-specs}:
+../tar_texi/tar.texi(,5789)
+../tar_texi/tar.texi(,5790) @smallexample
+../tar_texi/tar.texi(,5791) # site-specific parameters for file system backup.
+../tar_texi/tar.texi(,5792)
+../tar_texi/tar.texi(,5793) ADMINISTRATOR=friedman
+../tar_texi/tar.texi(,5794) BACKUP_HOUR=1
+../tar_texi/tar.texi(,5795) TAPE_FILE=/dev/nrsmt0
+../tar_texi/tar.texi(,5796)
+../tar_texi/tar.texi(,5797) # Use @code{ssh} instead of the less secure
@code{rsh}
+../tar_texi/tar.texi(,5798) RSH=/usr/bin/ssh
+../tar_texi/tar.texi(,5799) RSH_COMMAND=/usr/bin/ssh
+../tar_texi/tar.texi(,5800)
+../tar_texi/tar.texi(,5801) # Override MT_STATUS function:
+../tar_texi/tar.texi(,5802) my_status() @{
+../tar_texi/tar.texi(,5803) mts -t $TAPE_FILE
+../tar_texi/tar.texi(,5804) @}
+../tar_texi/tar.texi(,5805) MT_STATUS=my_status
+../tar_texi/tar.texi(,5806)
+../tar_texi/tar.texi(,5807) # Disable MT_OFFLINE function
+../tar_texi/tar.texi(,5808) MT_OFFLINE=:
+../tar_texi/tar.texi(,5809)
+../tar_texi/tar.texi(,5810) BLOCKING=124
+../tar_texi/tar.texi(,5811) BACKUP_DIRS="
+../tar_texi/tar.texi(,5812) albert:/fs/fsf
+../tar_texi/tar.texi(,5813) apple-gunkies:/gd
+../tar_texi/tar.texi(,5814) albert:/fs/gd2
+../tar_texi/tar.texi(,5815) albert:/fs/gp
+../tar_texi/tar.texi(,5816) geech:/usr/jla
+../tar_texi/tar.texi(,5817) churchy:/usr/roland
+../tar_texi/tar.texi(,5818) albert:/
+../tar_texi/tar.texi(,5819) albert:/usr
+../tar_texi/tar.texi(,5820) apple-gunkies:/
+../tar_texi/tar.texi(,5821) apple-gunkies:/usr
+../tar_texi/tar.texi(,5822) gnu:/hack
+../tar_texi/tar.texi(,5823) gnu:/u
+../tar_texi/tar.texi(,5824) apple-gunkies:/com/mailer/gnu
+../tar_texi/tar.texi(,5825) apple-gunkies:/com/archive/gnu"
+../tar_texi/tar.texi(,5826)
+../tar_texi/tar.texi(,5827) BACKUP_FILES="/com/mailer/aliases
/com/mailer/league*[a-z]"
+../tar_texi/tar.texi(,5828)
+../tar_texi/tar.texi(,5829) @end smallexample
+../tar_texi/tar.texi(,5830)
+../tar_texi/tar.texi(,5831) @node Scripted Backups
+../tar_texi/tar.texi(,5832) @section Using the Backup Scripts
+../tar_texi/tar.texi(,5833)
+../tar_texi/tar.texi(,5834) The syntax for running a backup script is:
+../tar_texi/tar.texi(,5835)
+../tar_texi/tar.texi(,5836) @smallexample
+../tar_texi/tar.texi(,5837) backup address@hidden address@hidden
+../tar_texi/tar.texi(,5838) @end smallexample
+../tar_texi/tar.texi(,5839)
+../tar_texi/tar.texi(,5840) The @option{level} option requests the dump level.
Thus, to produce
+../tar_texi/tar.texi(,5841) a full dump, specify @code{--level=0} (this is the
default, so
+../tar_texi/tar.texi(,5842) @option{--level} may be omitted if its value is
@code{0}).
+../tar_texi/tar.texi(,5843) @footnote{For backward compatibility, the
@code{backup} will also
+../tar_texi/tar.texi(,5844) try to deduce the requested dump level from the
name of the
+../tar_texi/tar.texi(,5845) script itself. If the name consists of a string
@samp{level-}
+../tar_texi/tar.texi(,5846) followed by a single decimal digit, that digit is
taken as
+../tar_texi/tar.texi(,5847) the dump level number. Thus, you may create a
link from @code{backup}
+../tar_texi/tar.texi(,5848) to @code{level-1} and then run @code{level-1}
whenever you need to
+../tar_texi/tar.texi(,5849) create a level one dump.}
+../tar_texi/tar.texi(,5850)
+../tar_texi/tar.texi(,5851) The @option{--time} option determines when should
the backup be
+../tar_texi/tar.texi(,5852) run. @var{Time} may take three forms:
+../tar_texi/tar.texi(,5853)
+../tar_texi/tar.texi(,5854) @table @asis
+../tar_texi/tar.texi(,5855) @item @var{hh}:@var{mm}
+../tar_texi/tar.texi(,5856)
+../tar_texi/tar.texi(,5857) The dump must be run at @var{hh} hours @var{mm}
minutes.
+../tar_texi/tar.texi(,5858)
+../tar_texi/tar.texi(,5859) @item @var{hh}
+../tar_texi/tar.texi(,5860)
+../tar_texi/tar.texi(,5861) The dump must be run at @var{hh} hours
+../tar_texi/tar.texi(,5862)
+../tar_texi/tar.texi(,5863) @item now
+../tar_texi/tar.texi(,5864)
+../tar_texi/tar.texi(,5865) The dump must be run immediately.
+../tar_texi/tar.texi(,5866) @end table
+../tar_texi/tar.texi(,5867)
+../tar_texi/tar.texi(,5868) You should start a script with a tape or disk
mounted. Once you
+../tar_texi/tar.texi(,5869) start a script, it prompts you for new tapes or
disks as it
+../tar_texi/tar.texi(,5870) needs them. Media volumes don't have to
correspond to archive
+../tar_texi/tar.texi(,5871) files --- a multi-volume archive can be started in
the middle of a
+../tar_texi/tar.texi(,5872) tape that already contains the end of another
multi-volume archive.
+../tar_texi/tar.texi(,5873) The @code{restore} script prompts for media by its
archive volume,
+../tar_texi/tar.texi(,5874) so to avoid an error message you should keep track
of which tape
+../tar_texi/tar.texi(,5875) (or disk) contains which volume of the archive
(@pxref{Scripted
+../tar_texi/tar.texi(,5876) Restoration}).
+../tar_texi/tar.texi(,5877)
+../tar_texi/tar.texi(,5878) The backup scripts write two files on the file
system. The first is a
+../tar_texi/tar.texi(,5879) record file in @file{/etc/tar-backup/}, which is
used by the scripts
+../tar_texi/tar.texi(,5880) to store and retrieve information about which
files were dumped. This
+../tar_texi/tar.texi(,5881) file is not meant to be read by humans, and should
not be deleted by
+../tar_texi/tar.texi(,5882) them. @xref{Snapshot Files}, for a more detailed
explanation of this
+../tar_texi/tar.texi(,5883) file.
+../tar_texi/tar.texi(,5884)
+../tar_texi/tar.texi(,5885) The second file is a log file containing the names
of the file systems
+../tar_texi/tar.texi(,5886) and files dumped, what time the backup was made,
and any error
+../tar_texi/tar.texi(,5887) messages that were generated, as well as how much
space was left in
+../tar_texi/tar.texi(,5888) the media volume after the last volume of the
archive was written.
+../tar_texi/tar.texi(,5889) You should check this log file after every backup.
The file name is
+../tar_texi/tar.texi(,5890) @address@hidden@var{n}}, where @var{mm-dd-yyyy}
+../tar_texi/tar.texi(,5891) represents current date, and @var{n} represents
current dump level number.
+../tar_texi/tar.texi(,5892)
+../tar_texi/tar.texi(,5893) The script also prints the name of each system
being dumped to the
+../tar_texi/tar.texi(,5894) standard output.
+../tar_texi/tar.texi(,5895)
+../tar_texi/tar.texi(,5896) Following is the full list of options accepted by
@code{backup}
+../tar_texi/tar.texi(,5897) script:
+../tar_texi/tar.texi(,5898)
+../tar_texi/tar.texi(,5899) @table @option
+../tar_texi/tar.texi(,5900) @item -l @var{level}
+../tar_texi/tar.texi(,5901) @itemx address@hidden
+../tar_texi/tar.texi(,5902) Do backup level @var{level} (default 0).
+../tar_texi/tar.texi(,5903)
+../tar_texi/tar.texi(,5904) @item -f
+../tar_texi/tar.texi(,5905) @itemx --force
+../tar_texi/tar.texi(,5906) Force backup even if today's log file already
exists.
+../tar_texi/tar.texi(,5907)
+../tar_texi/tar.texi(,5908) @item address@hidden
+../tar_texi/tar.texi(,5909) @itemx address@hidden
+../tar_texi/tar.texi(,5910) Set verbosity level. The higher the level is, the
more debugging
+../tar_texi/tar.texi(,5911) information will be output during execution.
Devault @var{level}
+../tar_texi/tar.texi(,5912) is 100, which means the highest debugging level.
+../tar_texi/tar.texi(,5913)
+../tar_texi/tar.texi(,5914) @item -t @var{start-time}
+../tar_texi/tar.texi(,5915) @itemx address@hidden
+../tar_texi/tar.texi(,5916) Wait till @var{time}, then do backup.
+../tar_texi/tar.texi(,5917)
+../tar_texi/tar.texi(,5918) @item -h
+../tar_texi/tar.texi(,5919) @itemx --help
+../tar_texi/tar.texi(,5920) Display short help message and exit.
+../tar_texi/tar.texi(,5921)
+../tar_texi/tar.texi(,5922) @item -V
+../tar_texi/tar.texi(,5923) @itemx --version
+../tar_texi/tar.texi(,5924) Display information about the program's name,
version, origin and legal
+../tar_texi/tar.texi(,5925) status, all on standard output, and then exit
successfully.
+../tar_texi/tar.texi(,5926) @end table
+../tar_texi/tar.texi(,5927)
+../tar_texi/tar.texi(,5928)
+../tar_texi/tar.texi(,5929) @node Scripted Restoration
+../tar_texi/tar.texi(,5930) @section Using the Restore Script
+../tar_texi/tar.texi(,5931)
+../tar_texi/tar.texi(,5932) To restore files that were archived using a
scripted backup, use the
+../tar_texi/tar.texi(,5933) @code{restore} script. Its usage is quite
straightforward. In the
+../tar_texi/tar.texi(,5934) simplest form, invoke @code{restore --all}, it will
+../tar_texi/tar.texi(,5935) then restore all the file systems and files
specified in
+../tar_texi/tar.texi(,5936) @file{backup-specs} (@pxref{General-Purpose
Variables,BACKUP_DIRS}).
+../tar_texi/tar.texi(,5937)
+../tar_texi/tar.texi(,5938) You may select the file systems (and/or files) to
restore by
+../tar_texi/tar.texi(,5939) giving @code{restore} list of @dfn{patterns} in
its command
+../tar_texi/tar.texi(,5940) line. For example, running
+../tar_texi/tar.texi(,5941)
+../tar_texi/tar.texi(,5942) @smallexample
+../tar_texi/tar.texi(,5943) restore 'albert:*'
+../tar_texi/tar.texi(,5944) @end smallexample
+../tar_texi/tar.texi(,5945)
+../tar_texi/tar.texi(,5946) @noindent
+../tar_texi/tar.texi(,5947) will restore all file systems on the machine
@samp{albert}. A more
+../tar_texi/tar.texi(,5948) complicated example:
+../tar_texi/tar.texi(,5949)
+../tar_texi/tar.texi(,5950) @smallexample
+../tar_texi/tar.texi(,5951) restore 'albert:*' '*:/var'
+../tar_texi/tar.texi(,5952) @end smallexample
+../tar_texi/tar.texi(,5953)
+../tar_texi/tar.texi(,5954) @noindent
+../tar_texi/tar.texi(,5955) This command will restore all file systems on the
machine @samp{albert}
+../tar_texi/tar.texi(,5956) as well as @file{/var} file system on all machines.
+../tar_texi/tar.texi(,5957)
+../tar_texi/tar.texi(,5958) By default @code{restore} will start restoring
files from the lowest
+../tar_texi/tar.texi(,5959) available dump level (usually zero) and will
continue through
+../tar_texi/tar.texi(,5960) all available dump levels. There may be
situations where such a
+../tar_texi/tar.texi(,5961) thorough restore is not necessary. For example,
you may wish to
+../tar_texi/tar.texi(,5962) restore only files from the recent level one
backup. To do so,
+../tar_texi/tar.texi(,5963) use @option{--level} option, as shown in the
example below:
+../tar_texi/tar.texi(,5964)
+../tar_texi/tar.texi(,5965) @smallexample
+../tar_texi/tar.texi(,5966) restore --level=1
+../tar_texi/tar.texi(,5967) @end smallexample
+../tar_texi/tar.texi(,5968)
+../tar_texi/tar.texi(,5969) The full list of options accepted by
@code{restore} follows:
+../tar_texi/tar.texi(,5970)
+../tar_texi/tar.texi(,5971) @table @option
+../tar_texi/tar.texi(,5972) @item -a
+../tar_texi/tar.texi(,5973) @itemx --all
+../tar_texi/tar.texi(,5974) Restore all file systems and files specified in
@file{backup-specs}
+../tar_texi/tar.texi(,5975)
+../tar_texi/tar.texi(,5976) @item -l @var{level}
+../tar_texi/tar.texi(,5977) @itemx address@hidden
+../tar_texi/tar.texi(,5978) Start restoring from the given backup level,
instead of the default 0.
+../tar_texi/tar.texi(,5979)
+../tar_texi/tar.texi(,5980) @item address@hidden
+../tar_texi/tar.texi(,5981) @itemx address@hidden
+../tar_texi/tar.texi(,5982) Set verbosity level. The higher the level is, the
more debugging
+../tar_texi/tar.texi(,5983) information will be output during execution.
Devault @var{level}
+../tar_texi/tar.texi(,5984) is 100, which means the highest debugging level.
+../tar_texi/tar.texi(,5985)
+../tar_texi/tar.texi(,5986) @item -h
+../tar_texi/tar.texi(,5987) @itemx --help
+../tar_texi/tar.texi(,5988) Display short help message and exit.
+../tar_texi/tar.texi(,5989)
+../tar_texi/tar.texi(,5990) @item -V
+../tar_texi/tar.texi(,5991) @itemx --version
+../tar_texi/tar.texi(,5992) Display information about the program's name,
version, origin and legal
+../tar_texi/tar.texi(,5993) status, all on standard output, and then exit
successfully.
+../tar_texi/tar.texi(,5994) @end table
+../tar_texi/tar.texi(,5995)
+../tar_texi/tar.texi(,5996) You should start the restore script with the media
containing the
+../tar_texi/tar.texi(,5997) first volume of the archive mounted. The script
will prompt for other
+../tar_texi/tar.texi(,5998) volumes as they are needed. If the archive is on
tape, you don't need
+../tar_texi/tar.texi(,5999) to rewind the tape to to its beginning---if the
tape head is
+../tar_texi/tar.texi(,6000) positioned past the beginning of the archive, the
script will rewind
+../tar_texi/tar.texi(,6001) the tape as needed. @xref{Tape Positioning}, for
a discussion of tape
+../tar_texi/tar.texi(,6002) positioning.
+../tar_texi/tar.texi(,6003)
+../tar_texi/tar.texi(,6004) @quotation
+../tar_texi/tar.texi(,6005) @strong{Warning:} The script will delete files
from the active file
+../tar_texi/tar.texi(,6006) system if they were not in the file system when
the archive was made.
+../tar_texi/tar.texi(,6007) @end quotation
+../tar_texi/tar.texi(,6008)
+../tar_texi/tar.texi(,6009) @xref{Incremental Dumps}, for an explanation of
how the script makes
+../tar_texi/tar.texi(,6010) that determination.
+../tar_texi/tar.texi(,6011)
+../tar_texi/tar.texi(,6012) @node Choosing
+../tar_texi/tar.texi(,6013) @chapter Choosing Files and Names for @command{tar}
+../tar_texi/tar.texi(UNREVISED,6014) @quotation
+../tar_texi/tar.texi(UNREVISED,6014) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,6014) @end quotation
+../tar_texi/tar.texi(UNREVISED,6014)
+../tar_texi/tar.texi(,6015)
+../tar_texi/tar.texi(,6016) Certain options to @command{tar} enable you to
specify a name for your
+../tar_texi/tar.texi(,6017) archive. Other options let you decide which files
to include or exclude
+../tar_texi/tar.texi(,6018) from the archive, based on when or whether files
were modified, whether
+../tar_texi/tar.texi(,6019) the file names do or don't match specified
patterns, or whether files
+../tar_texi/tar.texi(,6020) are in specified directories.
+../tar_texi/tar.texi(,6021)
+../tar_texi/tar.texi(,6022) This chapter discusses these options in detail.
+../tar_texi/tar.texi(,6023)
+../tar_texi/tar.texi(,6024) @menu
+../tar_texi/tar.texi(,6025) * file:: Choosing the
Archive's Name
+../tar_texi/tar.texi(,6026) * Selecting Archive Members::
+../tar_texi/tar.texi(,6027) * files:: Reading Names from
a File
+../tar_texi/tar.texi(,6028) * exclude:: Excluding Some
Files
+../tar_texi/tar.texi(,6029) * wildcards:: Wildcards Patterns
and Matching
+../tar_texi/tar.texi(,6030) * quoting styles:: Ways of Quoting
Special Characters in Names
+../tar_texi/tar.texi(,6031) * transform:: Modifying File and
Member Names
+../tar_texi/tar.texi(,6032) * after:: Operating Only on
New Files
+../tar_texi/tar.texi(,6033) * recurse:: Descending into
Directories
+../tar_texi/tar.texi(,6034) * one:: Crossing File
System Boundaries
+../tar_texi/tar.texi(,6035) @end menu
+../tar_texi/tar.texi(,6036)
+../tar_texi/tar.texi(,6037) @node file
+../tar_texi/tar.texi(,6038) @section Choosing and Naming Archive Files
+../tar_texi/tar.texi(UNREVISED,6039) @quotation
+../tar_texi/tar.texi(UNREVISED,6039) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,6039) @end quotation
+../tar_texi/tar.texi(UNREVISED,6039)
+../tar_texi/tar.texi(,6040)
+../tar_texi/tar.texi(,6041) @cindex Naming an archive
+../tar_texi/tar.texi(,6042) @cindex Archive Name
+../tar_texi/tar.texi(,6043) @cindex Choosing an archive file
+../tar_texi/tar.texi(,6044) @cindex Where is the archive?
+../tar_texi/tar.texi(,6045) By default, @command{tar} uses an archive file
name that was compiled when
+../tar_texi/tar.texi(,6046) it was built on the system; usually this name
refers to some physical
+../tar_texi/tar.texi(,6047) tape drive on the machine. However, the person
who installed @command{tar}
+../tar_texi/tar.texi(,6048) on the system may not have set the default to a
meaningful value as far as
+../tar_texi/tar.texi(,6049) most users are concerned. As a result, you will
usually want to tell
+../tar_texi/tar.texi(,6050) @command{tar} where to find (or create) the
archive. The
+../tar_texi/tar.texi(,6051) @address@hidden (@option{-f @var{archive-name}})
+../tar_texi/tar.texi(,6052) option allows you to either specify or name a file
to use as the archive
+../tar_texi/tar.texi(,6053) instead of the default archive file location.
+../tar_texi/tar.texi(,6054)
+../tar_texi/tar.texi(,6055) @table @option
+../tar_texi/tar.texi(xopindex,6056) @opindex address@hidden, short description}
+../tar_texi/tar.texi(,6057) @item address@hidden
+../tar_texi/tar.texi(,6058) @itemx -f @var{archive-name}
+../tar_texi/tar.texi(,6059) Name the archive to create or operate on. Use in
conjunction with
+../tar_texi/tar.texi(,6060) any operation.
+../tar_texi/tar.texi(,6061) @end table
+../tar_texi/tar.texi(,6062)
+../tar_texi/tar.texi(,6063) For example, in this @command{tar} command,
+../tar_texi/tar.texi(,6064)
+../tar_texi/tar.texi(,6065) @smallexample
+../tar_texi/tar.texi(,6066) $ @kbd{tar -cvf collection.tar blues folk jazz}
+../tar_texi/tar.texi(,6067) @end smallexample
+../tar_texi/tar.texi(,6068)
+../tar_texi/tar.texi(,6069) @noindent
+../tar_texi/tar.texi(,6070) @file{collection.tar} is the name of the archive.
It must directly
+../tar_texi/tar.texi(,6071) follow the @option{-f} option, since whatever
directly follows @option{-f}
+../tar_texi/tar.texi(,6072) @emph{will} end up naming the archive. If you
neglect to specify an
+../tar_texi/tar.texi(,6073) archive name, you may end up overwriting a file in
the working directory
+../tar_texi/tar.texi(,6074) with the archive you create since @command{tar}
will use this file's name
+../tar_texi/tar.texi(,6075) for the archive name.
+../tar_texi/tar.texi(,6076)
+../tar_texi/tar.texi(,6077) An archive can be saved as a file in the file
system, sent through a
+../tar_texi/tar.texi(,6078) pipe or over a network, or written to an I/O
device such as a tape,
+../tar_texi/tar.texi(,6079) floppy disk, or CD write drive.
+../tar_texi/tar.texi(,6080)
+../tar_texi/tar.texi(,6081) @cindex Writing new archives
+../tar_texi/tar.texi(,6082) @cindex Archive creation
+../tar_texi/tar.texi(,6083) If you do not name the archive, @command{tar} uses
the value of the
+../tar_texi/tar.texi(,6084) environment variable @env{TAPE} as the file name
for the archive. If
+../tar_texi/tar.texi(,6085) that is not available, @command{tar} uses a
default, compiled-in archive
+../tar_texi/tar.texi(,6086) name, usually that for tape unit zero (i.e.
@file{/dev/tu00}).
+../tar_texi/tar.texi(,6087)
+../tar_texi/tar.texi(,6088) @cindex Standard input and output
+../tar_texi/tar.texi(,6089) @cindex tar to standard input and output
+../tar_texi/tar.texi(,6090) If you use @file{-} as an @var{archive-name},
@command{tar} reads the
+../tar_texi/tar.texi(,6091) archive from standard input (when listing or
extracting files), or
+../tar_texi/tar.texi(,6092) writes it to standard output (when creating an
archive). If you use
+../tar_texi/tar.texi(,6093) @file{-} as an @var{archive-name} when modifying
an archive,
+../tar_texi/tar.texi(,6094) @command{tar} reads the original archive from its
standard input and
+../tar_texi/tar.texi(,6095) writes the entire new archive to its standard
output.
+../tar_texi/tar.texi(,6096)
+../tar_texi/tar.texi(,6097) The following example is a convenient way of
copying directory
+../tar_texi/tar.texi(,6098) hierarchy from @file{sourcedir} to
@file{targetdir}.
+../tar_texi/tar.texi(,6099)
+../tar_texi/tar.texi(,6100) @smallexample
+../tar_texi/tar.texi(,6101) $ @kbd{(cd sourcedir; tar -cf - .) | (cd
targetdir; tar -xpf -)}
+../tar_texi/tar.texi(,6102) @end smallexample
+../tar_texi/tar.texi(,6103)
+../tar_texi/tar.texi(,6104) The @option{-C} option allows to avoid using
subshells:
+../tar_texi/tar.texi(,6105)
+../tar_texi/tar.texi(,6106) @smallexample
+../tar_texi/tar.texi(,6107) $ @kbd{tar -C sourcedir -cf - . | tar -C targetdir
-xpf -}
+../tar_texi/tar.texi(,6108) @end smallexample
+../tar_texi/tar.texi(,6109)
+../tar_texi/tar.texi(,6110) In both examples above, the leftmost @command{tar}
invocation archives
+../tar_texi/tar.texi(,6111) the contents of @file{sourcedir} to the standard
output, while the
+../tar_texi/tar.texi(,6112) rightmost one reads this archive from its standard
input and
+../tar_texi/tar.texi(,6113) extracts it. The @option{-p} option tells it to
restore permissions
+../tar_texi/tar.texi(,6114) of the extracted files.
+../tar_texi/tar.texi(,6115)
+../tar_texi/tar.texi(,6116) @cindex Remote devices
+../tar_texi/tar.texi(,6117) @cindex tar to a remote device
+../tar_texi/tar.texi(,6118) @anchor{remote-dev}
+../tar_texi/tar.texi(,6119) To specify an archive file on a device attached to
a remote machine,
+../tar_texi/tar.texi(,6120) use the following:
+../tar_texi/tar.texi(,6121)
+../tar_texi/tar.texi(,6122) @smallexample
+../tar_texi/tar.texi(,6123) @address@hidden:/@var{dev}/@var{file-name}}
+../tar_texi/tar.texi(,6124) @end smallexample
+../tar_texi/tar.texi(,6125)
+../tar_texi/tar.texi(,6126) @noindent
+../tar_texi/tar.texi(,6127) @command{tar} will complete the remote connection,
if possible, and
+../tar_texi/tar.texi(,6128) prompt you for a username and password. If you use
+../tar_texi/tar.texi(,6129)
@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
+../tar_texi/tar.texi(,6130) will complete the remote connection, if possible,
using your username
+../tar_texi/tar.texi(,6131) as the username on the remote machine.
+../tar_texi/tar.texi(,6132)
+../tar_texi/tar.texi(,6133) @cindex Local and remote archives
+../tar_texi/tar.texi(,6134) @anchor{local and remote archives}
+../tar_texi/tar.texi(,6135) If the archive file name includes a colon
(@samp{:}), then it is assumed
+../tar_texi/tar.texi(,6136) to be a file on another machine. If the archive
file is
+../tar_texi/tar.texi(,6137) @address@hidden@@@var{host}:@var{file}}, then
@var{file} is used on the
+../tar_texi/tar.texi(,6138) host @var{host}. The remote host is accessed
using the @command{rsh}
+../tar_texi/tar.texi(,6139) program, with a username of @var{user}. If the
username is omitted
+../tar_texi/tar.texi(,6140) (along with the @samp{@@} sign), then your user
name will be used.
+../tar_texi/tar.texi(,6141) (This is the normal @command{rsh} behavior.) It
is necessary for the
+../tar_texi/tar.texi(,6142) remote machine, in addition to permitting your
@command{rsh} access, to
+../tar_texi/tar.texi(,6143) have the @file{rmt} program installed (This
command is included in
+../tar_texi/tar.texi(GNUTAR,6144) the @acronym{GNU} @command{tar} distribution
and by default is installed under
+../tar_texi/tar.texi(,6145) @address@hidden/libexec/rmt}, were @var{prefix}
means your
+../tar_texi/tar.texi(,6146) installation prefix). If you need to use a file
whose name includes a
+../tar_texi/tar.texi(,6147) colon, then the remote tape drive behavior
+../tar_texi/tar.texi(,6148) can be inhibited by using the
@option{--force-local} option.
+../tar_texi/tar.texi(,6149)
+../tar_texi/tar.texi(GNUTAR,6150) When the archive is being created to
@file{/dev/null}, @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,6151) tries to minimize input and output operations.
The Amanda backup
+../tar_texi/tar.texi(GNUTAR,6152) system, when used with @acronym{GNU}
@command{tar}, has an initial sizing pass which
+../tar_texi/tar.texi(,6153) uses this feature.
+../tar_texi/tar.texi(,6154)
+../tar_texi/tar.texi(,6155) @node Selecting Archive Members
+../tar_texi/tar.texi(,6156) @section Selecting Archive Members
+../tar_texi/tar.texi(,6157) @cindex Specifying files to act on
+../tar_texi/tar.texi(,6158) @cindex Specifying archive members
+../tar_texi/tar.texi(,6159)
+../tar_texi/tar.texi(,6160) @dfn{File Name arguments} specify which files in
the file system
+../tar_texi/tar.texi(,6161) @command{tar} operates on, when creating or adding
to an archive, or which
+../tar_texi/tar.texi(,6162) archive members @command{tar} operates on, when
reading or deleting from
+../tar_texi/tar.texi(,6163) an archive. @xref{Operations}.
+../tar_texi/tar.texi(,6164)
+../tar_texi/tar.texi(,6165) To specify file names, you can include them as the
last arguments on
+../tar_texi/tar.texi(,6166) the command line, as follows:
+../tar_texi/tar.texi(,6167) @smallexample
+../tar_texi/tar.texi(,6168) @kbd{tar} @var{operation} address@hidden
@var{option2} @dots{}] address@hidden name-1} @var{file name-2} @dots{}]
+../tar_texi/tar.texi(,6169) @end smallexample
+../tar_texi/tar.texi(,6170)
+../tar_texi/tar.texi(,6171) If a file name begins with dash (@samp{-}),
precede it with
+../tar_texi/tar.texi(,6172) @option{--add-file} option to prevent it from
being treated as an
+../tar_texi/tar.texi(,6173) option.
+../tar_texi/tar.texi(,6174)
+../tar_texi/tar.texi(,6175) @anchor{input name quoting}
+../tar_texi/tar.texi(GNUTAR,6176) By default @acronym{GNU} @command{tar}
attempts to @dfn{unquote} each file or member
+../tar_texi/tar.texi(,6177) name, replacing @dfn{escape sequences} according
to the following
+../tar_texi/tar.texi(,6178) table:
+../tar_texi/tar.texi(,6179)
+../tar_texi/tar.texi(,6180) @multitable @columnfractions 0.20 0.60
+../tar_texi/tar.texi(,6181) @headitem Escape @tab Replaced with
+../tar_texi/tar.texi(,6182) @item \a @tab Audible bell (ASCII 7)
+../tar_texi/tar.texi(,6183) @item \b @tab Backspace (ASCII 8)
+../tar_texi/tar.texi(,6184) @item \f @tab Form feed (ASCII 12)
+../tar_texi/tar.texi(,6185) @item \n @tab New line (ASCII 10)
+../tar_texi/tar.texi(,6186) @item \r @tab Carriage return (ASCII 13)
+../tar_texi/tar.texi(,6187) @item \t @tab Horizontal tabulation (ASCII
9)
+../tar_texi/tar.texi(,6188) @item \v @tab Vertical tabulation (ASCII
11)
+../tar_texi/tar.texi(,6189) @item \? @tab ASCII 127
+../tar_texi/tar.texi(,6190) @item address@hidden @tab ASCII @var{n} (@var{n}
should be an octal number
+../tar_texi/tar.texi(,6191) of up to 3 digits)
+../tar_texi/tar.texi(,6192) @end multitable
+../tar_texi/tar.texi(,6193)
+../tar_texi/tar.texi(,6194) A backslash followed by any other symbol is
retained.
+../tar_texi/tar.texi(,6195)
+../tar_texi/tar.texi(,6196) This default behavior is controlled by the
following command line
+../tar_texi/tar.texi(,6197) option:
+../tar_texi/tar.texi(,6198)
+../tar_texi/tar.texi(,6199) @table @option
+../tar_texi/tar.texi(,6200) @opindex unquote
+../tar_texi/tar.texi(,6201) @item --unquote
+../tar_texi/tar.texi(,6202) Enable unquoting input file or member names
(default).
+../tar_texi/tar.texi(,6203)
+../tar_texi/tar.texi(,6204) @opindex no-unquote
+../tar_texi/tar.texi(,6205) @item --no-unquote
+../tar_texi/tar.texi(,6206) Disable unquoting input file or member names.
+../tar_texi/tar.texi(,6207) @end table
+../tar_texi/tar.texi(,6208)
+../tar_texi/tar.texi(,6209) If you specify a directory name as a file name
argument, all the files
+../tar_texi/tar.texi(,6210) in that directory are operated on by @command{tar}.
+../tar_texi/tar.texi(,6211)
+../tar_texi/tar.texi(,6212) If you do not specify files, @command{tar}
behavior differs depending
+../tar_texi/tar.texi(,6213) on the operation mode as described below:
+../tar_texi/tar.texi(,6214)
+../tar_texi/tar.texi(,6215) When @command{tar} is invoked with
@option{--create} (@option{-c}),
+../tar_texi/tar.texi(,6216) @command{tar} will stop immediately, reporting the
following:
+../tar_texi/tar.texi(,6217)
+../tar_texi/tar.texi(,6218) @smallexample
+../tar_texi/tar.texi(,6219) @group
+../tar_texi/tar.texi(,6220) $ @kbd{tar cf a.tar}
+../tar_texi/tar.texi(,6221) tar: Cowardly refusing to create an empty archive
+../tar_texi/tar.texi(,6222) Try `tar --help' or `tar --usage' for more
information.
+../tar_texi/tar.texi(,6223) @end group
+../tar_texi/tar.texi(,6224) @end smallexample
+../tar_texi/tar.texi(,6225)
+../tar_texi/tar.texi(,6226) If you specify either @option{--list}
(@option{-t}) or
+../tar_texi/tar.texi(,6227) @option{--extract} (@option{--get}, @option{-x}),
@command{tar}
+../tar_texi/tar.texi(,6228) operates on all the archive members in the archive.
+../tar_texi/tar.texi(,6229)
+../tar_texi/tar.texi(,6230) If run with @option{--diff} option, tar will
compare the archive with
+../tar_texi/tar.texi(,6231) the contents of the current working directory.
+../tar_texi/tar.texi(,6232)
+../tar_texi/tar.texi(,6233) If you specify any other operation, @command{tar}
does nothing.
+../tar_texi/tar.texi(,6234)
+../tar_texi/tar.texi(,6235) By default, @command{tar} takes file names from
the command line. However,
+../tar_texi/tar.texi(,6236) there are other ways to specify file or member
names, or to modify the
+../tar_texi/tar.texi(,6237) manner in which @command{tar} selects the files or
members upon which to
+../tar_texi/tar.texi(,6238) operate. In general, these methods work both for
specifying the names
+../tar_texi/tar.texi(,6239) of files and archive members.
+../tar_texi/tar.texi(,6240)
+../tar_texi/tar.texi(,6241) @node files
+../tar_texi/tar.texi(,6242) @section Reading Names from a File
+../tar_texi/tar.texi(,6243)
+../tar_texi/tar.texi(,6244) @cindex Reading file names from a file
+../tar_texi/tar.texi(,6245) @cindex Lists of file names
+../tar_texi/tar.texi(,6246) @cindex File Name arguments, alternatives
+../tar_texi/tar.texi(,6247) Instead of giving the names of files or archive
members on the command
+../tar_texi/tar.texi(,6248) line, you can put the names into a file, and then
use the
+../tar_texi/tar.texi(,6249) @address@hidden (@option{-T
+../tar_texi/tar.texi(,6250) @var{file-of-names}}) option to @command{tar}.
Give the name of the
+../tar_texi/tar.texi(,6251) file which contains the list of files to include
as the argument to
+../tar_texi/tar.texi(,6252) @option{--files-from}. In the list, the file
names should be separated by
+../tar_texi/tar.texi(,6253) newlines. You will frequently use this option
when you have generated
+../tar_texi/tar.texi(,6254) the list of files to archive with the
@command{find} utility.
+../tar_texi/tar.texi(,6255)
+../tar_texi/tar.texi(,6256) @table @option
+../tar_texi/tar.texi(,6257) @opindex files-from
+../tar_texi/tar.texi(,6258) @item address@hidden
+../tar_texi/tar.texi(,6259) @itemx -T @var{file-name}
+../tar_texi/tar.texi(,6260) Get names to extract or create from file
@var{file-name}.
+../tar_texi/tar.texi(,6261) @end table
+../tar_texi/tar.texi(,6262)
+../tar_texi/tar.texi(,6263) If you give a single dash as a file name for
@option{--files-from}, (i.e.,
+../tar_texi/tar.texi(,6264) you specify either @code{--files-from=-} or
@code{-T -}), then the file
+../tar_texi/tar.texi(,6265) names are read from standard input.
+../tar_texi/tar.texi(,6266)
+../tar_texi/tar.texi(,6267) Unless you are running @command{tar} with
@option{--create}, you can not use
+../tar_texi/tar.texi(,6268) both @code{--files-from=-} and @code{--file=-}
(@code{-f -}) in the same
+../tar_texi/tar.texi(,6269) command.
+../tar_texi/tar.texi(,6270)
+../tar_texi/tar.texi(,6271) Any number of @option{-T} options can be given in
the command line.
+../tar_texi/tar.texi(,6272)
+../tar_texi/tar.texi(,6273) The following example shows how to use
@command{find} to generate a list of
+../tar_texi/tar.texi(,6274) files smaller than 400K in length and put that
list into a file
+../tar_texi/tar.texi(,6275) called @file{small-files}. You can then use the
@option{-T} option to
+../tar_texi/tar.texi(,6276) @command{tar} to specify the files from that file,
@file{small-files}, to
+../tar_texi/tar.texi(,6277) create the archive @file{little.tgz}. (The
@option{-z} option to
+../tar_texi/tar.texi(,6278) @command{tar} compresses the archive with
@command{gzip}; @pxref{gzip} for
+../tar_texi/tar.texi(,6279) more information.)
+../tar_texi/tar.texi(,6280)
+../tar_texi/tar.texi(,6281) @smallexample
+../tar_texi/tar.texi(,6282) $ @kbd{find . -size -400 -print > small-files}
+../tar_texi/tar.texi(,6283) $ @kbd{tar -c -v -z -T small-files -f little.tgz}
+../tar_texi/tar.texi(,6284) @end smallexample
+../tar_texi/tar.texi(,6285)
+../tar_texi/tar.texi(,6286) @noindent
+../tar_texi/tar.texi(,6287) In the file list given by @option{-T} option, any
file name beginning
+../tar_texi/tar.texi(,6288) with @samp{-} character is considered a
@command{tar} option and is
+../tar_texi/tar.texi(GNUTAR,6289) processed address@hidden of @acronym{GNU}
@command{tar} up to 1.15.1
+../tar_texi/tar.texi(,6290) recognized only @option{-C} option in file lists,
and only if the
+../tar_texi/tar.texi(,6291) option and its argument occupied two consecutive
lines.} For example,
+../tar_texi/tar.texi(,6292) the common use of this feature is to change to
another directory by
+../tar_texi/tar.texi(,6293) specifying @option{-C} option:
+../tar_texi/tar.texi(,6294)
+../tar_texi/tar.texi(,6295) @smallexample
+../tar_texi/tar.texi(,6296) @group
+../tar_texi/tar.texi(,6297) $ @kbd{cat list}
+../tar_texi/tar.texi(,6298) -C/etc
+../tar_texi/tar.texi(,6299) passwd
+../tar_texi/tar.texi(,6300) hosts
+../tar_texi/tar.texi(,6301) -C/lib
+../tar_texi/tar.texi(,6302) libc.a
+../tar_texi/tar.texi(,6303) $ @kbd{tar -c -f foo.tar --files-from list}
+../tar_texi/tar.texi(,6304) @end group
+../tar_texi/tar.texi(,6305) @end smallexample
+../tar_texi/tar.texi(,6306)
+../tar_texi/tar.texi(,6307) @noindent
+../tar_texi/tar.texi(,6308) In this example, @command{tar} will first switch
to @file{/etc}
+../tar_texi/tar.texi(,6309) directory and add files @file{passwd} and
@file{hosts} to the
+../tar_texi/tar.texi(,6310) archive. Then it will change to @file{/lib}
directory and will archive
+../tar_texi/tar.texi(,6311) the file @file{libc.a}. Thus, the resulting
archive @file{foo.tar} will
+../tar_texi/tar.texi(,6312) contain:
+../tar_texi/tar.texi(,6313)
+../tar_texi/tar.texi(,6314) @smallexample
+../tar_texi/tar.texi(,6315) @group
+../tar_texi/tar.texi(,6316) $ @kbd{tar tf foo.tar}
+../tar_texi/tar.texi(,6317) passwd
+../tar_texi/tar.texi(,6318) hosts
+../tar_texi/tar.texi(,6319) libc.a
+../tar_texi/tar.texi(,6320) @end group
+../tar_texi/tar.texi(,6321) @end smallexample
+../tar_texi/tar.texi(,6322)
+../tar_texi/tar.texi(,6323) @noindent
+../tar_texi/tar.texi(xopindex,6324) @opindex address@hidden, using in
@option{--files-from} argument}
+../tar_texi/tar.texi(,6325) Notice that the option parsing algorithm used with
@option{-T} is
+../tar_texi/tar.texi(,6326) stricter than the one used by shell. Namely, when
specifying option
+../tar_texi/tar.texi(,6327) arguments, you should observe the following rules:
+../tar_texi/tar.texi(,6328)
+../tar_texi/tar.texi(,6329) @itemize @bullet
+../tar_texi/tar.texi(,6330) @item
+../tar_texi/tar.texi(,6331) When using short (single-letter) option form, its
argument must
+../tar_texi/tar.texi(,6332) immediately follow the option letter, without any
intervening
+../tar_texi/tar.texi(,6333) whitespace. For example: @code{-Cdir}.
+../tar_texi/tar.texi(,6334)
+../tar_texi/tar.texi(,6335) @item
+../tar_texi/tar.texi(,6336) When using long option form, the option argument
must be separated
+../tar_texi/tar.texi(,6337) from the option by a single equal sign. No
whitespace is allowed on
+../tar_texi/tar.texi(,6338) any side of the equal sign. For example:
@code{--directory=dir}.
+../tar_texi/tar.texi(,6339)
+../tar_texi/tar.texi(,6340) @item
+../tar_texi/tar.texi(,6341) For both short and long option forms, the option
argument can be given
+../tar_texi/tar.texi(,6342) on the next line after the option name, e.g.:
+../tar_texi/tar.texi(,6343)
+../tar_texi/tar.texi(,6344) @smallexample
+../tar_texi/tar.texi(,6345) @group
+../tar_texi/tar.texi(,6346) --directory
+../tar_texi/tar.texi(,6347) dir
+../tar_texi/tar.texi(,6348) @end group
+../tar_texi/tar.texi(,6349) @end smallexample
+../tar_texi/tar.texi(,6350)
+../tar_texi/tar.texi(,6351) @noindent
+../tar_texi/tar.texi(,6352) and
+../tar_texi/tar.texi(,6353)
+../tar_texi/tar.texi(,6354) @smallexample
+../tar_texi/tar.texi(,6355) @group
+../tar_texi/tar.texi(,6356) -C
+../tar_texi/tar.texi(,6357) dir
+../tar_texi/tar.texi(,6358) @end group
+../tar_texi/tar.texi(,6359) @end smallexample
+../tar_texi/tar.texi(,6360) @end itemize
+../tar_texi/tar.texi(,6361)
+../tar_texi/tar.texi(,6362) @opindex add-file
+../tar_texi/tar.texi(,6363) If you happen to have a file whose name starts
with @samp{-},
+../tar_texi/tar.texi(,6364) precede it with @option{--add-file} option to
prevent it from
+../tar_texi/tar.texi(,6365) being recognized as an option. For example:
@code{--add-file=--my-file}.
+../tar_texi/tar.texi(,6366)
+../tar_texi/tar.texi(,6367) @menu
+../tar_texi/tar.texi(,6368) * nul::
+../tar_texi/tar.texi(,6369) @end menu
+../tar_texi/tar.texi(,6370)
+../tar_texi/tar.texi(,6371) @node nul
+../tar_texi/tar.texi(,6372) @subsection @code{NUL} Terminated File Names
+../tar_texi/tar.texi(,6373)
+../tar_texi/tar.texi(,6374) @cindex File names, terminated by @code{NUL}
+../tar_texi/tar.texi(,6375) @cindex @code{NUL} terminated file names
+../tar_texi/tar.texi(,6376) The @option{--null} option causes
+../tar_texi/tar.texi(,6377) @address@hidden (@option{-T @var{file-of-names}})
+../tar_texi/tar.texi(,6378) to read file names terminated by a @code{NUL}
instead of a newline, so
+../tar_texi/tar.texi(,6379) files whose names contain newlines can be archived
using
+../tar_texi/tar.texi(,6380) @option{--files-from}.
+../tar_texi/tar.texi(,6381)
+../tar_texi/tar.texi(,6382) @table @option
+../tar_texi/tar.texi(,6383) @opindex null
+../tar_texi/tar.texi(,6384) @item --null
+../tar_texi/tar.texi(,6385) Only consider @code{NUL} terminated file names,
instead of files that
+../tar_texi/tar.texi(,6386) terminate in a newline.
+../tar_texi/tar.texi(,6387) @end table
+../tar_texi/tar.texi(,6388)
+../tar_texi/tar.texi(,6389) The @option{--null} option is just like the one in
@acronym{GNU}
+../tar_texi/tar.texi(,6390) @command{xargs} and @command{cpio}, and is useful
with the
+../tar_texi/tar.texi(,6391) @option{-print0} predicate of @acronym{GNU}
@command{find}. In
+../tar_texi/tar.texi(,6392) @command{tar}, @option{--null} also disables
special handling for
+../tar_texi/tar.texi(,6393) file names that begin with dash.
+../tar_texi/tar.texi(,6394)
+../tar_texi/tar.texi(,6395) This example shows how to use @command{find} to
generate a list of files
+../tar_texi/tar.texi(,6396) larger than 800K in length and put that list into
a file called
+../tar_texi/tar.texi(,6397) @file{long-files}. The @option{-print0} option to
@command{find} is just
+../tar_texi/tar.texi(,6398) like @option{-print}, except that it separates
files with a @code{NUL}
+../tar_texi/tar.texi(,6399) rather than with a newline. You can then run
@command{tar} with both the
+../tar_texi/tar.texi(,6400) @option{--null} and @option{-T} options to specify
that @command{tar} get the
+../tar_texi/tar.texi(,6401) files from that file, @file{long-files}, to create
the archive
+../tar_texi/tar.texi(,6402) @file{big.tgz}. The @option{--null} option to
@command{tar} will cause
+../tar_texi/tar.texi(,6403) @command{tar} to recognize the @code{NUL}
separator between files.
+../tar_texi/tar.texi(,6404)
+../tar_texi/tar.texi(,6405) @smallexample
+../tar_texi/tar.texi(,6406) $ @kbd{find . -size +800 -print0 > long-files}
+../tar_texi/tar.texi(,6407) $ @kbd{tar -c -v --null --files-from=long-files
--file=big.tar}
+../tar_texi/tar.texi(,6408) @end smallexample
+../tar_texi/tar.texi(,6409)
+../tar_texi/tar.texi(FIXME,6410) @allow-recursion
+../tar_texi/tar.texi(FIXME,6410) @quote-arg
+../tar_texi/tar.texi(FIXME,6410)
+../tar_texi/tar.texi(,6411)
+../tar_texi/tar.texi(,6412) @node exclude
+../tar_texi/tar.texi(,6413) @section Excluding Some Files
+../tar_texi/tar.texi(UNREVISED,6414) @quotation
+../tar_texi/tar.texi(UNREVISED,6414) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,6414) @end quotation
+../tar_texi/tar.texi(UNREVISED,6414)
+../tar_texi/tar.texi(,6415)
+../tar_texi/tar.texi(,6416) @cindex File names, excluding files by
+../tar_texi/tar.texi(,6417) @cindex Excluding files by name and pattern
+../tar_texi/tar.texi(,6418) @cindex Excluding files by file system
+../tar_texi/tar.texi(,6419) To avoid operating on files whose names match a
particular pattern,
+../tar_texi/tar.texi(,6420) use the @option{--exclude} or
@option{--exclude-from} options.
+../tar_texi/tar.texi(,6421)
+../tar_texi/tar.texi(,6422) @table @option
+../tar_texi/tar.texi(,6423) @opindex exclude
+../tar_texi/tar.texi(,6424) @item address@hidden
+../tar_texi/tar.texi(,6425) Causes @command{tar} to ignore files that match
the @var{pattern}.
+../tar_texi/tar.texi(,6426) @end table
+../tar_texi/tar.texi(,6427)
+../tar_texi/tar.texi(,6428) @findex exclude
+../tar_texi/tar.texi(,6429) The @address@hidden option prevents any file or
+../tar_texi/tar.texi(,6430) member whose name matches the shell wildcard
(@var{pattern}) from
+../tar_texi/tar.texi(,6431) being operated on.
+../tar_texi/tar.texi(,6432) For example, to create an archive with all the
contents of the directory
+../tar_texi/tar.texi(,6433) @file{src} except for files whose names end in
@file{.o}, use the
+../tar_texi/tar.texi(,6434) command @samp{tar -cf src.tar --exclude='*.o' src}.
+../tar_texi/tar.texi(,6435)
+../tar_texi/tar.texi(,6436) You may give multiple @option{--exclude} options.
+../tar_texi/tar.texi(,6437)
+../tar_texi/tar.texi(,6438) @table @option
+../tar_texi/tar.texi(,6439) @opindex exclude-from
+../tar_texi/tar.texi(,6440) @item address@hidden
+../tar_texi/tar.texi(,6441) @itemx -X @var{file}
+../tar_texi/tar.texi(,6442) Causes @command{tar} to ignore files that match
the patterns listed in
+../tar_texi/tar.texi(,6443) @var{file}.
+../tar_texi/tar.texi(,6444) @end table
+../tar_texi/tar.texi(,6445)
+../tar_texi/tar.texi(,6446) @findex exclude-from
+../tar_texi/tar.texi(,6447) Use the @option{--exclude-from} option to read a
+../tar_texi/tar.texi(,6448) list of patterns, one per line, from @var{file};
@command{tar} will
+../tar_texi/tar.texi(,6449) ignore files matching those patterns. Thus if
@command{tar} is
+../tar_texi/tar.texi(,6450) called as @address@hidden -c -X foo .}} and the
file @file{foo} contains a
+../tar_texi/tar.texi(,6451) single line @file{*.o}, no files whose names end
in @file{.o} will be
+../tar_texi/tar.texi(,6452) added to the archive.
+../tar_texi/tar.texi(,6453)
+../tar_texi/tar.texi(,6454) @table @option
+../tar_texi/tar.texi(,6455) @opindex exclude-caches
+../tar_texi/tar.texi(,6456) @item --exclude-caches
+../tar_texi/tar.texi(,6457) Causes @command{tar} to ignore directories
containing a cache directory tag.
+../tar_texi/tar.texi(,6458) @end table
+../tar_texi/tar.texi(,6459)
+../tar_texi/tar.texi(,6460) @findex exclude-caches
+../tar_texi/tar.texi(,6461) When creating an archive, the
@option{--exclude-caches} option causes
+../tar_texi/tar.texi(,6462) @command{tar} to exclude all directories that
contain a @dfn{cache
+../tar_texi/tar.texi(,6463) directory tag}. A cache directory tag is a short
file with the
+../tar_texi/tar.texi(,6464) well-known name @file{CACHEDIR.TAG} and having a
standard header
+../tar_texi/tar.texi(,6465) specified in
@url{http://www.brynosaurus.com/cachedir/spec.html}.
+../tar_texi/tar.texi(,6466) Various applications write cache directory tags
into directories they
+../tar_texi/tar.texi(,6467) use to hold regenerable, non-precious data, so
that such data can be
+../tar_texi/tar.texi(,6468) more easily excluded from backups.
+../tar_texi/tar.texi(,6469)
+../tar_texi/tar.texi(,6470) @menu
+../tar_texi/tar.texi(,6471) * problems with exclude::
+../tar_texi/tar.texi(,6472) @end menu
+../tar_texi/tar.texi(,6473)
+../tar_texi/tar.texi(,6474) @node problems with exclude
+../tar_texi/tar.texi(,6475) @unnumberedsubsec Problems with Using the
@code{exclude} Options
+../tar_texi/tar.texi(,6476)
+../tar_texi/tar.texi(xopindex,6477) @opindex address@hidden, potential
problems with}
+../tar_texi/tar.texi(,6478) Some users find @samp{exclude} options confusing.
Here are some common
+../tar_texi/tar.texi(,6479) pitfalls:
+../tar_texi/tar.texi(,6480)
+../tar_texi/tar.texi(,6481) @itemize @bullet
+../tar_texi/tar.texi(,6482) @item
+../tar_texi/tar.texi(,6483) The main operating mode of @command{tar} does not
act on a path name
+../tar_texi/tar.texi(,6484) explicitly listed on the command line if one of
its file name
+../tar_texi/tar.texi(,6485) components is excluded. In the example above, if
+../tar_texi/tar.texi(,6486) you create an archive and exclude files that end
with @samp{*.o}, but
+../tar_texi/tar.texi(,6487) explicitly name the file @samp{dir.o/foo} after
all the options have been
+../tar_texi/tar.texi(,6488) listed, @samp{dir.o/foo} will be excluded from the
archive.
+../tar_texi/tar.texi(,6489)
+../tar_texi/tar.texi(,6490) @item
+../tar_texi/tar.texi(,6491) You can sometimes confuse the meanings of
@option{--exclude} and
+../tar_texi/tar.texi(,6492) @option{--exclude-from}. Be careful: use
@option{--exclude} when files
+../tar_texi/tar.texi(,6493) to be excluded are given as a pattern on the
command line. Use
+../tar_texi/tar.texi(,6494) @option{--exclude-from} to introduce the name of a
file which contains
+../tar_texi/tar.texi(,6495) a list of patterns, one per line; each of these
patterns can exclude
+../tar_texi/tar.texi(,6496) zero, one, or many files.
+../tar_texi/tar.texi(,6497)
+../tar_texi/tar.texi(,6498) @item
+../tar_texi/tar.texi(,6499) When you use @address@hidden, be sure to quote the
+../tar_texi/tar.texi(GNUTAR,6500) @var{pattern} parameter, so @acronym{GNU}
@command{tar} sees wildcard characters
+../tar_texi/tar.texi(,6501) like @samp{*}. If you do not do this, the shell
might expand the
+../tar_texi/tar.texi(,6502) @samp{*} itself using files at hand, so
@command{tar} might receive a
+../tar_texi/tar.texi(,6503) list of files instead of one pattern, or none at
all, making the
+../tar_texi/tar.texi(,6504) command somewhat illegal. This might not
correspond to what you want.
+../tar_texi/tar.texi(,6505)
+../tar_texi/tar.texi(,6506) For example, write:
+../tar_texi/tar.texi(,6507)
+../tar_texi/tar.texi(,6508) @smallexample
+../tar_texi/tar.texi(,6509) $ @kbd{tar -c -f @var{archive.tar} --exclude '*.o'
@var{directory}}
+../tar_texi/tar.texi(,6510) @end smallexample
+../tar_texi/tar.texi(,6511)
+../tar_texi/tar.texi(,6512) @noindent
+../tar_texi/tar.texi(,6513) rather than:
+../tar_texi/tar.texi(,6514)
+../tar_texi/tar.texi(,6515) @smallexample
+../tar_texi/tar.texi(,6516) # @emph{Wrong!}
+../tar_texi/tar.texi(,6517) $ @kbd{tar -c -f @var{archive.tar} --exclude *.o
@var{directory}}
+../tar_texi/tar.texi(,6518) @end smallexample
+../tar_texi/tar.texi(,6519)
+../tar_texi/tar.texi(,6520) @item
+../tar_texi/tar.texi(,6521) You must use use shell syntax, or globbing, rather
than @code{regexp}
+../tar_texi/tar.texi(,6522) syntax, when using exclude options in
@command{tar}. If you try to use
+../tar_texi/tar.texi(,6523) @code{regexp} syntax to describe files to be
excluded, your command
+../tar_texi/tar.texi(,6524) might fail.
+../tar_texi/tar.texi(,6525)
+../tar_texi/tar.texi(,6526) @item
+../tar_texi/tar.texi(FIXME,6529) @allow-recursion
+../tar_texi/tar.texi(FIXME,6529) @quote-arg
+../tar_texi/tar.texi(FIXME,6529)
+../tar_texi/tar.texi(,6530) In earlier versions of @command{tar}, what is now
the
+../tar_texi/tar.texi(,6531) @option{--exclude-from} option was called
@option{--exclude} instead.
+../tar_texi/tar.texi(,6532) Now, @option{--exclude} applies to patterns listed
on the command
+../tar_texi/tar.texi(,6533) line and @option{--exclude-from} applies to
patterns listed in a
+../tar_texi/tar.texi(,6534) file.
+../tar_texi/tar.texi(,6535)
+../tar_texi/tar.texi(,6536) @end itemize
+../tar_texi/tar.texi(,6537)
+../tar_texi/tar.texi(,6538) @node wildcards
+../tar_texi/tar.texi(,6539) @section Wildcards Patterns and Matching
+../tar_texi/tar.texi(,6540)
+../tar_texi/tar.texi(,6541) @dfn{Globbing} is the operation by which
@dfn{wildcard} characters,
+../tar_texi/tar.texi(,6542) @samp{*} or @samp{?} for example, are replaced and
expanded into all
+../tar_texi/tar.texi(GNUTAR,6543) existing files matching the given pattern.
@acronym{GNU} @command{tar} can use wildcard
+../tar_texi/tar.texi(,6544) patterns for matching (or globbing) archive
members when extracting
+../tar_texi/tar.texi(,6545) from or listing an archive. Wildcard patterns are
also used for
+../tar_texi/tar.texi(,6546) verifying volume labels of @command{tar} archives.
This section has the
+../tar_texi/tar.texi(,6547) purpose of explaining wildcard syntax for
@command{tar}.
+../tar_texi/tar.texi(,6548)
+../tar_texi/tar.texi(FIXME,6549) @allow-recursion
+../tar_texi/tar.texi(FIXME,6549) @quote-arg
+../tar_texi/tar.texi(FIXME,6549)
+../tar_texi/tar.texi(,6550)
+../tar_texi/tar.texi(,6551) A @var{pattern} should be written according to
shell syntax, using wildcard
+../tar_texi/tar.texi(,6552) characters to effect globbing. Most characters in
the pattern stand
+../tar_texi/tar.texi(,6553) for themselves in the matched string, and case is
significant: @samp{a}
+../tar_texi/tar.texi(,6554) will match only @samp{a}, and not @samp{A}. The
character @samp{?} in the
+../tar_texi/tar.texi(,6555) pattern matches any single character in the
matched string. The character
+../tar_texi/tar.texi(,6556) @samp{*} in the pattern matches zero, one, or more
single characters in
+../tar_texi/tar.texi(,6557) the matched string. The character @samp{\} says
to take the following
+../tar_texi/tar.texi(,6558) character of the pattern @emph{literally}; it is
useful when one needs to
+../tar_texi/tar.texi(,6559) match the @samp{?}, @samp{*}, @samp{[} or @samp{\}
characters, themselves.
+../tar_texi/tar.texi(,6560)
+../tar_texi/tar.texi(,6561) The character @samp{[}, up to the matching
@samp{]}, introduces a character
+../tar_texi/tar.texi(,6562) class. A @dfn{character class} is a list of
acceptable characters
+../tar_texi/tar.texi(,6563) for the next single character of the matched
string. For example,
+../tar_texi/tar.texi(,6564) @samp{[abcde]} would match any of the first five
letters of the alphabet.
+../tar_texi/tar.texi(,6565) Note that within a character class, all of the
``special characters''
+../tar_texi/tar.texi(,6566) listed above other than @samp{\} lose their
special meaning; for example,
+../tar_texi/tar.texi(,6567) @samp{[-\\[*?]]} would match any of the
characters, @samp{-}, @samp{\},
+../tar_texi/tar.texi(,6568) @samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due
to parsing constraints,
+../tar_texi/tar.texi(,6569) the characters @samp{-} and @samp{]} must either
come @emph{first} or
+../tar_texi/tar.texi(,6570) @emph{last} in a character class.)
+../tar_texi/tar.texi(,6571)
+../tar_texi/tar.texi(,6572) @cindex Excluding characters from a character class
+../tar_texi/tar.texi(,6573) @cindex Character class, excluding characters from
+../tar_texi/tar.texi(,6574) If the first character of the class after the
opening @samp{[}
+../tar_texi/tar.texi(,6575) is @samp{!} or @samp{^}, then the meaning of the
class is reversed.
+../tar_texi/tar.texi(,6576) Rather than listing character to match, it lists
those characters which
+../tar_texi/tar.texi(,6577) are @emph{forbidden} as the next single character
of the matched string.
+../tar_texi/tar.texi(,6578)
+../tar_texi/tar.texi(,6579) Other characters of the class stand for
themselves. The special
+../tar_texi/tar.texi(,6580) construction @address@hidden@var{e}]}, using an
hyphen between two
+../tar_texi/tar.texi(,6581) letters, is meant to represent all characters
between @var{a} and
+../tar_texi/tar.texi(,6582) @var{e}, inclusive.
+../tar_texi/tar.texi(,6583)
+../tar_texi/tar.texi(FIXME,6585) @allow-recursion
+../tar_texi/tar.texi(FIXME,6585) @quote-arg
+../tar_texi/tar.texi(FIXME,6585)
+../tar_texi/tar.texi(,6586)
+../tar_texi/tar.texi(,6587) Periods (@samp{.}) or forward slashes (@samp{/})
are not considered
+../tar_texi/tar.texi(,6588) special for wildcard matches. However, if a
pattern completely matches
+../tar_texi/tar.texi(,6589) a directory prefix of a matched string, then it
matches the full matched
+../tar_texi/tar.texi(,6590) string: thus, excluding a directory also excludes
all the files beneath it.
+../tar_texi/tar.texi(,6591)
+../tar_texi/tar.texi(,6592) @menu
+../tar_texi/tar.texi(,6593) * controlling pattern-matching::
+../tar_texi/tar.texi(,6594) @end menu
+../tar_texi/tar.texi(,6595)
+../tar_texi/tar.texi(,6596) @node controlling pattern-matching
+../tar_texi/tar.texi(,6597) @unnumberedsubsec Controlling Pattern-Matching
+../tar_texi/tar.texi(,6598)
+../tar_texi/tar.texi(,6599) For the purposes of this section, we call
@dfn{exclusion members} all
+../tar_texi/tar.texi(,6600) member names obtained while processing
@option{--exclude} and
+../tar_texi/tar.texi(,6601) @option{--exclude-from} options, and
@dfn{inclusion members} those
+../tar_texi/tar.texi(,6602) member names that were given in the command line
or read from the file
+../tar_texi/tar.texi(,6603) specified with @option{--files-from} option.
+../tar_texi/tar.texi(,6604)
+../tar_texi/tar.texi(,6605) These two pairs of member lists are used in the
following operations:
+../tar_texi/tar.texi(,6606) @option{--diff}, @option{--extract},
@option{--list},
+../tar_texi/tar.texi(,6607) @option{--update}.
+../tar_texi/tar.texi(,6608)
+../tar_texi/tar.texi(,6609) There are no inclusion members in create mode
(@option{--create} and
+../tar_texi/tar.texi(,6610) @option{--append}), since in this mode the names
obtained from the
+../tar_texi/tar.texi(,6611) command line refer to @emph{files}, not archive
members.
+../tar_texi/tar.texi(,6612)
+../tar_texi/tar.texi(,6613) By default, inclusion members are compared with
archive members
+../tar_texi/tar.texi(GNUTAR,6614) literally @footnote{Notice that earlier
@acronym{GNU} @command{tar} versions used
+../tar_texi/tar.texi(,6615) globbing for inclusion members, which contradicted
to UNIX98
+../tar_texi/tar.texi(,6616) specification and was not documented.
@xref{Changes}, for more
+../tar_texi/tar.texi(,6617) information on this and other changes.} and
exclusion members are
+../tar_texi/tar.texi(,6618) treated as globbing patterns. For example:
+../tar_texi/tar.texi(,6619)
+../tar_texi/tar.texi(,6620) @smallexample
+../tar_texi/tar.texi(,6621) @group
+../tar_texi/tar.texi(,6622) $ @kbd{tar tf foo.tar}
+../tar_texi/tar.texi(,6623) a.c
+../tar_texi/tar.texi(,6624) b.c
+../tar_texi/tar.texi(,6625) a.txt
+../tar_texi/tar.texi(,6626) [remarks]
+../tar_texi/tar.texi(,6627) # @i{Member names are used verbatim:}
+../tar_texi/tar.texi(,6628) $ @kbd{tar -xf foo.tar -v '[remarks]'}
+../tar_texi/tar.texi(,6629) [remarks]
+../tar_texi/tar.texi(,6630) # @i{Exclude member names are globbed:}
+../tar_texi/tar.texi(,6631) $ @kbd{tar -xf foo.tar -v --exclude '*.c'}
+../tar_texi/tar.texi(,6632) a.txt
+../tar_texi/tar.texi(,6633) [remarks]
+../tar_texi/tar.texi(,6634) @end group
+../tar_texi/tar.texi(,6635) @end smallexample
+../tar_texi/tar.texi(,6636)
+../tar_texi/tar.texi(,6637) This behavior can be altered by using the
following options:
+../tar_texi/tar.texi(,6638)
+../tar_texi/tar.texi(,6639) @table @option
+../tar_texi/tar.texi(,6640) @opindex wildcards
+../tar_texi/tar.texi(,6641) @item --wildcards
+../tar_texi/tar.texi(,6642) Treat all member names as wildcards.
+../tar_texi/tar.texi(,6643)
+../tar_texi/tar.texi(,6644) @opindex no-wildcards
+../tar_texi/tar.texi(,6645) @item --no-wildcards
+../tar_texi/tar.texi(,6646) Treat all member names as literal strings.
+../tar_texi/tar.texi(,6647) @end table
+../tar_texi/tar.texi(,6648)
+../tar_texi/tar.texi(,6649) Thus, to extract files whose names end in
@samp{.c}, you can use:
+../tar_texi/tar.texi(,6650)
+../tar_texi/tar.texi(,6651) @smallexample
+../tar_texi/tar.texi(,6652) $ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
+../tar_texi/tar.texi(,6653) a.c
+../tar_texi/tar.texi(,6654) b.c
+../tar_texi/tar.texi(,6655) @end smallexample
+../tar_texi/tar.texi(,6656)
+../tar_texi/tar.texi(,6657) @noindent
+../tar_texi/tar.texi(,6658) Notice quoting of the pattern to prevent the shell
from interpreting
+../tar_texi/tar.texi(,6659) it.
+../tar_texi/tar.texi(,6660)
+../tar_texi/tar.texi(,6661) The effect of @option{--wildcards} option is
cancelled by
+../tar_texi/tar.texi(,6662) @option{--no-wildcards}. This can be used to pass
part of
+../tar_texi/tar.texi(,6663) the command line arguments verbatim and other part
as globbing
+../tar_texi/tar.texi(,6664) patterns. For example, the following invocation:
+../tar_texi/tar.texi(,6665)
+../tar_texi/tar.texi(,6666) @smallexample
+../tar_texi/tar.texi(,6667) $ @kbd{tar -xf foo.tar --wildcards '*.txt'
--no-wildcards '[remarks]'}
+../tar_texi/tar.texi(,6668) @end smallexample
+../tar_texi/tar.texi(,6669)
+../tar_texi/tar.texi(,6670) @noindent
+../tar_texi/tar.texi(,6671) instructs @command{tar} to extract from
@file{foo.tar} all files whose
+../tar_texi/tar.texi(,6672) names end in @samp{.txt} and the file named
@file{[remarks]}.
+../tar_texi/tar.texi(,6673)
+../tar_texi/tar.texi(,6674) Normally, a pattern matches a name if an initial
subsequence of the
+../tar_texi/tar.texi(,6675) name's components matches the pattern, where
@samp{*}, @samp{?}, and
+../tar_texi/tar.texi(,6676) @samp{[...]} are the usual shell wildcards,
@samp{\} escapes wildcards,
+../tar_texi/tar.texi(,6677) and wildcards can match @samp{/}.
+../tar_texi/tar.texi(,6678)
+../tar_texi/tar.texi(,6679) Other than optionally stripping leading @samp{/}
from names
+../tar_texi/tar.texi(,6680) (@pxref{absolute}), patterns and names are used
as-is. For
+../tar_texi/tar.texi(,6681) example, trailing @samp{/} is not trimmed from a
user-specified name
+../tar_texi/tar.texi(,6682) before deciding whether to exclude it.
+../tar_texi/tar.texi(,6683)
+../tar_texi/tar.texi(,6684) However, this matching procedure can be altered by
the options listed
+../tar_texi/tar.texi(,6685) below. These options accumulate. For example:
+../tar_texi/tar.texi(,6686)
+../tar_texi/tar.texi(,6687) @smallexample
+../tar_texi/tar.texi(,6688) --ignore-case --exclude='makefile'
--no-ignore-case ---exclude='readme'
+../tar_texi/tar.texi(,6689) @end smallexample
+../tar_texi/tar.texi(,6690)
+../tar_texi/tar.texi(,6691) @noindent
+../tar_texi/tar.texi(,6692) ignores case when excluding @samp{makefile}, but
not when excluding
+../tar_texi/tar.texi(,6693) @samp{readme}.
+../tar_texi/tar.texi(,6694)
+../tar_texi/tar.texi(,6695) @table @option
+../tar_texi/tar.texi(,6696) @opindex anchored
+../tar_texi/tar.texi(,6697) @opindex no-anchored
+../tar_texi/tar.texi(,6698) @item --anchored
+../tar_texi/tar.texi(,6699) @itemx --no-anchored
+../tar_texi/tar.texi(,6700) If anchored, a pattern must match an initial
subsequence
+../tar_texi/tar.texi(,6701) of the name's components. Otherwise, the pattern
can match any
+../tar_texi/tar.texi(,6702) subsequence. Default is @option{--no-anchored}
for exclusion members
+../tar_texi/tar.texi(,6703) and @option{--anchored} inclusion members.
+../tar_texi/tar.texi(,6704)
+../tar_texi/tar.texi(,6705) @opindex ignore-case
+../tar_texi/tar.texi(,6706) @opindex no-ignore-case
+../tar_texi/tar.texi(,6707) @item --ignore-case
+../tar_texi/tar.texi(,6708) @itemx --no-ignore-case
+../tar_texi/tar.texi(,6709) When ignoring case, upper-case patterns match
lower-case names and vice versa.
+../tar_texi/tar.texi(,6710) When not ignoring case (the default), matching is
case-sensitive.
+../tar_texi/tar.texi(,6711)
+../tar_texi/tar.texi(,6712) @opindex wildcards-match-slash
+../tar_texi/tar.texi(,6713) @opindex no-wildcards-match-slash
+../tar_texi/tar.texi(,6714) @item --wildcards-match-slash
+../tar_texi/tar.texi(,6715) @itemx --no-wildcards-match-slash
+../tar_texi/tar.texi(,6716) When wildcards match slash (the default for
exclusion members), a
+../tar_texi/tar.texi(,6717) wildcard like @samp{*} in the pattern can match a
@samp{/} in the
+../tar_texi/tar.texi(,6718) name. Otherwise, @samp{/} is matched only by
@samp{/}.
+../tar_texi/tar.texi(,6719)
+../tar_texi/tar.texi(,6720) @end table
+../tar_texi/tar.texi(,6721)
+../tar_texi/tar.texi(,6722) The @option{--recursion} and
@option{--no-recursion} options
+../tar_texi/tar.texi(,6723) (@pxref{recurse}) also affect how member patterns
are interpreted. If
+../tar_texi/tar.texi(,6724) recursion is in effect, a pattern matches a name
if it matches any of
+../tar_texi/tar.texi(,6725) the name's parent directories.
+../tar_texi/tar.texi(,6726)
+../tar_texi/tar.texi(,6727) The following table summarizes pattern-matching
default values:
+../tar_texi/tar.texi(,6728)
+../tar_texi/tar.texi(,6729) @multitable @columnfractions .3 .7
+../tar_texi/tar.texi(,6730) @headitem Members @tab Default settings
+../tar_texi/tar.texi(,6731) @item Inclusion @tab @option{--no-wildcards
--anchored --no-wildcards-match-slash}
+../tar_texi/tar.texi(,6732) @item Exclusion @tab @option{--wildcards
--no-anchored --wildcards-match-slash}
+../tar_texi/tar.texi(,6733) @end multitable
+../tar_texi/tar.texi(,6734)
+../tar_texi/tar.texi(,6735) @node quoting styles
+../tar_texi/tar.texi(,6736) @section Quoting Member Names
+../tar_texi/tar.texi(,6737)
+../tar_texi/tar.texi(,6738) When displaying member names, @command{tar} takes
care to avoid
+../tar_texi/tar.texi(,6739) ambiguities caused by certain characters. This is
called @dfn{name
+../tar_texi/tar.texi(,6740) quoting}. The characters in question are:
+../tar_texi/tar.texi(,6741)
+../tar_texi/tar.texi(,6742) @itemize @bullet
+../tar_texi/tar.texi(,6743) @item Non-printable control characters:
+../tar_texi/tar.texi(,6744)
+../tar_texi/tar.texi(,6745) @multitable @columnfractions 0.20 0.10 0.60
+../tar_texi/tar.texi(,6746) @headitem Character @tab ASCII @tab Character name
+../tar_texi/tar.texi(,6747) @item \a @tab 7 @tab Audible bell
+../tar_texi/tar.texi(,6748) @item \b @tab 8 @tab Backspace
+../tar_texi/tar.texi(,6749) @item \f @tab 12 @tab Form feed
+../tar_texi/tar.texi(,6750) @item \n @tab 10 @tab New line
+../tar_texi/tar.texi(,6751) @item \r @tab 13 @tab Carriage return
+../tar_texi/tar.texi(,6752) @item \t @tab 9 @tab Horizontal tabulation
+../tar_texi/tar.texi(,6753) @item \v @tab 11 @tab Vertical tabulation
+../tar_texi/tar.texi(,6754) @end multitable
+../tar_texi/tar.texi(,6755)
+../tar_texi/tar.texi(,6756) @item Space (ASCII 32)
+../tar_texi/tar.texi(,6757)
+../tar_texi/tar.texi(,6758) @item Single and double quotes (@samp{'} and
@samp{"})
+../tar_texi/tar.texi(,6759)
+../tar_texi/tar.texi(,6760) @item Backslash (@samp{\})
+../tar_texi/tar.texi(,6761) @end itemize
+../tar_texi/tar.texi(,6762)
+../tar_texi/tar.texi(,6763) The exact way @command{tar} uses to quote these
characters depends on
+../tar_texi/tar.texi(,6764) the @dfn{quoting style}. The default quoting
style, called
+../tar_texi/tar.texi(,6765) @dfn{escape} (see below), uses backslash notation
to represent control
+../tar_texi/tar.texi(,6766) characters, space and backslash. Using this
quoting style, control
+../tar_texi/tar.texi(,6767) characters are represented as listed in column
@samp{Character} in the
+../tar_texi/tar.texi(,6768) above table, a space is printed as @samp{\ } and a
backslash as @samp{\\}.
+../tar_texi/tar.texi(,6769)
+../tar_texi/tar.texi(GNUTAR,6770) @acronym{GNU} @command{tar} offers seven
distinct quoting styles, which can be selected
+../tar_texi/tar.texi(,6771) using @option{--quoting-style} option:
+../tar_texi/tar.texi(,6772)
+../tar_texi/tar.texi(,6773) @table @option
+../tar_texi/tar.texi(,6774) @item address@hidden
+../tar_texi/tar.texi(,6775) @opindex quoting-style
+../tar_texi/tar.texi(,6776)
+../tar_texi/tar.texi(,6777) Sets quoting style. Valid values for @var{style}
argument are:
+../tar_texi/tar.texi(,6778) literal, shell, shell-always, c, escape, locale,
clocale.
+../tar_texi/tar.texi(,6779) @end table
+../tar_texi/tar.texi(,6780)
+../tar_texi/tar.texi(,6781) These styles are described in detail below. To
illustrate their
+../tar_texi/tar.texi(,6782) effect, we will use an imaginary tar archive
@file{arch.tar}
+../tar_texi/tar.texi(,6783) containing the following members:
+../tar_texi/tar.texi(,6784)
+../tar_texi/tar.texi(,6785) @smallexample
+../tar_texi/tar.texi(,6786) @group
+../tar_texi/tar.texi(,6787) # 1. Contains horizontal tabulation character.
+../tar_texi/tar.texi(,6788) a tab
+../tar_texi/tar.texi(,6789) # 2. Contains newline character
+../tar_texi/tar.texi(,6790) a
+../tar_texi/tar.texi(,6791) newline
+../tar_texi/tar.texi(,6792) # 3. Contains a space
+../tar_texi/tar.texi(,6793) a space
+../tar_texi/tar.texi(,6794) # 4. Contains double quotes
+../tar_texi/tar.texi(,6795) a"double"quote
+../tar_texi/tar.texi(,6796) # 5. Contains single quotes
+../tar_texi/tar.texi(,6797) a'single'quote
+../tar_texi/tar.texi(,6798) # 6. Contains a backslash character:
+../tar_texi/tar.texi(,6799) a\backslash
+../tar_texi/tar.texi(,6800) @end group
+../tar_texi/tar.texi(,6801) @end smallexample
+../tar_texi/tar.texi(,6802)
+../tar_texi/tar.texi(,6803) Here is how usual @command{ls} command would have
listed them, if they
+../tar_texi/tar.texi(,6804) had existed in the current working directory:
+../tar_texi/tar.texi(,6805)
+../tar_texi/tar.texi(,6806) @smallexample
+../tar_texi/tar.texi(,6807) @group
+../tar_texi/tar.texi(,6808) $ @kbd{ls}
+../tar_texi/tar.texi(,6809) a\ttab
+../tar_texi/tar.texi(,6810) a\nnewline
+../tar_texi/tar.texi(,6811) a\ space
+../tar_texi/tar.texi(,6812) a"double"quote
+../tar_texi/tar.texi(,6813) a'single'quote
+../tar_texi/tar.texi(,6814) a\\backslash
+../tar_texi/tar.texi(,6815) @end group
+../tar_texi/tar.texi(,6816) @end smallexample
+../tar_texi/tar.texi(,6817)
+../tar_texi/tar.texi(,6818) Quoting styles:
+../tar_texi/tar.texi(,6819)
+../tar_texi/tar.texi(,6820) @table @samp
+../tar_texi/tar.texi(,6821) @item literal
+../tar_texi/tar.texi(,6822) No quoting, display each character as is:
+../tar_texi/tar.texi(,6823)
+../tar_texi/tar.texi(,6824) @smallexample
+../tar_texi/tar.texi(,6825) @group
+../tar_texi/tar.texi(,6826) $ @kbd{tar tf arch.tar --quoting-style=literal}
+../tar_texi/tar.texi(,6827) ./
+../tar_texi/tar.texi(,6828) ./a space
+../tar_texi/tar.texi(,6829) ./a'single'quote
+../tar_texi/tar.texi(,6830) ./a"double"quote
+../tar_texi/tar.texi(,6831) ./a\backslash
+../tar_texi/tar.texi(,6832) ./a tab
+../tar_texi/tar.texi(,6833) ./a
+../tar_texi/tar.texi(,6834) newline
+../tar_texi/tar.texi(,6835) @end group
+../tar_texi/tar.texi(,6836) @end smallexample
+../tar_texi/tar.texi(,6837)
+../tar_texi/tar.texi(,6838) @item shell
+../tar_texi/tar.texi(,6839) Display characters the same way Bourne shell does:
+../tar_texi/tar.texi(,6840) control characters, except @samp{\t} and
@samp{\n}, are printed using
+../tar_texi/tar.texi(,6841) backslash escapes, @samp{\t} and @samp{\n} are
printed as is, and a
+../tar_texi/tar.texi(,6842) single quote is printed as @samp{\'}. If a name
contains any quoted
+../tar_texi/tar.texi(,6843) characters, it is enclosed in single quotes. In
particular, if a name
+../tar_texi/tar.texi(,6844) contains single quotes, it is printed as several
single-quoted strings:
+../tar_texi/tar.texi(,6845)
+../tar_texi/tar.texi(,6846) @smallexample
+../tar_texi/tar.texi(,6847) @group
+../tar_texi/tar.texi(,6848) $ @kbd{tar tf arch.tar --quoting-style=shell}
+../tar_texi/tar.texi(,6849) ./
+../tar_texi/tar.texi(,6850) './a space'
+../tar_texi/tar.texi(,6851) './a'\''single'\''quote'
+../tar_texi/tar.texi(,6852) './a"double"quote'
+../tar_texi/tar.texi(,6853) './a\backslash'
+../tar_texi/tar.texi(,6854) './a tab'
+../tar_texi/tar.texi(,6855) './a
+../tar_texi/tar.texi(,6856) newline'
+../tar_texi/tar.texi(,6857) @end group
+../tar_texi/tar.texi(,6858) @end smallexample
+../tar_texi/tar.texi(,6859)
+../tar_texi/tar.texi(,6860) @item shell-always
+../tar_texi/tar.texi(,6861) Same as @samp{shell}, but the names are always
enclosed in single
+../tar_texi/tar.texi(,6862) quotes:
+../tar_texi/tar.texi(,6863)
+../tar_texi/tar.texi(,6864) @smallexample
+../tar_texi/tar.texi(,6865) @group
+../tar_texi/tar.texi(,6866) $ @kbd{tar tf arch.tar
--quoting-style=shell-always}
+../tar_texi/tar.texi(,6867) './'
+../tar_texi/tar.texi(,6868) './a space'
+../tar_texi/tar.texi(,6869) './a'\''single'\''quote'
+../tar_texi/tar.texi(,6870) './a"double"quote'
+../tar_texi/tar.texi(,6871) './a\backslash'
+../tar_texi/tar.texi(,6872) './a tab'
+../tar_texi/tar.texi(,6873) './a
+../tar_texi/tar.texi(,6874) newline'
+../tar_texi/tar.texi(,6875) @end group
+../tar_texi/tar.texi(,6876) @end smallexample
+../tar_texi/tar.texi(,6877)
+../tar_texi/tar.texi(,6878) @item c
+../tar_texi/tar.texi(,6879) Use the notation of the C programming language.
All names are
+../tar_texi/tar.texi(,6880) enclosed in double quotes. Control characters are
quoted using
+../tar_texi/tar.texi(,6881) backslash notations, double quotes are represented
as @samp{\"},
+../tar_texi/tar.texi(,6882) backslash characters are represented as @samp{\\}.
Single quotes and
+../tar_texi/tar.texi(,6883) spaces are not quoted:
+../tar_texi/tar.texi(,6884)
+../tar_texi/tar.texi(,6885) @smallexample
+../tar_texi/tar.texi(,6886) @group
+../tar_texi/tar.texi(,6887) $ @kbd{tar tf arch.tar --quoting-style=c}
+../tar_texi/tar.texi(,6888) "./"
+../tar_texi/tar.texi(,6889) "./a space"
+../tar_texi/tar.texi(,6890) "./a'single'quote"
+../tar_texi/tar.texi(,6891) "./a\"double\"quote"
+../tar_texi/tar.texi(,6892) "./a\\backslash"
+../tar_texi/tar.texi(,6893) "./a\ttab"
+../tar_texi/tar.texi(,6894) "./a\nnewline"
+../tar_texi/tar.texi(,6895) @end group
+../tar_texi/tar.texi(,6896) @end smallexample
+../tar_texi/tar.texi(,6897)
+../tar_texi/tar.texi(,6898) @item escape
+../tar_texi/tar.texi(,6899) Control characters are printed using backslash
notation, a space is
+../tar_texi/tar.texi(,6900) printed as @samp{\ } and a backslash as @samp{\\}.
This is the
+../tar_texi/tar.texi(,6901) default quoting style, unless it was changed when
configured the
+../tar_texi/tar.texi(,6902) package.
+../tar_texi/tar.texi(,6903)
+../tar_texi/tar.texi(,6904) @smallexample
+../tar_texi/tar.texi(,6905) @group
+../tar_texi/tar.texi(,6906) $ @kbd{tar tf arch.tar --quoting-style=escape}
+../tar_texi/tar.texi(,6907) ./
+../tar_texi/tar.texi(,6908) ./a space
+../tar_texi/tar.texi(,6909) ./a'single'quote
+../tar_texi/tar.texi(,6910) ./a"double"quote
+../tar_texi/tar.texi(,6911) ./a\\backslash
+../tar_texi/tar.texi(,6912) ./a\ttab
+../tar_texi/tar.texi(,6913) ./a\nnewline
+../tar_texi/tar.texi(,6914) @end group
+../tar_texi/tar.texi(,6915) @end smallexample
+../tar_texi/tar.texi(,6916)
+../tar_texi/tar.texi(,6917) @item locale
+../tar_texi/tar.texi(,6918) Control characters, single quote and backslash are
printed using
+../tar_texi/tar.texi(,6919) backslash notation. All names are quoted using
left and right
+../tar_texi/tar.texi(,6920) quotation marks, appropriate to the current
locale. If it does not
+../tar_texi/tar.texi(,6921) define quotation marks, use @samp{`} as left and
@samp{'} as right
+../tar_texi/tar.texi(,6922) quotation marks. Any occurrences of the right
quotation mark in a
+../tar_texi/tar.texi(,6923) name are escaped with @samp{\}, for example:
+../tar_texi/tar.texi(,6924)
+../tar_texi/tar.texi(,6925) For example:
+../tar_texi/tar.texi(,6926)
+../tar_texi/tar.texi(,6927) @smallexample
+../tar_texi/tar.texi(,6928) @group
+../tar_texi/tar.texi(,6929) $ @kbd{tar tf arch.tar --quoting-style=locale}
+../tar_texi/tar.texi(,6930) `./'
+../tar_texi/tar.texi(,6931) `./a space'
+../tar_texi/tar.texi(,6932) `./a\'single\'quote'
+../tar_texi/tar.texi(,6933) `./a"double"quote'
+../tar_texi/tar.texi(,6934) `./a\\backslash'
+../tar_texi/tar.texi(,6935) `./a\ttab'
+../tar_texi/tar.texi(,6936) `./a\nnewline'
+../tar_texi/tar.texi(,6937) @end group
+../tar_texi/tar.texi(,6938) @end smallexample
+../tar_texi/tar.texi(,6939)
+../tar_texi/tar.texi(,6940) @item clocale
+../tar_texi/tar.texi(,6941) Same as @samp{locale}, but @samp{"} is used for
both left and right
+../tar_texi/tar.texi(,6942) quotation marks, if not provided by the currently
selected locale:
+../tar_texi/tar.texi(,6943)
+../tar_texi/tar.texi(,6944) @smallexample
+../tar_texi/tar.texi(,6945) @group
+../tar_texi/tar.texi(,6946) $ @kbd{tar tf arch.tar --quoting-style=clocale}
+../tar_texi/tar.texi(,6947) "./"
+../tar_texi/tar.texi(,6948) "./a space"
+../tar_texi/tar.texi(,6949) "./a'single'quote"
+../tar_texi/tar.texi(,6950) "./a\"double\"quote"
+../tar_texi/tar.texi(,6951) "./a\\backslash"
+../tar_texi/tar.texi(,6952) "./a\ttab"
+../tar_texi/tar.texi(,6953) "./a\nnewline"
+../tar_texi/tar.texi(,6954) @end group
+../tar_texi/tar.texi(,6955) @end smallexample
+../tar_texi/tar.texi(,6956) @end table
+../tar_texi/tar.texi(,6957)
+../tar_texi/tar.texi(,6958) You can specify which characters should be quoted
in addition to those
+../tar_texi/tar.texi(,6959) implied by the current quoting style:
+../tar_texi/tar.texi(,6960)
+../tar_texi/tar.texi(,6961) @table @option
+../tar_texi/tar.texi(,6962) @item address@hidden
+../tar_texi/tar.texi(,6963) Always quote characters from @var{string}, even if
the selected
+../tar_texi/tar.texi(,6964) quoting style would not quote them.
+../tar_texi/tar.texi(,6965) @end table
+../tar_texi/tar.texi(,6966)
+../tar_texi/tar.texi(,6967) For example, using @samp{escape} quoting (compare
with the usual
+../tar_texi/tar.texi(,6968) escape listing above):
+../tar_texi/tar.texi(,6969)
+../tar_texi/tar.texi(,6970) @smallexample
+../tar_texi/tar.texi(,6971) @group
+../tar_texi/tar.texi(,6972) $ @kbd{tar tf arch.tar --quoting-style=escape
--quote-chars=' "'}
+../tar_texi/tar.texi(,6973) ./
+../tar_texi/tar.texi(,6974) ./a\ space
+../tar_texi/tar.texi(,6975) ./a'single'quote
+../tar_texi/tar.texi(,6976) ./a\"double\"quote
+../tar_texi/tar.texi(,6977) ./a\\backslash
+../tar_texi/tar.texi(,6978) ./a\ttab
+../tar_texi/tar.texi(,6979) ./a\nnewline
+../tar_texi/tar.texi(,6980) @end group
+../tar_texi/tar.texi(,6981) @end smallexample
+../tar_texi/tar.texi(,6982)
+../tar_texi/tar.texi(,6983) To disable quoting of such additional characters,
use the following
+../tar_texi/tar.texi(,6984) option:
+../tar_texi/tar.texi(,6985)
+../tar_texi/tar.texi(,6986) @table @option
+../tar_texi/tar.texi(,6987) @item address@hidden
+../tar_texi/tar.texi(,6988) Remove characters listed in @var{string} from the
list of quoted
+../tar_texi/tar.texi(,6989) characters set by the previous
@option{--quote-chars} option.
+../tar_texi/tar.texi(,6990) @end table
+../tar_texi/tar.texi(,6991)
+../tar_texi/tar.texi(,6992) This option is particularly useful if you have
added
+../tar_texi/tar.texi(,6993) @option{--quote-chars} to your @env{TAR_OPTIONS}
(@pxref{TAR_OPTIONS})
+../tar_texi/tar.texi(,6994) and wish to disable it for the current invocation.
+../tar_texi/tar.texi(,6995)
+../tar_texi/tar.texi(,6996) Note, that @option{--no-quote-chars} does
@emph{not} disable those
+../tar_texi/tar.texi(,6997) characters that are quoted by default in the
selected quoting style.
+../tar_texi/tar.texi(,6998)
+../tar_texi/tar.texi(,6999) @node transform
+../tar_texi/tar.texi(,7000) @section Modifying File and Member Names
+../tar_texi/tar.texi(,7001)
+../tar_texi/tar.texi(,7002) @command{Tar} archives contain detailed
information about files stored
+../tar_texi/tar.texi(,7003) in them and full file names are part of that
information. When
+../tar_texi/tar.texi(,7004) storing file to an archive, its file name is
recorded in the archive
+../tar_texi/tar.texi(,7005) along with the actual file contents. When
restoring from an archive,
+../tar_texi/tar.texi(,7006) a file is created on disk with exactly the same
name as that stored
+../tar_texi/tar.texi(,7007) in the archive. In the majority of cases this is
the desired behavior
+../tar_texi/tar.texi(,7008) of a file archiver. However, there are some cases
when it is not.
+../tar_texi/tar.texi(,7009)
+../tar_texi/tar.texi(,7010) First of all, it is often unsafe to extract
archive members with
+../tar_texi/tar.texi(GNUTAR,7011) absolute file names or those that begin with
a @file{../}. @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,7012) takes special precautions when extracting such
names and provides a
+../tar_texi/tar.texi(,7013) special option for handling them, which is
described in
+../tar_texi/tar.texi(,7014) @ref{absolute}.
+../tar_texi/tar.texi(,7015)
+../tar_texi/tar.texi(,7016) Secondly, you may wish to extract file names
without some leading
+../tar_texi/tar.texi(,7017) directory components, or with otherwise modified
names. In other
+../tar_texi/tar.texi(,7018) cases it is desirable to store files under
differing names in the
+../tar_texi/tar.texi(,7019) archive.
+../tar_texi/tar.texi(,7020)
+../tar_texi/tar.texi(GNUTAR,7021) @acronym{GNU} @command{tar} provides two
options for these needs.
+../tar_texi/tar.texi(,7022)
+../tar_texi/tar.texi(,7023) @table @option
+../tar_texi/tar.texi(,7024) @opindex strip-components
+../tar_texi/tar.texi(,7025) @item address@hidden
+../tar_texi/tar.texi(,7026) Strip given @var{number} of leading components
from file names before
+../tar_texi/tar.texi(,7027) extraction.
+../tar_texi/tar.texi(,7028) @end table
+../tar_texi/tar.texi(,7029)
+../tar_texi/tar.texi(,7030) For example, suppose you have archived whole
@file{/usr} hierarchy to
+../tar_texi/tar.texi(,7031) a tar archive named @file{usr.tar}. Among other
files, this archive
+../tar_texi/tar.texi(,7032) contains @file{usr/include/stdlib.h}, which you
wish to extract to
+../tar_texi/tar.texi(,7033) the current working directory. To do so, you type:
+../tar_texi/tar.texi(,7034)
+../tar_texi/tar.texi(,7035) @smallexample
+../tar_texi/tar.texi(,7036) $ @kbd{tar -xf usr.tar --strip=2
usr/include/stdlib.h}
+../tar_texi/tar.texi(,7037) @end smallexample
+../tar_texi/tar.texi(,7038)
+../tar_texi/tar.texi(,7039) The option @option{--strip=2} instructs
@command{tar} to strip the
+../tar_texi/tar.texi(,7040) two leading components (@file{usr/} and
@file{include/}) off the file
+../tar_texi/tar.texi(,7041) name.
+../tar_texi/tar.texi(,7042)
+../tar_texi/tar.texi(,7043) If you add to the above invocation
@option{--verbose} (@option{-v})
+../tar_texi/tar.texi(,7044) option, you will note that the verbose listing
still contains the
+../tar_texi/tar.texi(,7045) full file name, with the two removed components
still in place. This
+../tar_texi/tar.texi(,7046) can be inconvenient, so @command{tar} provides a
special option for
+../tar_texi/tar.texi(,7047) altering this behavior:
+../tar_texi/tar.texi(,7048)
+../tar_texi/tar.texi(,7049) @anchor{show-transformed-names}
+../tar_texi/tar.texi(,7050) @table @option
+../tar_texi/tar.texi(,7051) @opindex show-transformed-names
+../tar_texi/tar.texi(,7052) @item --show-transformed-names
+../tar_texi/tar.texi(,7053) Display file or member names with all requested
transformations
+../tar_texi/tar.texi(,7054) applied.
+../tar_texi/tar.texi(,7055) @end table
+../tar_texi/tar.texi(,7056)
+../tar_texi/tar.texi(,7057) @noindent
+../tar_texi/tar.texi(,7058) For example:
+../tar_texi/tar.texi(,7059)
+../tar_texi/tar.texi(,7060) @smallexample
+../tar_texi/tar.texi(,7061) @group
+../tar_texi/tar.texi(,7062) $ @kbd{tar -xf usr.tar -v --strip=2
usr/include/stdlib.h}
+../tar_texi/tar.texi(,7063) usr/include/stdlib.h
+../tar_texi/tar.texi(,7064) $ @kbd{tar -xf usr.tar -v --strip=2
--show-transformed usr/include/stdlib.h}
+../tar_texi/tar.texi(,7065) stdlib.h
+../tar_texi/tar.texi(,7066) @end group
+../tar_texi/tar.texi(,7067) @end smallexample
+../tar_texi/tar.texi(,7068)
+../tar_texi/tar.texi(,7069) Notice that in both cases the file is
@file{stdlib.h} extracted to the
+../tar_texi/tar.texi(,7070) current working directory,
@option{--show-transformed-names} affects
+../tar_texi/tar.texi(,7071) only the way its name is displayed.
+../tar_texi/tar.texi(,7072)
+../tar_texi/tar.texi(,7073) This option is especially useful for verifying
whether the invocation
+../tar_texi/tar.texi(,7074) will have the desired effect. Thus, before running
+../tar_texi/tar.texi(,7075)
+../tar_texi/tar.texi(,7076) @smallexample
+../tar_texi/tar.texi(,7077) $ @kbd{tar -x address@hidden
+../tar_texi/tar.texi(,7078) @end smallexample
+../tar_texi/tar.texi(,7079)
+../tar_texi/tar.texi(,7080) @noindent
+../tar_texi/tar.texi(,7081) it is often advisable to run
+../tar_texi/tar.texi(,7082)
+../tar_texi/tar.texi(,7083) @smallexample
+../tar_texi/tar.texi(,7084) $ @kbd{tar -t -v --show-transformed address@hidden
+../tar_texi/tar.texi(,7085) @end smallexample
+../tar_texi/tar.texi(,7086)
+../tar_texi/tar.texi(,7087) @noindent
+../tar_texi/tar.texi(,7088) to make sure the command will produce the intended
results.
+../tar_texi/tar.texi(,7089)
+../tar_texi/tar.texi(,7090) In case you need to apply more complex
modifications to the file name,
+../tar_texi/tar.texi(GNUTAR,7091) @acronym{GNU} @command{tar} provides a
general-purpose transformation option:
+../tar_texi/tar.texi(,7092)
+../tar_texi/tar.texi(,7093) @table @option
+../tar_texi/tar.texi(,7094) @opindex transform
+../tar_texi/tar.texi(,7095) @item address@hidden
+../tar_texi/tar.texi(,7096) Modify file names using supplied @var{expression}.
+../tar_texi/tar.texi(,7097) @end table
+../tar_texi/tar.texi(,7098)
+../tar_texi/tar.texi(,7099) @noindent
+../tar_texi/tar.texi(,7100) The @var{expression} is a @command{sed}-like
replace expression of the
+../tar_texi/tar.texi(,7101) form:
+../tar_texi/tar.texi(,7102)
+../tar_texi/tar.texi(,7103) @smallexample
+../tar_texi/tar.texi(,7104) s/@var{regexp}/@var{replace}/address@hidden
+../tar_texi/tar.texi(,7105) @end smallexample
+../tar_texi/tar.texi(,7106)
+../tar_texi/tar.texi(,7107) @noindent
+../tar_texi/tar.texi(,7108) where @var{regexp} is a @dfn{regular expression},
@var{replace} is a
+../tar_texi/tar.texi(,7109) replacement for each file name part that matches
@var{regexp}. Both
+../tar_texi/tar.texi(,7110) @var{regexp} and @var{replace} are described in
detail in
+../tar_texi/tar.texi(,7111) @ref{The "s" Command, The "s" Command, The `s'
Command, sed, GNU sed}.
+../tar_texi/tar.texi(,7112)
+../tar_texi/tar.texi(,7113) Supported @var{flags} are:
+../tar_texi/tar.texi(,7114)
+../tar_texi/tar.texi(,7115) @table @samp
+../tar_texi/tar.texi(,7116) @item g
+../tar_texi/tar.texi(,7117) Apply the replacement to @emph{all} matches to the
@var{regexp}, not
+../tar_texi/tar.texi(,7118) just the first.
+../tar_texi/tar.texi(,7119)
+../tar_texi/tar.texi(,7120) @item i
+../tar_texi/tar.texi(,7121) Use case-insensitive matching
+../tar_texi/tar.texi(,7122)
+../tar_texi/tar.texi(,7123) @item x
+../tar_texi/tar.texi(,7124) @var{regexp} is an @dfn{extended regular
expression} (@pxref{Extended
+../tar_texi/tar.texi(,7125) regexps, Extended regular expressions, Extended
regular expressions,
+../tar_texi/tar.texi(,7126) sed, GNU sed}).
+../tar_texi/tar.texi(,7127)
+../tar_texi/tar.texi(,7128) @item @var{number}
+../tar_texi/tar.texi(,7129) Only replace the @var{number}th match of the
@var{regexp}.
+../tar_texi/tar.texi(,7130)
+../tar_texi/tar.texi(,7131) Note: the @var{posix} standard does not specify
what should happen
+../tar_texi/tar.texi(GNUTAR,7132) when you mix the @samp{g} and @var{number}
modifiers. @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,7133) follows the GNU @command{sed} implementation in
this regard, so
+../tar_texi/tar.texi(,7134) the the interaction is defined to be: ignore
matches before the
+../tar_texi/tar.texi(,7135) @var{number}th, and then match and replace all
matches from the
+../tar_texi/tar.texi(,7136) @var{number}th on.
+../tar_texi/tar.texi(,7137)
+../tar_texi/tar.texi(,7138) @end table
+../tar_texi/tar.texi(,7139)
+../tar_texi/tar.texi(,7140) Any delimiter can be used in lieue of @samp{/},
the only requirement being
+../tar_texi/tar.texi(,7141) that it be used consistently throughout the
expression. For example,
+../tar_texi/tar.texi(,7142) the following two expressions are equivalent:
+../tar_texi/tar.texi(,7143)
+../tar_texi/tar.texi(,7144) @smallexample
+../tar_texi/tar.texi(,7145) @group
+../tar_texi/tar.texi(,7146) s/one/two/
+../tar_texi/tar.texi(,7147) s,one,two,
+../tar_texi/tar.texi(,7148) @end group
+../tar_texi/tar.texi(,7149) @end smallexample
+../tar_texi/tar.texi(,7150)
+../tar_texi/tar.texi(,7151) Changing delimiters is often useful when the
@var{regex} contains
+../tar_texi/tar.texi(,7152) slashes. For example, it is more convenient to
write @code{s,/,-,} than
+../tar_texi/tar.texi(,7153) @code{s/\//-/}.
+../tar_texi/tar.texi(,7154)
+../tar_texi/tar.texi(,7155) Here are several examples of @option{--transform}
usage:
+../tar_texi/tar.texi(,7156)
+../tar_texi/tar.texi(,7157) @enumerate
+../tar_texi/tar.texi(,7158) @item Extract @file{usr/} hierarchy into
@file{usr/local/}:
+../tar_texi/tar.texi(,7159)
+../tar_texi/tar.texi(,7160) @smallexample
+../tar_texi/tar.texi(,7161) $ @kbd{tar --transform='s,usr/,usr/local/,' -x -f
arch.tar}
+../tar_texi/tar.texi(,7162) @end smallexample
+../tar_texi/tar.texi(,7163)
+../tar_texi/tar.texi(,7164) @item Strip two leading directory components
(equivalent to
+../tar_texi/tar.texi(,7165) @option{--strip-components=2}):
+../tar_texi/tar.texi(,7166)
+../tar_texi/tar.texi(,7167) @smallexample
+../tar_texi/tar.texi(,7168) $ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f
arch.tar}
+../tar_texi/tar.texi(,7169) @end smallexample
+../tar_texi/tar.texi(,7170)
+../tar_texi/tar.texi(,7171) @item Prepend @file{/prefix/} to each file name:
+../tar_texi/tar.texi(,7172)
+../tar_texi/tar.texi(,7173) @smallexample
+../tar_texi/tar.texi(,7174) $ @kbd{tar --transform 's,^,/prefix/,' -x -f
arch.tar}
+../tar_texi/tar.texi(,7175) @end smallexample
+../tar_texi/tar.texi(,7176)
+../tar_texi/tar.texi(,7177) @item Convert each file name to lower case:
+../tar_texi/tar.texi(,7178)
+../tar_texi/tar.texi(,7179) @smallexample
+../tar_texi/tar.texi(,7180) $ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+../tar_texi/tar.texi(,7181) @end smallexample
+../tar_texi/tar.texi(,7182)
+../tar_texi/tar.texi(,7183) @end enumerate
+../tar_texi/tar.texi(,7184)
+../tar_texi/tar.texi(,7185) Unlike @option{--strip-components},
@option{--transform} can be used
+../tar_texi/tar.texi(GNUTAR,7186) in any @acronym{GNU} @command{tar} operation
mode. For example, the following command
+../tar_texi/tar.texi(,7187) adds files to the archive while replacing the
leading @file{usr/}
+../tar_texi/tar.texi(,7188) component with @file{var/}:
+../tar_texi/tar.texi(,7189)
+../tar_texi/tar.texi(,7190) @smallexample
+../tar_texi/tar.texi(,7191) $ @kbd{tar -cf arch.tar
--transform='s,^usr/,var/,' /}
+../tar_texi/tar.texi(,7192) @end smallexample
+../tar_texi/tar.texi(,7193)
+../tar_texi/tar.texi(,7194) To test @option{--transform} effect we suggest
using
+../tar_texi/tar.texi(,7195) @option{--show-transformed-names} option:
+../tar_texi/tar.texi(,7196)
+../tar_texi/tar.texi(,7197) @smallexample
+../tar_texi/tar.texi(,7198) $ @kbd{tar -cf arch.tar
--transform='s,^usr/,var/,' \
+../tar_texi/tar.texi(,7199) --verbose --show-transformed-names /}
+../tar_texi/tar.texi(,7200) @end smallexample
+../tar_texi/tar.texi(,7201)
+../tar_texi/tar.texi(,7202) If both @option{--strip-components} and
@option{--transform} are used
+../tar_texi/tar.texi(,7203) together, then @option{--transform} is applied
first, and the required
+../tar_texi/tar.texi(,7204) number of components is then stripped from its
result.
+../tar_texi/tar.texi(,7205)
+../tar_texi/tar.texi(,7206) @node after
+../tar_texi/tar.texi(,7207) @section Operating Only on New Files
+../tar_texi/tar.texi(UNREVISED,7208) @quotation
+../tar_texi/tar.texi(UNREVISED,7208) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7208) @end quotation
+../tar_texi/tar.texi(UNREVISED,7208)
+../tar_texi/tar.texi(,7209)
+../tar_texi/tar.texi(,7210) @cindex Excluding file by age
+../tar_texi/tar.texi(,7211) @cindex Data Modification time, excluding files by
+../tar_texi/tar.texi(,7212) @cindex Modification time, excluding files by
+../tar_texi/tar.texi(,7213) @cindex Age, excluding files by
+../tar_texi/tar.texi(,7214) The @address@hidden (@address@hidden,
+../tar_texi/tar.texi(,7215) @option{-N @var{date}}) option causes
@command{tar} to only work on
+../tar_texi/tar.texi(,7216) files whose data modification or status change
times are newer than
+../tar_texi/tar.texi(,7217) the @var{date} given. If @var{date} starts with
@samp{/} or @samp{.},
+../tar_texi/tar.texi(,7218) it is taken to be a file name; the data
modification time of that file
+../tar_texi/tar.texi(,7219) is used as the date. If you use this option when
creating or appending
+../tar_texi/tar.texi(,7220) to an archive, the archive will only include new
files. If you use
+../tar_texi/tar.texi(,7221) @option{--after-date} when extracting an archive,
@command{tar} will
+../tar_texi/tar.texi(,7222) only extract files newer than the @var{date} you
specify.
+../tar_texi/tar.texi(,7223)
+../tar_texi/tar.texi(,7224) If you only want @command{tar} to make the date
comparison based on
+../tar_texi/tar.texi(,7225) modification of the file's data (rather than status
+../tar_texi/tar.texi(,7226) changes), then use the @address@hidden option.
+../tar_texi/tar.texi(,7227)
+../tar_texi/tar.texi(,7228) You may use these options with any operation.
Note that these options
+../tar_texi/tar.texi(,7229) differ from the @option{--update} (@option{-u})
operation in that they
+../tar_texi/tar.texi(,7230) allow you to specify a particular date against
which @command{tar} can
+../tar_texi/tar.texi(,7231) compare when deciding whether or not to archive
the files.
+../tar_texi/tar.texi(,7232)
+../tar_texi/tar.texi(,7233) @table @option
+../tar_texi/tar.texi(,7234) @opindex after-date
+../tar_texi/tar.texi(,7235) @opindex newer
+../tar_texi/tar.texi(,7236) @item address@hidden
+../tar_texi/tar.texi(,7237) @itemx address@hidden
+../tar_texi/tar.texi(,7238) @itemx -N @var{date}
+../tar_texi/tar.texi(,7239) Only store files newer than @var{date}.
+../tar_texi/tar.texi(,7240)
+../tar_texi/tar.texi(,7241) Acts on files only if their data modification or
status change times are
+../tar_texi/tar.texi(,7242) later than @var{date}. Use in conjunction with
any operation.
+../tar_texi/tar.texi(,7243)
+../tar_texi/tar.texi(,7244) If @var{date} starts with @samp{/} or @samp{.}, it
is taken to be a file
+../tar_texi/tar.texi(,7245) name; the data modification time of that file is
used as the date.
+../tar_texi/tar.texi(,7246)
+../tar_texi/tar.texi(,7247) @opindex newer-mtime
+../tar_texi/tar.texi(,7248) @item address@hidden
+../tar_texi/tar.texi(,7249) Acts like @option{--after-date}, but only looks at
data modification times.
+../tar_texi/tar.texi(,7250) @end table
+../tar_texi/tar.texi(,7251)
+../tar_texi/tar.texi(,7252) These options limit @command{tar} to operate only
on files which have
+../tar_texi/tar.texi(,7253) been modified after the date specified. A file's
status is considered to have
+../tar_texi/tar.texi(,7254) changed if its contents have been modified, or if
its owner,
+../tar_texi/tar.texi(,7255) permissions, and so forth, have been changed.
(For more information on
+../tar_texi/tar.texi(,7256) how to specify a date, see @ref{Date input
formats}; remember that the
+../tar_texi/tar.texi(,7257) entire date argument must be quoted if it contains
any spaces.)
+../tar_texi/tar.texi(,7258)
+../tar_texi/tar.texi(,7259) Gurus would say that @option{--after-date} tests
both the data
+../tar_texi/tar.texi(,7260) modification time (@code{mtime}, the time the
contents of the file
+../tar_texi/tar.texi(,7261) were last modified) and the status change time
(@code{ctime}, the time
+../tar_texi/tar.texi(,7262) the file's status was last changed: owner,
permissions, etc.@:)
+../tar_texi/tar.texi(,7263) fields, while @option{--newer-mtime} tests only
the @code{mtime}
+../tar_texi/tar.texi(,7264) field.
+../tar_texi/tar.texi(,7265)
+../tar_texi/tar.texi(,7266) To be precise, @option{--after-date} checks
@emph{both} @code{mtime} and
+../tar_texi/tar.texi(,7267) @code{ctime} and processes the file if either one
is more recent than
+../tar_texi/tar.texi(,7268) @var{date}, while @option{--newer-mtime} only
checks @code{mtime} and
+../tar_texi/tar.texi(,7269) disregards @code{ctime}. Neither does it use
@code{atime} (the last time the
+../tar_texi/tar.texi(,7270) contents of the file were looked at).
+../tar_texi/tar.texi(,7271)
+../tar_texi/tar.texi(,7272) Date specifiers can have embedded spaces. Because
of this, you may need
+../tar_texi/tar.texi(,7273) to quote date arguments to keep the shell from
parsing them as separate
+../tar_texi/tar.texi(,7274) arguments. For example, the following command
will add to the archive
+../tar_texi/tar.texi(,7275) all the files modified less than two days ago:
+../tar_texi/tar.texi(,7276)
+../tar_texi/tar.texi(,7277) @smallexample
+../tar_texi/tar.texi(,7278) $ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
+../tar_texi/tar.texi(,7279) @end smallexample
+../tar_texi/tar.texi(,7280)
+../tar_texi/tar.texi(,7281) When any of these options is used with the option
@option{--verbose}
+../tar_texi/tar.texi(GNUTAR,7282) (@pxref{verbose tutorial}) @acronym{GNU}
@command{tar} will try to convert the specified
+../tar_texi/tar.texi(,7283) date back to its textual representation and
compare that with the
+../tar_texi/tar.texi(,7284) one given with the option. If the two dates
differ, @command{tar} will
+../tar_texi/tar.texi(,7285) print a warning saying what date it will use.
This is to help user
+../tar_texi/tar.texi(,7286) ensure he is using the right date. For example:
+../tar_texi/tar.texi(,7287)
+../tar_texi/tar.texi(,7288) @smallexample
+../tar_texi/tar.texi(,7289) @group
+../tar_texi/tar.texi(,7290) $ @kbd{tar -c -f archive.tar --after-date='10 days
ago' .}
+../tar_texi/tar.texi(,7291) tar: Option --after-date: Treating date `10 days
ago' as 2006-06-11
+../tar_texi/tar.texi(,7292) 13:19:37.232434
+../tar_texi/tar.texi(,7293) @end group
+../tar_texi/tar.texi(,7294) @end smallexample
+../tar_texi/tar.texi(,7295)
+../tar_texi/tar.texi(,7296) @quotation
+../tar_texi/tar.texi(,7297) @strong{Please Note:} @option{--after-date} and
@option{--newer-mtime}
+../tar_texi/tar.texi(,7298) should not be used for incremental backups.
@xref{Incremental Dumps},
+../tar_texi/tar.texi(,7299) for proper way of creating incremental backups.
+../tar_texi/tar.texi(,7300) @end quotation
+../tar_texi/tar.texi(,7301)
+../tar_texi/tar.texi(,7302) @node recurse
+../tar_texi/tar.texi(,7303) @section Descending into Directories
+../tar_texi/tar.texi(UNREVISED,7304) @quotation
+../tar_texi/tar.texi(UNREVISED,7304) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7304) @end quotation
+../tar_texi/tar.texi(UNREVISED,7304)
+../tar_texi/tar.texi(,7305) @cindex Avoiding recursion in directories
+../tar_texi/tar.texi(,7306) @cindex Descending directories, avoiding
+../tar_texi/tar.texi(,7307) @cindex Directories, avoiding recursion
+../tar_texi/tar.texi(,7308) @cindex Recursion in directories, avoiding
+../tar_texi/tar.texi(,7309)
+../tar_texi/tar.texi(FIXME,7310) @allow-recursion
+../tar_texi/tar.texi(FIXME,7310) @quote-arg
+../tar_texi/tar.texi(FIXME,7310)
+../tar_texi/tar.texi(,7311)
+../tar_texi/tar.texi(,7312) Usually, @command{tar} will recursively explore
all directories (either
+../tar_texi/tar.texi(,7313) those given on the command line or through the
@option{--files-from}
+../tar_texi/tar.texi(,7314) option) for the various files they contain.
However, you may not always
+../tar_texi/tar.texi(,7315) want @command{tar} to act this way.
+../tar_texi/tar.texi(,7316)
+../tar_texi/tar.texi(,7317) @opindex no-recursion
+../tar_texi/tar.texi(,7318) The @option{--no-recursion} option inhibits
@command{tar}'s recursive descent
+../tar_texi/tar.texi(,7319) into specified directories. If you specify
@option{--no-recursion}, you can
+../tar_texi/tar.texi(,7320) use the @command{find} utility for hunting through
levels of directories to
+../tar_texi/tar.texi(,7321) construct a list of file names which you could
then pass to @command{tar}.
+../tar_texi/tar.texi(,7322) @command{find} allows you to be more selective
when choosing which files to
+../tar_texi/tar.texi(,7323) archive; see @ref{files}, for more information on
using @command{find} with
+../tar_texi/tar.texi(,7324) @command{tar}, or look.
+../tar_texi/tar.texi(,7325)
+../tar_texi/tar.texi(,7326) @table @option
+../tar_texi/tar.texi(,7327) @item --no-recursion
+../tar_texi/tar.texi(,7328) Prevents @command{tar} from recursively descending
directories.
+../tar_texi/tar.texi(,7329)
+../tar_texi/tar.texi(,7330) @opindex recursion
+../tar_texi/tar.texi(,7331) @item --recursion
+../tar_texi/tar.texi(,7332) Requires @command{tar} to recursively descend
directories.
+../tar_texi/tar.texi(,7333) This is the default.
+../tar_texi/tar.texi(,7334) @end table
+../tar_texi/tar.texi(,7335)
+../tar_texi/tar.texi(GNUTAR,7336) When you use @option{--no-recursion},
@acronym{GNU} @command{tar} grabs
+../tar_texi/tar.texi(,7337) directory entries themselves, but does not descend
on them
+../tar_texi/tar.texi(,7338) recursively. Many people use @command{find} for
locating files they
+../tar_texi/tar.texi(,7339) want to back up, and since @command{tar}
@emph{usually} recursively
+../tar_texi/tar.texi(,7340) descends on directories, they have to use the
@address@hidden -type d}}
+../tar_texi/tar.texi(,7341) test in their @command{find} invocation
(@pxref{Type, Type, Type test,
+../tar_texi/tar.texi(,7342) find, Finding Files}), as they usually do not want
all the files in a
+../tar_texi/tar.texi(,7343) directory. They then use the @option{--files-from}
option to archive
+../tar_texi/tar.texi(,7344) the files located via @command{find}.
+../tar_texi/tar.texi(,7345)
+../tar_texi/tar.texi(,7346) The problem when restoring files archived in this
manner is that the
+../tar_texi/tar.texi(,7347) directories themselves are not in the archive; so
the
+../tar_texi/tar.texi(,7348) @option{--same-permissions}
(@option{--preserve-permissions},
+../tar_texi/tar.texi(,7349) @option{-p}) option does not affect them---while
users might really
+../tar_texi/tar.texi(,7350) like it to. Specifying @option{--no-recursion} is
a way to tell
+../tar_texi/tar.texi(,7351) @command{tar} to grab only the directory entries
given to it, adding
+../tar_texi/tar.texi(,7352) no new files on its own. To summarize, if you use
@command{find} to
+../tar_texi/tar.texi(,7353) create a list of files to be stored in an archive,
use it as follows:
+../tar_texi/tar.texi(,7354)
+../tar_texi/tar.texi(,7355) @smallexample
+../tar_texi/tar.texi(,7356) @group
+../tar_texi/tar.texi(,7357) $ @kbd{find @var{dir} @var{tests} | \
+../tar_texi/tar.texi(,7358) tar -cf @var{archive} -T - --no-recursion}
+../tar_texi/tar.texi(,7359) @end group
+../tar_texi/tar.texi(,7360) @end smallexample
+../tar_texi/tar.texi(,7361)
+../tar_texi/tar.texi(,7362) The @option{--no-recursion} option also applies
when extracting: it
+../tar_texi/tar.texi(,7363) causes @command{tar} to extract only the matched
directory entries, not
+../tar_texi/tar.texi(,7364) the files under those directories.
+../tar_texi/tar.texi(,7365)
+../tar_texi/tar.texi(,7366) The @option{--no-recursion} option also affects
how globbing patterns
+../tar_texi/tar.texi(,7367) are interpreted (@pxref{controlling
pattern-matching}).
+../tar_texi/tar.texi(,7368)
+../tar_texi/tar.texi(,7369) The @option{--no-recursion} and
@option{--recursion} options apply to
+../tar_texi/tar.texi(,7370) later options and operands, and can be overridden
by later occurrences
+../tar_texi/tar.texi(,7371) of @option{--no-recursion} and
@option{--recursion}. For example:
+../tar_texi/tar.texi(,7372)
+../tar_texi/tar.texi(,7373) @smallexample
+../tar_texi/tar.texi(,7374) $ @kbd{tar -cf jams.tar --no-recursion grape
--recursion grape/concord}
+../tar_texi/tar.texi(,7375) @end smallexample
+../tar_texi/tar.texi(,7376)
+../tar_texi/tar.texi(,7377) @noindent
+../tar_texi/tar.texi(,7378) creates an archive with one entry for
@file{grape}, and the recursive
+../tar_texi/tar.texi(,7379) contents of @file{grape/concord}, but no entries
under @file{grape}
+../tar_texi/tar.texi(,7380) other than @file{grape/concord}.
+../tar_texi/tar.texi(,7381)
+../tar_texi/tar.texi(,7382) @node one
+../tar_texi/tar.texi(,7383) @section Crossing File System Boundaries
+../tar_texi/tar.texi(,7384) @cindex File system boundaries, not crossing
+../tar_texi/tar.texi(UNREVISED,7385) @quotation
+../tar_texi/tar.texi(UNREVISED,7385) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7385) @end quotation
+../tar_texi/tar.texi(UNREVISED,7385)
+../tar_texi/tar.texi(,7386)
+../tar_texi/tar.texi(,7387) @command{tar} will normally automatically cross
file system boundaries in
+../tar_texi/tar.texi(,7388) order to archive files which are part of a
directory tree. You can
+../tar_texi/tar.texi(,7389) change this behavior by running @command{tar} and
specifying
+../tar_texi/tar.texi(,7390) @option{--one-file-system}. This option only
affects files that are
+../tar_texi/tar.texi(,7391) archived because they are in a directory that is
being archived;
+../tar_texi/tar.texi(,7392) @command{tar} will still archive files explicitly
named on the command line
+../tar_texi/tar.texi(,7393) or through @option{--files-from}, regardless of
where they reside.
+../tar_texi/tar.texi(,7394)
+../tar_texi/tar.texi(,7395) @table @option
+../tar_texi/tar.texi(,7396) @opindex one-file-system
+../tar_texi/tar.texi(,7397) @item --one-file-system
+../tar_texi/tar.texi(,7398) Prevents @command{tar} from crossing file system
boundaries when
+../tar_texi/tar.texi(,7399) archiving. Use in conjunction with any write
operation.
+../tar_texi/tar.texi(,7400) @end table
+../tar_texi/tar.texi(,7401)
+../tar_texi/tar.texi(,7402) The @option{--one-file-system} option causes
@command{tar} to modify its
+../tar_texi/tar.texi(,7403) normal behavior in archiving the contents of
directories. If a file in
+../tar_texi/tar.texi(,7404) a directory is not on the same file system as the
directory itself, then
+../tar_texi/tar.texi(,7405) @command{tar} will not archive that file. If the
file is a directory
+../tar_texi/tar.texi(,7406) itself, @command{tar} will not archive anything
beneath it; in other words,
+../tar_texi/tar.texi(,7407) @command{tar} will not cross mount points.
+../tar_texi/tar.texi(,7408)
+../tar_texi/tar.texi(,7409) This option is useful for making full or
incremental archival backups of
+../tar_texi/tar.texi(,7410) a file system. If this option is used in
conjunction with
+../tar_texi/tar.texi(,7411) @option{--verbose} (@option{-v}), files that are
excluded are
+../tar_texi/tar.texi(,7412) mentioned by name on the standard error.
+../tar_texi/tar.texi(,7413)
+../tar_texi/tar.texi(,7414) @menu
+../tar_texi/tar.texi(,7415) * directory:: Changing Directory
+../tar_texi/tar.texi(,7416) * absolute:: Absolute File Names
+../tar_texi/tar.texi(,7417) @end menu
+../tar_texi/tar.texi(,7418)
+../tar_texi/tar.texi(,7419) @node directory
+../tar_texi/tar.texi(,7420) @subsection Changing the Working Directory
+../tar_texi/tar.texi(UNREVISED,7421) @quotation
+../tar_texi/tar.texi(UNREVISED,7421) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7421) @end quotation
+../tar_texi/tar.texi(UNREVISED,7421)
+../tar_texi/tar.texi(,7422)
+../tar_texi/tar.texi(FIXME,7424) @allow-recursion
+../tar_texi/tar.texi(FIXME,7424) @quote-arg
+../tar_texi/tar.texi(FIXME,7424)
+../tar_texi/tar.texi(,7425)
+../tar_texi/tar.texi(,7426) @cindex Changing directory mid-stream
+../tar_texi/tar.texi(,7427) @cindex Directory, changing mid-stream
+../tar_texi/tar.texi(,7428) @cindex Working directory, specifying
+../tar_texi/tar.texi(,7429) To change the working directory in the middle of a
list of file names,
+../tar_texi/tar.texi(,7430) either on the command line or in a file specified
using
+../tar_texi/tar.texi(,7431) @option{--files-from} (@option{-T}), use
@option{--directory} (@option{-C}).
+../tar_texi/tar.texi(,7432) This will change the working directory to the
specified directory
+../tar_texi/tar.texi(,7433) after that point in the list.
+../tar_texi/tar.texi(,7434)
+../tar_texi/tar.texi(,7435) @table @option
+../tar_texi/tar.texi(,7436) @opindex directory
+../tar_texi/tar.texi(,7437) @item address@hidden
+../tar_texi/tar.texi(,7438) @itemx -C @var{directory}
+../tar_texi/tar.texi(,7439) Changes the working directory in the middle of a
command line.
+../tar_texi/tar.texi(,7440) @end table
+../tar_texi/tar.texi(,7441)
+../tar_texi/tar.texi(,7442) For example,
+../tar_texi/tar.texi(,7443)
+../tar_texi/tar.texi(,7444) @smallexample
+../tar_texi/tar.texi(,7445) $ @kbd{tar -c -f jams.tar grape prune -C food
cherry}
+../tar_texi/tar.texi(,7446) @end smallexample
+../tar_texi/tar.texi(,7447)
+../tar_texi/tar.texi(,7448) @noindent
+../tar_texi/tar.texi(,7449) will place the files @file{grape} and @file{prune}
from the current
+../tar_texi/tar.texi(,7450) directory into the archive @file{jams.tar},
followed by the file
+../tar_texi/tar.texi(,7451) @file{cherry} from the directory @file{food}.
This option is especially
+../tar_texi/tar.texi(,7452) useful when you have several widely separated
files that you want to
+../tar_texi/tar.texi(,7453) store in the same archive.
+../tar_texi/tar.texi(,7454)
+../tar_texi/tar.texi(,7455) Note that the file @file{cherry} is recorded in
the archive under the
+../tar_texi/tar.texi(,7456) precise name @file{cherry}, @emph{not}
@file{food/cherry}. Thus, the
+../tar_texi/tar.texi(,7457) archive will contain three files that all appear
to have come from the
+../tar_texi/tar.texi(,7458) same directory; if the archive is extracted with
plain @samp{tar
+../tar_texi/tar.texi(,7459) --extract}, all three files will be written in the
current directory.
+../tar_texi/tar.texi(,7460)
+../tar_texi/tar.texi(,7461) Contrast this with the command,
+../tar_texi/tar.texi(,7462)
+../tar_texi/tar.texi(,7463) @smallexample
+../tar_texi/tar.texi(,7464) $ @kbd{tar -c -f jams.tar grape prune -C food
red/cherry}
+../tar_texi/tar.texi(,7465) @end smallexample
+../tar_texi/tar.texi(,7466)
+../tar_texi/tar.texi(,7467) @noindent
+../tar_texi/tar.texi(,7468) which records the third file in the archive under
the name
+../tar_texi/tar.texi(,7469) @file{red/cherry} so that, if the archive is
extracted using
+../tar_texi/tar.texi(,7470) @samp{tar --extract}, the third file will be
written in a subdirectory
+../tar_texi/tar.texi(,7471) named @file{orange-colored}.
+../tar_texi/tar.texi(,7472)
+../tar_texi/tar.texi(,7473) You can use the @option{--directory} option to
make the archive
+../tar_texi/tar.texi(,7474) independent of the original name of the directory
holding the files.
+../tar_texi/tar.texi(,7475) The following command places the files
@file{/etc/passwd},
+../tar_texi/tar.texi(,7476) @file{/etc/hosts}, and @file{/lib/libc.a} into the
archive
+../tar_texi/tar.texi(,7477) @file{foo.tar}:
+../tar_texi/tar.texi(,7478)
+../tar_texi/tar.texi(,7479) @smallexample
+../tar_texi/tar.texi(,7480) $ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C
/lib libc.a}
+../tar_texi/tar.texi(,7481) @end smallexample
+../tar_texi/tar.texi(,7482)
+../tar_texi/tar.texi(,7483) @noindent
+../tar_texi/tar.texi(,7484) However, the names of the archive members will be
exactly what they were
+../tar_texi/tar.texi(,7485) on the command line: @file{passwd}, @file{hosts},
and @file{libc.a}.
+../tar_texi/tar.texi(,7486) They will not appear to be related by file name to
the original
+../tar_texi/tar.texi(,7487) directories where those files were located.
+../tar_texi/tar.texi(,7488)
+../tar_texi/tar.texi(,7489) Note that @option{--directory} options are
interpreted consecutively. If
+../tar_texi/tar.texi(,7490) @option{--directory} specifies a relative file
name, it is interpreted
+../tar_texi/tar.texi(,7491) relative to the then current directory, which
might not be the same as
+../tar_texi/tar.texi(,7492) the original current working directory of
@command{tar}, due to a previous
+../tar_texi/tar.texi(,7493) @option{--directory} option.
+../tar_texi/tar.texi(,7494)
+../tar_texi/tar.texi(,7495) When using @option{--files-from} (@pxref{files}),
you can put various
+../tar_texi/tar.texi(,7496) @command{tar} options (including @option{-C}) in
the file list. Notice,
+../tar_texi/tar.texi(,7497) however, that in this case the option and its
argument may not be
+../tar_texi/tar.texi(,7498) separated by whitespace. If you use short option,
its argument must
+../tar_texi/tar.texi(,7499) either follow the option letter immediately,
without any intervening
+../tar_texi/tar.texi(,7500) whitespace, or occupy the next line. Otherwise,
if you use long
+../tar_texi/tar.texi(,7501) option, separate its argument by an equal sign.
+../tar_texi/tar.texi(,7502)
+../tar_texi/tar.texi(,7503) For instance, the file list for the above example
will be:
+../tar_texi/tar.texi(,7504)
+../tar_texi/tar.texi(,7505) @smallexample
+../tar_texi/tar.texi(,7506) @group
+../tar_texi/tar.texi(,7507) -C
+../tar_texi/tar.texi(,7508) /etc
+../tar_texi/tar.texi(,7509) passwd
+../tar_texi/tar.texi(,7510) hosts
+../tar_texi/tar.texi(,7511) -C
+../tar_texi/tar.texi(,7512) /lib
+../tar_texi/tar.texi(,7513) libc.a
+../tar_texi/tar.texi(,7514) @end group
+../tar_texi/tar.texi(,7515) @end smallexample
+../tar_texi/tar.texi(,7516)
+../tar_texi/tar.texi(,7517) @noindent
+../tar_texi/tar.texi(,7518) To use it, you would invoke @command{tar} as
follows:
+../tar_texi/tar.texi(,7519)
+../tar_texi/tar.texi(,7520) @smallexample
+../tar_texi/tar.texi(,7521) $ @kbd{tar -c -f foo.tar --files-from list}
+../tar_texi/tar.texi(,7522) @end smallexample
+../tar_texi/tar.texi(,7523)
+../tar_texi/tar.texi(,7524) Notice also that you can only use the short option
variant in the file
+../tar_texi/tar.texi(,7525) list, i.e., always use @option{-C}, not
@option{--directory}.
+../tar_texi/tar.texi(,7526)
+../tar_texi/tar.texi(,7527) The interpretation of @option{--directory} is
disabled by
+../tar_texi/tar.texi(,7528) @option{--null} option.
+../tar_texi/tar.texi(,7529)
+../tar_texi/tar.texi(,7530) @node absolute
+../tar_texi/tar.texi(,7531) @subsection Absolute File Names
+../tar_texi/tar.texi(UNREVISED,7532) @quotation
+../tar_texi/tar.texi(UNREVISED,7532) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7532) @end quotation
+../tar_texi/tar.texi(UNREVISED,7532)
+../tar_texi/tar.texi(,7533)
+../tar_texi/tar.texi(,7534) @table @option
+../tar_texi/tar.texi(,7535) @opindex absolute-names
+../tar_texi/tar.texi(,7536) @item --absolute-names
+../tar_texi/tar.texi(,7537) @itemx -P
+../tar_texi/tar.texi(,7538) Do not strip leading slashes from file names, and
permit file names
+../tar_texi/tar.texi(,7539) containing a @file{..} file name component.
+../tar_texi/tar.texi(,7540) @end table
+../tar_texi/tar.texi(,7541)
+../tar_texi/tar.texi(GNUTAR,7542) By default, @acronym{GNU} @command{tar}
drops a leading @samp{/} on
+../tar_texi/tar.texi(,7543) input or output, and complains about file names
containing a @file{..}
+../tar_texi/tar.texi(,7544) component. This option turns off this behavior.
+../tar_texi/tar.texi(,7545)
+../tar_texi/tar.texi(,7546) When @command{tar} extracts archive members from
an archive, it strips any
+../tar_texi/tar.texi(,7547) leading slashes (@samp{/}) from the member name.
This causes absolute
+../tar_texi/tar.texi(,7548) member names in the archive to be treated as
relative file names. This
+../tar_texi/tar.texi(,7549) allows you to have such members extracted wherever
you want, instead of
+../tar_texi/tar.texi(,7550) being restricted to extracting the member in the
exact directory named
+../tar_texi/tar.texi(,7551) in the archive. For example, if the archive
member has the name
+../tar_texi/tar.texi(,7552) @file{/etc/passwd}, @command{tar} will extract it
as if the name were
+../tar_texi/tar.texi(,7553) really @file{etc/passwd}.
+../tar_texi/tar.texi(,7554)
+../tar_texi/tar.texi(,7555) File names containing @file{..} can cause problems
when extracting, so
+../tar_texi/tar.texi(,7556) @command{tar} normally warns you about such files
when creating an
+../tar_texi/tar.texi(,7557) archive, and rejects attempts to extracts such
files.
+../tar_texi/tar.texi(,7558)
+../tar_texi/tar.texi(,7559) Other @command{tar} programs do not do this. As a
result, if you
+../tar_texi/tar.texi(,7560) create an archive whose member names start with a
slash, they will be
+../tar_texi/tar.texi(GNUTAR,7561) difficult for other people with a
address@hidden @command{tar}
+../tar_texi/tar.texi(GNUTAR,7562) program to use. Therefore, @acronym{GNU}
@command{tar} also strips
+../tar_texi/tar.texi(,7563) leading slashes from member names when putting
members into the
+../tar_texi/tar.texi(,7564) archive. For example, if you ask @command{tar} to
add the file
+../tar_texi/tar.texi(,7565) @file{/bin/ls} to an archive, it will do so, but
the member name will
+../tar_texi/tar.texi(,7566) be @file{bin/address@hidden side effect of this is
that when
+../tar_texi/tar.texi(,7567) @option{--create} is used with @option{--verbose}
the resulting output
+../tar_texi/tar.texi(,7568) is not, generally speaking, the same as the one
you'd get running
+../tar_texi/tar.texi(,7569) @kbd{tar --list} command. This may be important
if you use some
+../tar_texi/tar.texi(,7570) scripts for comparing both outputs. @xref{listing
member and file names},
+../tar_texi/tar.texi(,7571) for the information on how to handle this case.}
+../tar_texi/tar.texi(,7572)
+../tar_texi/tar.texi(,7573) If you use the @option{--absolute-names}
(@option{-P}) option,
+../tar_texi/tar.texi(,7574) @command{tar} will do none of these
transformations.
+../tar_texi/tar.texi(,7575)
+../tar_texi/tar.texi(,7576) To archive or extract files relative to the root
directory, specify
+../tar_texi/tar.texi(,7577) the @option{--absolute-names} (@option{-P}) option.
+../tar_texi/tar.texi(,7578)
+../tar_texi/tar.texi(,7579) Normally, @command{tar} acts on files relative to
the working
+../tar_texi/tar.texi(,7580) directory---ignoring superior directory names when
archiving, and
+../tar_texi/tar.texi(,7581) ignoring leading slashes when extracting.
+../tar_texi/tar.texi(,7582)
+../tar_texi/tar.texi(,7583) When you specify @option{--absolute-names}
(@option{-P}),
+../tar_texi/tar.texi(,7584) @command{tar} stores file names including all
superior directory
+../tar_texi/tar.texi(,7585) names, and preserves leading slashes. If you only
invoked
+../tar_texi/tar.texi(,7586) @command{tar} from the root directory you would
never need the
+../tar_texi/tar.texi(,7587) @option{--absolute-names} option, but using this
option
+../tar_texi/tar.texi(,7588) may be more convenient than switching to root.
+../tar_texi/tar.texi(,7589)
+../tar_texi/tar.texi(FIXME,7591) @allow-recursion
+../tar_texi/tar.texi(FIXME,7591) @quote-arg
+../tar_texi/tar.texi(FIXME,7591)
+../tar_texi/tar.texi(,7592)
+../tar_texi/tar.texi(FIXME,7593) @allow-recursion
+../tar_texi/tar.texi(FIXME,7593) @quote-arg
+../tar_texi/tar.texi(FIXME,7593)
+../tar_texi/tar.texi(,7594)
+../tar_texi/tar.texi(,7595) @table @option
+../tar_texi/tar.texi(,7596) @item --absolute-names
+../tar_texi/tar.texi(,7597) Preserves full file names (including superior
directory names) when
+../tar_texi/tar.texi(,7598) archiving files. Preserves leading slash when
extracting files.
+../tar_texi/tar.texi(,7599)
+../tar_texi/tar.texi(,7600) @end table
+../tar_texi/tar.texi(,7601)
+../tar_texi/tar.texi(FIXME,7602) @allow-recursion
+../tar_texi/tar.texi(FIXME,7602) @quote-arg
+../tar_texi/tar.texi(FIXME,7602)
+../tar_texi/tar.texi(,7603)
+../tar_texi/tar.texi(,7604) @command{tar} prints out a message about removing
the @samp{/} from
+../tar_texi/tar.texi(GNUTAR,7605) file names. This message appears once per
@acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,7606) invocation. It represents something which ought
to be told; ignoring
+../tar_texi/tar.texi(,7607) what it means can cause very serious surprises,
later.
+../tar_texi/tar.texi(,7608)
+../tar_texi/tar.texi(,7609) Some people, nevertheless, do not want to see this
message. Wanting to
+../tar_texi/tar.texi(,7610) play really dangerously, one may of course
redirect @command{tar} standard
+../tar_texi/tar.texi(,7611) error to the sink. For example, under
@command{sh}:
+../tar_texi/tar.texi(,7612)
+../tar_texi/tar.texi(,7613) @smallexample
+../tar_texi/tar.texi(,7614) $ @kbd{tar -c -f archive.tar /home 2> /dev/null}
+../tar_texi/tar.texi(,7615) @end smallexample
+../tar_texi/tar.texi(,7616)
+../tar_texi/tar.texi(,7617) @noindent
+../tar_texi/tar.texi(,7618) Another solution, both nicer and simpler, would be
to change to
+../tar_texi/tar.texi(,7619) the @file{/} directory first, and then avoid
absolute notation.
+../tar_texi/tar.texi(,7620) For example:
+../tar_texi/tar.texi(,7621)
+../tar_texi/tar.texi(,7622) @smallexample
+../tar_texi/tar.texi(,7623) $ @kbd{(cd / && tar -c -f archive.tar home)}
+../tar_texi/tar.texi(,7624) # @i{or}:
+../tar_texi/tar.texi(,7625) $ @kbd{tar -c -f archive.tar -C / home}
+../tar_texi/tar.texi(,7626) @end smallexample
+../tar_texi/tar.texi(,7627)
+../tar_texi/getdate.texi(,1) @c GNU date syntax documentation
+../tar_texi/getdate.texi(,2)
+../tar_texi/getdate.texi(,3) @c Copyright (C) 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002,
+../tar_texi/getdate.texi(,4) @c 2003, 2004, 2005, 2006 Free Software
Foundation, Inc.
+../tar_texi/getdate.texi(,5)
+../tar_texi/getdate.texi(,6) @c Permission is granted to copy, distribute
and/or modify this document
+../tar_texi/getdate.texi(,7) @c under the terms of the GNU Free Documentation
License, Version 1.1 or
+../tar_texi/getdate.texi(,8) @c any later version published by the Free
Software Foundation; with no
+../tar_texi/getdate.texi(,9) @c Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover
+../tar_texi/getdate.texi(,10) @c Texts. A copy of the license is included in
the ``GNU Free
+../tar_texi/getdate.texi(,11) @c Documentation License'' file as part of this
distribution.
+../tar_texi/getdate.texi(,12)
+../tar_texi/getdate.texi(,13) @node Date input formats
+../tar_texi/getdate.texi(,14) @chapter Date input formats
+../tar_texi/getdate.texi(,15)
+../tar_texi/getdate.texi(,16) @cindex date input formats
+../tar_texi/getdate.texi(,17) @findex get_date
+../tar_texi/getdate.texi(,18)
+../tar_texi/getdate.texi(,19) First, a quote:
+../tar_texi/getdate.texi(,20)
+../tar_texi/getdate.texi(,21) @quotation
+../tar_texi/getdate.texi(,22) Our units of temporal measurement, from seconds
on up to months, are so
+../tar_texi/getdate.texi(,23) complicated, asymmetrical and disjunctive so as
to make coherent mental
+../tar_texi/getdate.texi(,24) reckoning in time all but impossible. Indeed,
had some tyrannical god
+../tar_texi/getdate.texi(,25) contrived to enslave our minds to time, to make
it all but impossible
+../tar_texi/getdate.texi(,26) for us to escape subjection to sodden routines
and unpleasant surprises,
+../tar_texi/getdate.texi(,27) he could hardly have done better than handing
down our present system.
+../tar_texi/getdate.texi(,28) It is like a set of trapezoidal building blocks,
with no vertical or
+../tar_texi/getdate.texi(,29) horizontal surfaces, like a language in which
the simplest thought
+../tar_texi/getdate.texi(,30) demands ornate constructions, useless particles
and lengthy
+../tar_texi/getdate.texi(,31) circumlocutions. Unlike the more successful
patterns of language and
+../tar_texi/getdate.texi(,32) science, which enable us to face experience
boldly or at least
+../tar_texi/getdate.texi(,33) level-headedly, our system of temporal
calculation silently and
+../tar_texi/getdate.texi(,34) persistently encourages our terror of time.
+../tar_texi/getdate.texi(,35)
+../tar_texi/getdate.texi(,36) @dots{} It is as though architects had to
measure length in feet, width
+../tar_texi/getdate.texi(,37) in meters and height in ells; as though basic
instruction manuals
+../tar_texi/getdate.texi(,38) demanded a knowledge of five different
languages. It is no wonder then
+../tar_texi/getdate.texi(,39) that we often look into our own immediate past
or future, last Tuesday
+../tar_texi/getdate.texi(,40) or a week from Sunday, with feelings of helpless
confusion. @dots{}
+../tar_texi/getdate.texi(,41)
+../tar_texi/getdate.texi(,42) --- Robert Grudin, @cite{Time and the Art of
Living}.
+../tar_texi/getdate.texi(,43) @end quotation
+../tar_texi/getdate.texi(,44)
+../tar_texi/getdate.texi(,45) This section describes the textual date
representations that @sc{gnu}
+../tar_texi/getdate.texi(,46) programs accept. These are the strings you, as
a user, can supply as
+../tar_texi/getdate.texi(,47) arguments to the various programs. The C
interface (via the
+../tar_texi/getdate.texi(,48) @code{get_date} function) is not described here.
+../tar_texi/getdate.texi(,49)
+../tar_texi/getdate.texi(,50) @menu
+../tar_texi/getdate.texi(,51) * General date syntax:: Common rules.
+../tar_texi/getdate.texi(,52) * Calendar date items:: 19 Dec 1994.
+../tar_texi/getdate.texi(,53) * Time of day items:: 9:20pm.
+../tar_texi/getdate.texi(,54) * Time zone items:: @sc{est},
@sc{pdt}, @sc{gmt}.
+../tar_texi/getdate.texi(,55) * Day of week items:: Monday and
others.
+../tar_texi/getdate.texi(,56) * Relative items in date strings:: next tuesday,
2 years ago.
+../tar_texi/getdate.texi(,57) * Pure numbers in date strings:: 19931219,
1440.
+../tar_texi/getdate.texi(,58) * Seconds since the Epoch:: @@1078100502.
+../tar_texi/getdate.texi(,59) * Specifying time zone rules::
TZ="America/New_York", TZ="UTC0".
+../tar_texi/getdate.texi(,60) * Authors of get_date:: Bellovin,
Eggert, Salz, Berets, et al.
+../tar_texi/getdate.texi(,61) @end menu
+../tar_texi/getdate.texi(,62)
+../tar_texi/getdate.texi(,63)
+../tar_texi/getdate.texi(,64) @node General date syntax
+../tar_texi/getdate.texi(,65) @section General date syntax
+../tar_texi/getdate.texi(,66)
+../tar_texi/getdate.texi(,67) @cindex general date syntax
+../tar_texi/getdate.texi(,68)
+../tar_texi/getdate.texi(,69) @cindex items in date strings
+../tar_texi/getdate.texi(,70) A @dfn{date} is a string, possibly empty,
containing many items
+../tar_texi/getdate.texi(,71) separated by whitespace. The whitespace may be
omitted when no
+../tar_texi/getdate.texi(,72) ambiguity arises. The empty string means the
beginning of today (i.e.,
+../tar_texi/getdate.texi(,73) midnight). Order of the items is immaterial. A
date string may contain
+../tar_texi/getdate.texi(,74) many flavors of items:
+../tar_texi/getdate.texi(,75)
+../tar_texi/getdate.texi(,76) @itemize @bullet
+../tar_texi/getdate.texi(,77) @item calendar date items
+../tar_texi/getdate.texi(,78) @item time of day items
+../tar_texi/getdate.texi(,79) @item time zone items
+../tar_texi/getdate.texi(,80) @item day of the week items
+../tar_texi/getdate.texi(,81) @item relative items
+../tar_texi/getdate.texi(,82) @item pure numbers.
+../tar_texi/getdate.texi(,83) @end itemize
+../tar_texi/getdate.texi(,84)
+../tar_texi/getdate.texi(,85) @noindent We describe each of these item types
in turn, below.
+../tar_texi/getdate.texi(,86)
+../tar_texi/getdate.texi(,87) @cindex numbers, written-out
+../tar_texi/getdate.texi(,88) @cindex ordinal numbers
+../tar_texi/getdate.texi(,89) @findex first @r{in date strings}
+../tar_texi/getdate.texi(,90) @findex next @r{in date strings}
+../tar_texi/getdate.texi(,91) @findex last @r{in date strings}
+../tar_texi/getdate.texi(,92) A few ordinal numbers may be written out in
words in some contexts. This is
+../tar_texi/getdate.texi(,93) most useful for specifying day of the week items
or relative items (see
+../tar_texi/getdate.texi(,94) below). Among the most commonly used ordinal
numbers, the word
+../tar_texi/getdate.texi(,95) @samp{last} stands for @math{-1}, @samp{this}
stands for 0, and
+../tar_texi/getdate.texi(,96) @samp{first} and @samp{next} both stand for 1.
Because the word
+../tar_texi/getdate.texi(,97) @samp{second} stands for the unit of time there
is no way to write the
+../tar_texi/getdate.texi(,98) ordinal number 2, but for convenience
@samp{third} stands for 3,
+../tar_texi/getdate.texi(,99) @samp{fourth} for 4, @samp{fifth} for 5,
+../tar_texi/getdate.texi(,100) @samp{sixth} for 6, @samp{seventh} for 7,
@samp{eighth} for 8,
+../tar_texi/getdate.texi(,101) @samp{ninth} for 9, @samp{tenth} for 10,
@samp{eleventh} for 11 and
+../tar_texi/getdate.texi(,102) @samp{twelfth} for 12.
+../tar_texi/getdate.texi(,103)
+../tar_texi/getdate.texi(,104) @cindex months, written-out
+../tar_texi/getdate.texi(,105) When a month is written this way, it is still
considered to be written
+../tar_texi/getdate.texi(,106) numerically, instead of being ``spelled in
full''; this changes the
+../tar_texi/getdate.texi(,107) allowed strings.
+../tar_texi/getdate.texi(,108)
+../tar_texi/getdate.texi(,109) @cindex language, in dates
+../tar_texi/getdate.texi(,110) In the current implementation, only English is
supported for words and
+../tar_texi/getdate.texi(,111) abbreviations like @samp{AM}, @samp{DST},
@samp{EST}, @samp{first},
+../tar_texi/getdate.texi(,112) @samp{January}, @samp{Sunday}, @samp{tomorrow},
and @samp{year}.
+../tar_texi/getdate.texi(,113)
+../tar_texi/getdate.texi(,114) @cindex language, in dates
+../tar_texi/getdate.texi(,115) @cindex time zone item
+../tar_texi/getdate.texi(,116) The output of the @command{date} command
+../tar_texi/getdate.texi(,117) is not always acceptable as a date string,
+../tar_texi/getdate.texi(,118) not only because of the language problem, but
also because there is no
+../tar_texi/getdate.texi(,119) standard meaning for time zone items like
@samp{IST}. When using
+../tar_texi/getdate.texi(,120) @command{date} to generate a date string
intended to be parsed later,
+../tar_texi/getdate.texi(,121) specify a date format that is independent of
language and that does not
+../tar_texi/getdate.texi(,122) use time zone items other than @samp{UTC} and
@samp{Z}. Here are some
+../tar_texi/getdate.texi(,123) ways to do this:
+../tar_texi/getdate.texi(,124)
+../tar_texi/getdate.texi(,125) @example
+../tar_texi/getdate.texi(,126) $ LC_ALL=C TZ=UTC0 date
+../tar_texi/getdate.texi(,127) Mon Mar 1 00:21:42 UTC 2004
+../tar_texi/getdate.texi(,128) $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+../tar_texi/getdate.texi(,129) 2004-03-01 00:21:42Z
+../tar_texi/getdate.texi(,130) $ date --iso-8601=ns | tr T ' ' # --iso-8601
is a GNU extension.
+../tar_texi/getdate.texi(,131) 2004-02-29 16:21:42,692722128-0800
+../tar_texi/getdate.texi(,132) $ date --rfc-2822 # a GNU extension
+../tar_texi/getdate.texi(,133) Sun, 29 Feb 2004 16:21:42 -0800
+../tar_texi/getdate.texi(,134) $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU
extension.
+../tar_texi/getdate.texi(,135) 2004-02-29 16:21:42 -0800
+../tar_texi/getdate.texi(,136) $ date +'@@%s.%N' # %s and %N are GNU
extensions.
+../tar_texi/getdate.texi(,137) @@1078100502.692722128
+../tar_texi/getdate.texi(,138) @end example
+../tar_texi/getdate.texi(,139)
+../tar_texi/getdate.texi(,140) @cindex case, ignored in dates
+../tar_texi/getdate.texi(,141) @cindex comments, in dates
+../tar_texi/getdate.texi(,142) Alphabetic case is completely ignored in dates.
Comments may be introduced
+../tar_texi/getdate.texi(,143) between round parentheses, as long as included
parentheses are properly
+../tar_texi/getdate.texi(,144) nested. Hyphens not followed by a digit are
currently ignored. Leading
+../tar_texi/getdate.texi(,145) zeros on numbers are ignored.
+../tar_texi/getdate.texi(,146)
+../tar_texi/getdate.texi(,147) Invalid dates like @samp{2005-02-29} or times
like @samp{24:00} are
+../tar_texi/getdate.texi(,148) rejected. In the typical case of a host that
does not support leap
+../tar_texi/getdate.texi(,149) seconds, a time like @samp{23:59:60} is
rejected even if it
+../tar_texi/getdate.texi(,150) corresponds to a valid leap second.
+../tar_texi/getdate.texi(,151)
+../tar_texi/getdate.texi(,152)
+../tar_texi/getdate.texi(,153) @node Calendar date items
+../tar_texi/getdate.texi(,154) @section Calendar date items
+../tar_texi/getdate.texi(,155)
+../tar_texi/getdate.texi(,156) @cindex calendar date item
+../tar_texi/getdate.texi(,157)
+../tar_texi/getdate.texi(,158) A @dfn{calendar date item} specifies a day of
the year. It is
+../tar_texi/getdate.texi(,159) specified differently, depending on whether the
month is specified
+../tar_texi/getdate.texi(,160) numerically or literally. All these strings
specify the same calendar date:
+../tar_texi/getdate.texi(,161)
+../tar_texi/getdate.texi(,162) @example
+../tar_texi/getdate.texi(,163) 1972-09-24 # @sc{iso} 8601.
+../tar_texi/getdate.texi(,164) 72-9-24 # Assume 19xx for 69 through 99,
+../tar_texi/getdate.texi(,165) # 20xx for 00 through 68.
+../tar_texi/getdate.texi(,166) 72-09-24 # Leading zeros are ignored.
+../tar_texi/getdate.texi(,167) 9/24/72 # Common U.S. writing.
+../tar_texi/getdate.texi(,168) 24 September 1972
+../tar_texi/getdate.texi(,169) 24 Sept 72 # September has a special
abbreviation.
+../tar_texi/getdate.texi(,170) 24 Sep 72 # Three-letter abbreviations
always allowed.
+../tar_texi/getdate.texi(,171) Sep 24, 1972
+../tar_texi/getdate.texi(,172) 24-sep-72
+../tar_texi/getdate.texi(,173) 24sep72
+../tar_texi/getdate.texi(,174) @end example
+../tar_texi/getdate.texi(,175)
+../tar_texi/getdate.texi(,176) The year can also be omitted. In this case,
the last specified year is
+../tar_texi/getdate.texi(,177) used, or the current year if none. For example:
+../tar_texi/getdate.texi(,178)
+../tar_texi/getdate.texi(,179) @example
+../tar_texi/getdate.texi(,180) 9/24
+../tar_texi/getdate.texi(,181) sep 24
+../tar_texi/getdate.texi(,182) @end example
+../tar_texi/getdate.texi(,183)
+../tar_texi/getdate.texi(,184) Here are the rules.
+../tar_texi/getdate.texi(,185)
+../tar_texi/getdate.texi(,186) @cindex @sc{iso} 8601 date format
+../tar_texi/getdate.texi(,187) @cindex date format, @sc{iso} 8601
+../tar_texi/getdate.texi(,188) For numeric months, the @sc{iso} 8601 format
+../tar_texi/getdate.texi(,189) @address@hidden@address@hidden is allowed,
where @var{year} is
+../tar_texi/getdate.texi(,190) any positive number, @var{month} is a number
between 01 and 12, and
+../tar_texi/getdate.texi(,191) @var{day} is a number between 01 and 31. A
leading zero must be present
+../tar_texi/getdate.texi(,192) if a number is less than ten. If @var{year} is
68 or smaller, then 2000
+../tar_texi/getdate.texi(,193) is added to it; otherwise, if @var{year} is
less than 100,
+../tar_texi/getdate.texi(,194) then 1900 is added to it. The construct
+../tar_texi/getdate.texi(,195) @address@hidden/@var{day}/@var{year}}, popular
in the United States,
+../tar_texi/getdate.texi(,196) is accepted. Also @address@hidden/@var{day}},
omitting the year.
+../tar_texi/getdate.texi(,197)
+../tar_texi/getdate.texi(,198) @cindex month names in date strings
+../tar_texi/getdate.texi(,199) @cindex abbreviations for months
+../tar_texi/getdate.texi(,200) Literal months may be spelled out in full:
@samp{January},
+../tar_texi/getdate.texi(,201) @samp{February}, @samp{March}, @samp{April},
@samp{May}, @samp{June},
+../tar_texi/getdate.texi(,202) @samp{July}, @samp{August}, @samp{September},
@samp{October},
+../tar_texi/getdate.texi(,203) @samp{November} or @samp{December}. Literal
months may be abbreviated
+../tar_texi/getdate.texi(,204) to their first three letters, possibly followed
by an abbreviating dot.
+../tar_texi/getdate.texi(,205) It is also permitted to write @samp{Sept}
instead of @samp{September}.
+../tar_texi/getdate.texi(,206)
+../tar_texi/getdate.texi(,207) When months are written literally, the calendar
date may be given as any
+../tar_texi/getdate.texi(,208) of the following:
+../tar_texi/getdate.texi(,209)
+../tar_texi/getdate.texi(,210) @example
+../tar_texi/getdate.texi(,211) @var{day} @var{month} @var{year}
+../tar_texi/getdate.texi(,212) @var{day} @var{month}
+../tar_texi/getdate.texi(,213) @var{month} @var{day} @var{year}
+../tar_texi/getdate.texi(,214) @address@hidden@var{year}
+../tar_texi/getdate.texi(,215) @end example
+../tar_texi/getdate.texi(,216)
+../tar_texi/getdate.texi(,217) Or, omitting the year:
+../tar_texi/getdate.texi(,218)
+../tar_texi/getdate.texi(,219) @example
+../tar_texi/getdate.texi(,220) @var{month} @var{day}
+../tar_texi/getdate.texi(,221) @end example
+../tar_texi/getdate.texi(,222)
+../tar_texi/getdate.texi(,223)
+../tar_texi/getdate.texi(,224) @node Time of day items
+../tar_texi/getdate.texi(,225) @section Time of day items
+../tar_texi/getdate.texi(,226)
+../tar_texi/getdate.texi(,227) @cindex time of day item
+../tar_texi/getdate.texi(,228)
+../tar_texi/getdate.texi(,229) A @dfn{time of day item} in date strings
specifies the time on a given
+../tar_texi/getdate.texi(,230) day. Here are some examples, all of which
represent the same time:
+../tar_texi/getdate.texi(,231)
+../tar_texi/getdate.texi(,232) @example
+../tar_texi/getdate.texi(,233) 20:02:00.000000
+../tar_texi/getdate.texi(,234) 20:02
+../tar_texi/getdate.texi(,235) 8:02pm
+../tar_texi/getdate.texi(,236) 20:02-0500 # In @sc{est} (U.S. Eastern
Standard Time).
+../tar_texi/getdate.texi(,237) @end example
+../tar_texi/getdate.texi(,238)
+../tar_texi/getdate.texi(,239) More generally, the time of day may be given as
+../tar_texi/getdate.texi(,240) @address@hidden:@var{minute}:@var{second}},
where @var{hour} is
+../tar_texi/getdate.texi(,241) a number between 0 and 23, @var{minute} is a
number between 0 and
+../tar_texi/getdate.texi(,242) 59, and @var{second} is a number between 0 and
59 possibly followed by
+../tar_texi/getdate.texi(,243) @samp{.} or @samp{,} and a fraction containing
one or more digits.
+../tar_texi/getdate.texi(,244) Alternatively,
+../tar_texi/getdate.texi(,245) @samp{:@var{second}} can be omitted, in which
case it is taken to
+../tar_texi/getdate.texi(,246) be zero. On the rare hosts that support leap
seconds, @var{second}
+../tar_texi/getdate.texi(,247) may be 60.
+../tar_texi/getdate.texi(,248)
+../tar_texi/getdate.texi(,249) @findex am @r{in date strings}
+../tar_texi/getdate.texi(,250) @findex pm @r{in date strings}
+../tar_texi/getdate.texi(,251) @findex midnight @r{in date strings}
+../tar_texi/getdate.texi(,252) @findex noon @r{in date strings}
+../tar_texi/getdate.texi(,253) If the time is followed by @samp{am} or
@samp{pm} (or @samp{a.m.}
+../tar_texi/getdate.texi(,254) or @samp{p.m.}), @var{hour} is restricted to
run from 1 to 12, and
+../tar_texi/getdate.texi(,255) @samp{:@var{minute}} may be omitted (taken to
be zero). @samp{am}
+../tar_texi/getdate.texi(,256) indicates the first half of the day, @samp{pm}
indicates the second
+../tar_texi/getdate.texi(,257) half of the day. In this notation, 12 is the
predecessor of 1:
+../tar_texi/getdate.texi(,258) midnight is @samp{12am} while noon is
@samp{12pm}.
+../tar_texi/getdate.texi(,259) (This is the zero-oriented interpretation of
@samp{12am} and @samp{12pm},
+../tar_texi/getdate.texi(,260) as opposed to the old tradition derived from
Latin
+../tar_texi/getdate.texi(,261) which uses @samp{12m} for noon and @samp{12pm}
for midnight.)
+../tar_texi/getdate.texi(,262)
+../tar_texi/getdate.texi(,263) @cindex time zone correction
+../tar_texi/getdate.texi(,264) @cindex minutes, time zone correction by
+../tar_texi/getdate.texi(,265) The time may alternatively be followed by a
time zone correction,
+../tar_texi/getdate.texi(,266) expressed as @address@hidden@address@hidden,
where @var{s} is @samp{+}
+../tar_texi/getdate.texi(,267) or @samp{-}, @var{hh} is a number of zone hours
and @var{mm} is a number
+../tar_texi/getdate.texi(,268) of zone minutes. You can also separate
@var{hh} from @var{mm} with a colon.
+../tar_texi/getdate.texi(,269) When a time zone correction is given this way,
it
+../tar_texi/getdate.texi(,270) forces interpretation of the time relative to
+../tar_texi/getdate.texi(,271) Coordinated Universal Time (@sc{utc}),
overriding any previous
+../tar_texi/getdate.texi(,272) specification for the time zone or the local
time zone. For example,
+../tar_texi/getdate.texi(,273) @samp{+0530} and @samp{+05:30} both stand for
the time zone 5.5 hours
+../tar_texi/getdate.texi(,274) ahead of @sc{utc} (e.g., India). The
@var{minute}
+../tar_texi/getdate.texi(,275) part of the time of day may not be elided when
a time zone correction
+../tar_texi/getdate.texi(,276) is used. This is the best way to specify a
time zone correction by
+../tar_texi/getdate.texi(,277) fractional parts of an hour.
+../tar_texi/getdate.texi(,278)
+../tar_texi/getdate.texi(,279) Either @samp{am}/@samp{pm} or a time zone
correction may be specified,
+../tar_texi/getdate.texi(,280) but not both.
+../tar_texi/getdate.texi(,281)
+../tar_texi/getdate.texi(,282)
+../tar_texi/getdate.texi(,283) @node Time zone items
+../tar_texi/getdate.texi(,284) @section Time zone items
+../tar_texi/getdate.texi(,285)
+../tar_texi/getdate.texi(,286) @cindex time zone item
+../tar_texi/getdate.texi(,287)
+../tar_texi/getdate.texi(,288) A @dfn{time zone item} specifies an
international time zone, indicated
+../tar_texi/getdate.texi(,289) by a small set of letters, e.g., @samp{UTC} or
@samp{Z}
+../tar_texi/getdate.texi(,290) for Coordinated Universal
+../tar_texi/getdate.texi(,291) Time. Any included periods are ignored. By
following a
+../tar_texi/getdate.texi(,292) non-daylight-saving time zone by the string
@samp{DST} in a separate
+../tar_texi/getdate.texi(,293) word (that is, separated by some white space),
the corresponding
+../tar_texi/getdate.texi(,294) daylight saving time zone may be specified.
+../tar_texi/getdate.texi(,295) Alternatively, a non-daylight-saving time zone
can be followed by a
+../tar_texi/getdate.texi(,296) time zone correction, to add the two values.
This is normally done
+../tar_texi/getdate.texi(,297) only for @samp{UTC}; for example,
@samp{UTC+05:30} is equivalent to
+../tar_texi/getdate.texi(,298) @samp{+05:30}.
+../tar_texi/getdate.texi(,299)
+../tar_texi/getdate.texi(,300) Time zone items other than @samp{UTC} and
@samp{Z}
+../tar_texi/getdate.texi(,301) are obsolescent and are not recommended,
because they
+../tar_texi/getdate.texi(,302) are ambiguous; for example, @samp{EST} has a
different meaning in
+../tar_texi/getdate.texi(,303) Australia than in the United States. Instead,
it's better to use
+../tar_texi/getdate.texi(,304) unambiguous numeric time zone corrections like
@samp{-0500}, as
+../tar_texi/getdate.texi(,305) described in the previous section.
+../tar_texi/getdate.texi(,306)
+../tar_texi/getdate.texi(,307) If neither a time zone item nor a time zone
correction is supplied,
+../tar_texi/getdate.texi(,308) time stamps are interpreted using the rules of
the default time zone
+../tar_texi/getdate.texi(,309) (@pxref{Specifying time zone rules}).
+../tar_texi/getdate.texi(,310)
+../tar_texi/getdate.texi(,311)
+../tar_texi/getdate.texi(,312) @node Day of week items
+../tar_texi/getdate.texi(,313) @section Day of week items
+../tar_texi/getdate.texi(,314)
+../tar_texi/getdate.texi(,315) @cindex day of week item
+../tar_texi/getdate.texi(,316)
+../tar_texi/getdate.texi(,317) The explicit mention of a day of the week will
forward the date
+../tar_texi/getdate.texi(,318) (only if necessary) to reach that day of the
week in the future.
+../tar_texi/getdate.texi(,319)
+../tar_texi/getdate.texi(,320) Days of the week may be spelled out in full:
@samp{Sunday},
+../tar_texi/getdate.texi(,321) @samp{Monday}, @samp{Tuesday},
@samp{Wednesday}, @samp{Thursday},
+../tar_texi/getdate.texi(,322) @samp{Friday} or @samp{Saturday}. Days may be
abbreviated to their
+../tar_texi/getdate.texi(,323) first three letters, optionally followed by a
period. The special
+../tar_texi/getdate.texi(,324) abbreviations @samp{Tues} for @samp{Tuesday},
@samp{Wednes} for
+../tar_texi/getdate.texi(,325) @samp{Wednesday} and @samp{Thur} or
@samp{Thurs} for @samp{Thursday} are
+../tar_texi/getdate.texi(,326) also allowed.
+../tar_texi/getdate.texi(,327)
+../tar_texi/getdate.texi(,328) @findex next @var{day}
+../tar_texi/getdate.texi(,329) @findex last @var{day}
+../tar_texi/getdate.texi(,330) A number may precede a day of the week item to
move forward
+../tar_texi/getdate.texi(,331) supplementary weeks. It is best used in
expression like @samp{third
+../tar_texi/getdate.texi(,332) monday}. In this context, @samp{last
@var{day}} or @samp{next
+../tar_texi/getdate.texi(,333) @var{day}} is also acceptable; they move one
week before or after
+../tar_texi/getdate.texi(,334) the day that @var{day} by itself would
represent.
+../tar_texi/getdate.texi(,335)
+../tar_texi/getdate.texi(,336) A comma following a day of the week item is
ignored.
+../tar_texi/getdate.texi(,337)
+../tar_texi/getdate.texi(,338)
+../tar_texi/getdate.texi(,339) @node Relative items in date strings
+../tar_texi/getdate.texi(,340) @section Relative items in date strings
+../tar_texi/getdate.texi(,341)
+../tar_texi/getdate.texi(,342) @cindex relative items in date strings
+../tar_texi/getdate.texi(,343) @cindex displacement of dates
+../tar_texi/getdate.texi(,344)
+../tar_texi/getdate.texi(,345) @dfn{Relative items} adjust a date (or the
current date if none) forward
+../tar_texi/getdate.texi(,346) or backward. The effects of relative items
accumulate. Here are some
+../tar_texi/getdate.texi(,347) examples:
+../tar_texi/getdate.texi(,348)
+../tar_texi/getdate.texi(,349) @example
+../tar_texi/getdate.texi(,350) 1 year
+../tar_texi/getdate.texi(,351) 1 year ago
+../tar_texi/getdate.texi(,352) 3 years
+../tar_texi/getdate.texi(,353) 2 days
+../tar_texi/getdate.texi(,354) @end example
+../tar_texi/getdate.texi(,355)
+../tar_texi/getdate.texi(,356) @findex year @r{in date strings}
+../tar_texi/getdate.texi(,357) @findex month @r{in date strings}
+../tar_texi/getdate.texi(,358) @findex fortnight @r{in date strings}
+../tar_texi/getdate.texi(,359) @findex week @r{in date strings}
+../tar_texi/getdate.texi(,360) @findex day @r{in date strings}
+../tar_texi/getdate.texi(,361) @findex hour @r{in date strings}
+../tar_texi/getdate.texi(,362) @findex minute @r{in date strings}
+../tar_texi/getdate.texi(,363) The unit of time displacement may be selected
by the string @samp{year}
+../tar_texi/getdate.texi(,364) or @samp{month} for moving by whole years or
months. These are fuzzy
+../tar_texi/getdate.texi(,365) units, as years and months are not all of equal
duration. More precise
+../tar_texi/getdate.texi(,366) units are @samp{fortnight} which is worth 14
days, @samp{week} worth 7
+../tar_texi/getdate.texi(,367) days, @samp{day} worth 24 hours, @samp{hour}
worth 60 minutes,
+../tar_texi/getdate.texi(,368) @samp{minute} or @samp{min} worth 60 seconds,
and @samp{second} or
+../tar_texi/getdate.texi(,369) @samp{sec} worth one second. An @samp{s}
suffix on these units is
+../tar_texi/getdate.texi(,370) accepted and ignored.
+../tar_texi/getdate.texi(,371)
+../tar_texi/getdate.texi(,372) @findex ago @r{in date strings}
+../tar_texi/getdate.texi(,373) The unit of time may be preceded by a
multiplier, given as an optionally
+../tar_texi/getdate.texi(,374) signed number. Unsigned numbers are taken as
positively signed. No
+../tar_texi/getdate.texi(,375) number at all implies 1 for a multiplier.
Following a relative item by
+../tar_texi/getdate.texi(,376) the string @samp{ago} is equivalent to
preceding the unit by a
+../tar_texi/getdate.texi(,377) multiplier with value @math{-1}.
+../tar_texi/getdate.texi(,378)
+../tar_texi/getdate.texi(,379) @findex day @r{in date strings}
+../tar_texi/getdate.texi(,380) @findex tomorrow @r{in date strings}
+../tar_texi/getdate.texi(,381) @findex yesterday @r{in date strings}
+../tar_texi/getdate.texi(,382) The string @samp{tomorrow} is worth one day in
the future (equivalent
+../tar_texi/getdate.texi(,383) to @samp{day}), the string @samp{yesterday} is
worth
+../tar_texi/getdate.texi(,384) one day in the past (equivalent to @samp{day
ago}).
+../tar_texi/getdate.texi(,385)
+../tar_texi/getdate.texi(,386) @findex now @r{in date strings}
+../tar_texi/getdate.texi(,387) @findex today @r{in date strings}
+../tar_texi/getdate.texi(,388) @findex this @r{in date strings}
+../tar_texi/getdate.texi(,389) The strings @samp{now} or @samp{today} are
relative items corresponding
+../tar_texi/getdate.texi(,390) to zero-valued time displacement, these strings
come from the fact
+../tar_texi/getdate.texi(,391) a zero-valued time displacement represents the
current time when not
+../tar_texi/getdate.texi(,392) otherwise changed by previous items. They may
be used to stress other
+../tar_texi/getdate.texi(,393) items, like in @samp{12:00 today}. The string
@samp{this} also has
+../tar_texi/getdate.texi(,394) the meaning of a zero-valued time displacement,
but is preferred in
+../tar_texi/getdate.texi(,395) date strings like @samp{this thursday}.
+../tar_texi/getdate.texi(,396)
+../tar_texi/getdate.texi(,397) When a relative item causes the resulting date
to cross a boundary
+../tar_texi/getdate.texi(,398) where the clocks were adjusted, typically for
daylight saving time,
+../tar_texi/getdate.texi(,399) the resulting date and time are adjusted
accordingly.
+../tar_texi/getdate.texi(,400)
+../tar_texi/getdate.texi(,401) The fuzz in units can cause problems with
relative items. For
+../tar_texi/getdate.texi(,402) example, @samp{2003-07-31 -1 month} might
evaluate to 2003-07-01,
+../tar_texi/getdate.texi(,403) because 2003-06-31 is an invalid date. To
determine the previous
+../tar_texi/getdate.texi(,404) month more reliably, you can ask for the month
before the 15th of the
+../tar_texi/getdate.texi(,405) current month. For example:
+../tar_texi/getdate.texi(,406)
+../tar_texi/getdate.texi(,407) @example
+../tar_texi/getdate.texi(,408) $ date -R
+../tar_texi/getdate.texi(,409) Thu, 31 Jul 2003 13:02:39 -0700
+../tar_texi/getdate.texi(,410) $ date --date='-1 month' +'Last month was %B?'
+../tar_texi/getdate.texi(,411) Last month was July?
+../tar_texi/getdate.texi(,412) $ date --date="$(date +%Y-%m-15) -1 month"
+'Last month was %B!'
+../tar_texi/getdate.texi(,413) Last month was June!
+../tar_texi/getdate.texi(,414) @end example
+../tar_texi/getdate.texi(,415)
+../tar_texi/getdate.texi(,416) Also, take care when manipulating dates around
clock changes such as
+../tar_texi/getdate.texi(,417) daylight saving leaps. In a few cases these
have added or subtracted
+../tar_texi/getdate.texi(,418) as much as 24 hours from the clock, so it is
often wise to adopt
+../tar_texi/getdate.texi(,419) universal time by setting the @env{TZ}
environment variable to
+../tar_texi/getdate.texi(,420) @samp{UTC0} before embarking on calendrical
calculations.
+../tar_texi/getdate.texi(,421)
+../tar_texi/getdate.texi(,422) @node Pure numbers in date strings
+../tar_texi/getdate.texi(,423) @section Pure numbers in date strings
+../tar_texi/getdate.texi(,424)
+../tar_texi/getdate.texi(,425) @cindex pure numbers in date strings
+../tar_texi/getdate.texi(,426)
+../tar_texi/getdate.texi(,427) The precise interpretation of a pure decimal
number depends
+../tar_texi/getdate.texi(,428) on the context in the date string.
+../tar_texi/getdate.texi(,429)
+../tar_texi/getdate.texi(,430) If the decimal number is of the form
@address@hidden@var{dd} and no
+../tar_texi/getdate.texi(,431) other calendar date item (@pxref{Calendar date
items}) appears before it
+../tar_texi/getdate.texi(,432) in the date string, then @var{yyyy} is read as
the year, @var{mm} as the
+../tar_texi/getdate.texi(,433) month number and @var{dd} as the day of the
month, for the specified
+../tar_texi/getdate.texi(,434) calendar date.
+../tar_texi/getdate.texi(,435)
+../tar_texi/getdate.texi(,436) If the decimal number is of the form
@address@hidden and no other time
+../tar_texi/getdate.texi(,437) of day item appears before it in the date
string, then @var{hh} is read
+../tar_texi/getdate.texi(,438) as the hour of the day and @var{mm} as the
minute of the hour, for the
+../tar_texi/getdate.texi(,439) specified time of day. @var{mm} can also be
omitted.
+../tar_texi/getdate.texi(,440)
+../tar_texi/getdate.texi(,441) If both a calendar date and a time of day
appear to the left of a number
+../tar_texi/getdate.texi(,442) in the date string, but no relative item, then
the number overrides the
+../tar_texi/getdate.texi(,443) year.
+../tar_texi/getdate.texi(,444)
+../tar_texi/getdate.texi(,445)
+../tar_texi/getdate.texi(,446) @node Seconds since the Epoch
+../tar_texi/getdate.texi(,447) @section Seconds since the Epoch
+../tar_texi/getdate.texi(,448)
+../tar_texi/getdate.texi(,449) If you precede a number with @samp{@@}, it
represents an internal time
+../tar_texi/getdate.texi(,450) stamp as a count of seconds. The number can
contain an internal
+../tar_texi/getdate.texi(,451) decimal point (either @samp{.} or @samp{,});
any excess precision not
+../tar_texi/getdate.texi(,452) supported by the internal representation is
truncated toward minus
+../tar_texi/getdate.texi(,453) infinity. Such a number cannot be combined
with any other date
+../tar_texi/getdate.texi(,454) item, as it specifies a complete time stamp.
+../tar_texi/getdate.texi(,455)
+../tar_texi/getdate.texi(,456) @cindex beginning of time, for @acronym{POSIX}
+../tar_texi/getdate.texi(,457) @cindex epoch, for @acronym{POSIX}
+../tar_texi/getdate.texi(,458) Internally, computer times are represented as a
count of seconds since
+../tar_texi/getdate.texi(,459) an epoch---a well-defined point of time. On
@acronym{GNU} and
+../tar_texi/getdate.texi(,460) @acronym{POSIX} systems, the epoch is
1970-01-01 00:00:00 @sc{utc}, so
+../tar_texi/getdate.texi(,461) @samp{@@0} represents this time, @samp{@@1}
represents 1970-01-01
+../tar_texi/getdate.texi(,462) 00:00:01 @sc{utc}, and so forth. @acronym{GNU}
and most other
+../tar_texi/getdate.texi(,463) @acronym{POSIX}-compliant systems support such
times as an extension
+../tar_texi/getdate.texi(,464) to @acronym{POSIX}, using negative counts, so
that @samp{@@-1}
+../tar_texi/getdate.texi(,465) represents 1969-12-31 23:59:59 @sc{utc}.
+../tar_texi/getdate.texi(,466)
+../tar_texi/getdate.texi(,467) Traditional Unix systems count seconds with
32-bit two's-complement
+../tar_texi/getdate.texi(,468) integers and can represent times from
1901-12-13 20:45:52 through
+../tar_texi/getdate.texi(,469) 2038-01-19 03:14:07 @sc{utc}. More modern
systems use 64-bit counts
+../tar_texi/getdate.texi(,470) of seconds with nanosecond subcounts, and can
represent all the times
+../tar_texi/getdate.texi(,471) in the known lifetime of the universe to a
resolution of 1 nanosecond.
+../tar_texi/getdate.texi(,472)
+../tar_texi/getdate.texi(,473) On most hosts, these counts ignore the presence
of leap seconds.
+../tar_texi/getdate.texi(,474) For example, on most hosts @samp{@@915148799}
represents 1998-12-31
+../tar_texi/getdate.texi(,475) 23:59:59 @sc{utc}, @samp{@@915148800}
represents 1999-01-01 00:00:00
+../tar_texi/getdate.texi(,476) @sc{utc}, and there is no way to represent the
intervening leap second
+../tar_texi/getdate.texi(,477) 1998-12-31 23:59:60 @sc{utc}.
+../tar_texi/getdate.texi(,478)
+../tar_texi/getdate.texi(,479) @node Specifying time zone rules
+../tar_texi/getdate.texi(,480) @section Specifying time zone rules
+../tar_texi/getdate.texi(,481)
+../tar_texi/getdate.texi(,482) @vindex TZ
+../tar_texi/getdate.texi(,483) Normally, dates are interpreted using the rules
of the current time
+../tar_texi/getdate.texi(,484) zone, which in turn are specified by the
@env{TZ} environment
+../tar_texi/getdate.texi(,485) variable, or by a system default if @env{TZ} is
not set. To specify a
+../tar_texi/getdate.texi(,486) different set of default time zone rules that
apply just to one date,
+../tar_texi/getdate.texi(,487) start the date with a string of the form
@samp{TZ="@var{rule}"}. The
+../tar_texi/getdate.texi(,488) two quote characters (@samp{"}) must be present
in the date, and any
+../tar_texi/getdate.texi(,489) quotes or backslashes within @var{rule} must be
escaped by a
+../tar_texi/getdate.texi(,490) backslash.
+../tar_texi/getdate.texi(,491)
+../tar_texi/getdate.texi(,492) For example, with the @acronym{GNU}
@command{date} command you can
+../tar_texi/getdate.texi(,493) answer the question ``What time is it in New
York when a Paris clock
+../tar_texi/getdate.texi(,494) shows 6:30am on October 31, 2004?'' by using a
date beginning with
+../tar_texi/getdate.texi(,495) @samp{TZ="Europe/Paris"} as shown in the
following shell transcript:
+../tar_texi/getdate.texi(,496)
+../tar_texi/getdate.texi(,497) @example
+../tar_texi/getdate.texi(,498) $ export TZ="America/New_York"
+../tar_texi/getdate.texi(,499) $ date --date='TZ="Europe/Paris" 2004-10-31
06:30'
+../tar_texi/getdate.texi(,500) Sun Oct 31 01:30:00 EDT 2004
+../tar_texi/getdate.texi(,501) @end example
+../tar_texi/getdate.texi(,502)
+../tar_texi/getdate.texi(,503) In this example, the @option{--date} operand
begins with its own
+../tar_texi/getdate.texi(,504) @env{TZ} setting, so the rest of that operand
is processed according
+../tar_texi/getdate.texi(,505) to @samp{Europe/Paris} rules, treating the
string @samp{2004-10-31
+../tar_texi/getdate.texi(,506) 06:30} as if it were in Paris. However, since
the output of the
+../tar_texi/getdate.texi(,507) @command{date} command is processed according
to the overall time zone
+../tar_texi/getdate.texi(,508) rules, it uses New York time. (Paris was
normally six hours ahead of
+../tar_texi/getdate.texi(,509) New York in 2004, but this example refers to a
brief Halloween period
+../tar_texi/getdate.texi(,510) when the gap was five hours.)
+../tar_texi/getdate.texi(,511)
+../tar_texi/getdate.texi(,512) A @env{TZ} value is a rule that typically names
a location in the
+../tar_texi/getdate.texi(,513) @uref{http://www.twinsun.com/tz/tz-link.htm,
@samp{tz} database}.
+../tar_texi/getdate.texi(,514) A recent catalog of location names appears in
the
+../tar_texi/getdate.texi(,515) @uref{http://twiki.org/cgi-bin/xtra/tzdate,
TWiki Date and Time
+../tar_texi/getdate.texi(,516) Gateway}. A few address@hidden hosts require a
colon before a
+../tar_texi/getdate.texi(,517) location name in a @env{TZ} setting, e.g.,
+../tar_texi/getdate.texi(,518) @samp{TZ=":America/New_York"}.
+../tar_texi/getdate.texi(,519)
+../tar_texi/getdate.texi(,520) The @samp{tz} database includes a wide variety
of locations ranging
+../tar_texi/getdate.texi(,521) from @samp{Arctic/Longyearbyen} to
@samp{Antarctica/South_Pole}, but
+../tar_texi/getdate.texi(,522) if you are at sea and have your own private
time zone, or if you are
+../tar_texi/getdate.texi(,523) using a address@hidden host that does not
support the @samp{tz}
+../tar_texi/getdate.texi(,524) database, you may need to use a @acronym{POSIX}
rule instead. Simple
+../tar_texi/getdate.texi(,525) @acronym{POSIX} rules like @samp{UTC0} specify
a time zone without
+../tar_texi/getdate.texi(,526) daylight saving time; other rules can specify
simple daylight saving
+../tar_texi/getdate.texi(,527) regimes. @xref{TZ Variable,, Specifying the
Time Zone with @code{TZ},
+../tar_texi/getdate.texi(,528) libc, The GNU C Library}.
+../tar_texi/getdate.texi(,529)
+../tar_texi/getdate.texi(,530) @node Authors of get_date
+../tar_texi/getdate.texi(,531) @section Authors of @code{get_date}
+../tar_texi/getdate.texi(,532)
+../tar_texi/getdate.texi(,533) @cindex authors of @code{get_date}
+../tar_texi/getdate.texi(,534)
+../tar_texi/getdate.texi(,535) @cindex Bellovin, Steven M.
+../tar_texi/getdate.texi(,536) @cindex Salz, Rich
+../tar_texi/getdate.texi(,537) @cindex Berets, Jim
+../tar_texi/getdate.texi(,538) @cindex MacKenzie, David
+../tar_texi/getdate.texi(,539) @cindex Meyering, Jim
+../tar_texi/getdate.texi(,540) @cindex Eggert, Paul
+../tar_texi/getdate.texi(,541) @code{get_date} was originally implemented by
Steven M. Bellovin
+../tar_texi/getdate.texi(,542) (@email{smb@@research.att.com}) while at the
University of North Carolina
+../tar_texi/getdate.texi(,543) at Chapel Hill. The code was later tweaked by
a couple of people on
+../tar_texi/getdate.texi(,544) Usenet, then completely overhauled by Rich $alz
(@email{rsalz@@bbn.com})
+../tar_texi/getdate.texi(,545) and Jim Berets (@email{jberets@@bbn.com}) in
August, 1990. Various
+../tar_texi/getdate.texi(,546) revisions for the @sc{gnu} system were made by
David MacKenzie, Jim Meyering,
+../tar_texi/getdate.texi(,547) Paul Eggert and others.
+../tar_texi/getdate.texi(,548)
+../tar_texi/getdate.texi(,549) @cindex Pinard, F.
+../tar_texi/getdate.texi(,550) @cindex Berry, K.
+../tar_texi/getdate.texi(,551) This chapter was originally produced by
address@hidden Pinard
+../tar_texi/getdate.texi(,552) (@email{pinard@@iro.umontreal.ca}) from the
@file{getdate.y} source code,
+../tar_texi/getdate.texi(,553) and then edited by K.@: Berry
(@email{kb@@cs.umb.edu}).
+../tar_texi/tar.texi(,7629)
+../tar_texi/tar.texi(,7630) @node Formats
+../tar_texi/tar.texi(,7631) @chapter Controlling the Archive Format
+../tar_texi/tar.texi(,7632)
+../tar_texi/tar.texi(,7633) @cindex Tar archive formats
+../tar_texi/tar.texi(,7634) Due to historical reasons, there are several
formats of tar archives.
+../tar_texi/tar.texi(,7635) All of them are based on the same principles, but
have some subtle
+../tar_texi/tar.texi(,7636) differences that often make them incompatible with
each other.
+../tar_texi/tar.texi(,7637)
+../tar_texi/tar.texi(,7638) GNU tar is able to create and handle archives in a
variety of formats.
+../tar_texi/tar.texi(,7639) The most frequently used formats are (in
alphabetical order):
+../tar_texi/tar.texi(,7640)
+../tar_texi/tar.texi(,7641) @table @asis
+../tar_texi/tar.texi(,7642) @item gnu
+../tar_texi/tar.texi(GNUTAR,7643) Format used by @acronym{GNU} @command{tar}
versions up to 1.13.25. This format derived
+../tar_texi/tar.texi(,7644) from an early @acronym{POSIX} standard, adding
some improvements such as
+../tar_texi/tar.texi(,7645) sparse file handling and incremental archives.
Unfortunately these
+../tar_texi/tar.texi(,7646) features were implemented in a way incompatible
with other archive
+../tar_texi/tar.texi(,7647) formats.
+../tar_texi/tar.texi(,7648)
+../tar_texi/tar.texi(,7649) Archives in @samp{gnu} format are able to hold
pathnames of unlimited
+../tar_texi/tar.texi(,7650) length.
+../tar_texi/tar.texi(,7651)
+../tar_texi/tar.texi(,7652) @item oldgnu
+../tar_texi/tar.texi(GNUTAR,7653) Format used by @acronym{GNU} @command{tar}
of versions prior to 1.12.
+../tar_texi/tar.texi(,7654)
+../tar_texi/tar.texi(,7655) @item v7
+../tar_texi/tar.texi(,7656) Archive format, compatible with the V7
implementation of tar. This
+../tar_texi/tar.texi(,7657) format imposes a number of limitations. The most
important of them
+../tar_texi/tar.texi(,7658) are:
+../tar_texi/tar.texi(,7659)
+../tar_texi/tar.texi(,7660) @enumerate
+../tar_texi/tar.texi(,7661) @item The maximum length of a file name is limited
to 99 characters.
+../tar_texi/tar.texi(,7662) @item The maximum length of a symbolic link is
limited to 99 characters.
+../tar_texi/tar.texi(,7663) @item It is impossible to store special files
(block and character
+../tar_texi/tar.texi(,7664) devices, fifos etc.)
+../tar_texi/tar.texi(,7665) @item Maximum value of user or group ID is limited
to 2097151 (7777777
+../tar_texi/tar.texi(,7666) octal)
+../tar_texi/tar.texi(,7667) @item V7 archives do not contain symbolic
ownership information (user
+../tar_texi/tar.texi(,7668) and group name of the file owner).
+../tar_texi/tar.texi(,7669) @end enumerate
+../tar_texi/tar.texi(,7670)
+../tar_texi/tar.texi(,7671) This format has traditionally been used by
Automake when producing
+../tar_texi/tar.texi(,7672) Makefiles. This practice will change in the
future, in the meantime,
+../tar_texi/tar.texi(,7673) however this means that projects containing
filenames more than 99
+../tar_texi/tar.texi(GNUTAR,7674) characters long will not be able to use
@acronym{GNU} @command{tar} 1.15.92 and
+../tar_texi/tar.texi(,7675) Automake prior to 1.9.
+../tar_texi/tar.texi(,7676)
+../tar_texi/tar.texi(,7677) @item ustar
+../tar_texi/tar.texi(,7678) Archive format defined by @acronym{POSIX.1-1988}
specification. It stores
+../tar_texi/tar.texi(,7679) symbolic ownership information. It is also able
to store
+../tar_texi/tar.texi(,7680) special files. However, it imposes several
restrictions as well:
+../tar_texi/tar.texi(,7681)
+../tar_texi/tar.texi(,7682) @enumerate
+../tar_texi/tar.texi(,7683) @item The maximum length of a file name is limited
to 256 characters,
+../tar_texi/tar.texi(,7684) provided that the filename can be split at
directory separator in
+../tar_texi/tar.texi(,7685) two parts, first of them being at most 155 bytes
long. So, in most
+../tar_texi/tar.texi(,7686) cases the maximum file name length will be shorter
than 256
+../tar_texi/tar.texi(,7687) characters.
+../tar_texi/tar.texi(,7688) @item The maximum length of a symbolic link name
is limited to
+../tar_texi/tar.texi(,7689) 100 characters.
+../tar_texi/tar.texi(,7690) @item Maximum size of a file the archive is able
to accomodate
+../tar_texi/tar.texi(,7691) is 8GB
+../tar_texi/tar.texi(,7692) @item Maximum value of UID/GID is 2097151.
+../tar_texi/tar.texi(,7693) @item Maximum number of bits in device major and
minor numbers is 21.
+../tar_texi/tar.texi(,7694) @end enumerate
+../tar_texi/tar.texi(,7695)
+../tar_texi/tar.texi(,7696) @item star
+../tar_texi/tar.texi(,7697) Format used by J@"org Schilling @command{star}
+../tar_texi/tar.texi(GNUTAR,7698) implementation. @acronym{GNU} @command{tar}
is able to read @samp{star} archives but
+../tar_texi/tar.texi(,7699) currently does not produce them.
+../tar_texi/tar.texi(,7700)
+../tar_texi/tar.texi(,7701) @item posix
+../tar_texi/tar.texi(,7702) Archive format defined by @acronym{POSIX.1-2001}
specification. This is the
+../tar_texi/tar.texi(,7703) most flexible and feature-rich format. It does
not impose any
+../tar_texi/tar.texi(,7704) restrictions on file sizes or filename lengths.
This format is quite
+../tar_texi/tar.texi(,7705) recent, so not all tar implementations are able to
handle it properly.
+../tar_texi/tar.texi(,7706) However, this format is designed in such a way
that any tar
+../tar_texi/tar.texi(,7707) implementation able to read @samp{ustar} archives
will be able to read
+../tar_texi/tar.texi(,7708) most @samp{posix} archives as well, with the only
exception that any
+../tar_texi/tar.texi(,7709) additional information (such as long file names
etc.) will in such
+../tar_texi/tar.texi(,7710) case be extracted as plain text files along with
the files it refers to.
+../tar_texi/tar.texi(,7711)
+../tar_texi/tar.texi(,7712) This archive format will be the default format for
future versions
+../tar_texi/tar.texi(GNUTAR,7713) of @acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,7714)
+../tar_texi/tar.texi(,7715) @end table
+../tar_texi/tar.texi(,7716)
+../tar_texi/tar.texi(,7717) The following table summarizes the limitations of
each of these
+../tar_texi/tar.texi(,7718) formats:
+../tar_texi/tar.texi(,7719)
+../tar_texi/tar.texi(,7720) @multitable @columnfractions .10 .20 .20 .20 .20
+../tar_texi/tar.texi(,7721) @headitem Format @tab UID @tab File Size @tab Path
Name @tab Devn
+../tar_texi/tar.texi(,7722) @item gnu @tab 1.8e19 @tab Unlimited @tab
Unlimited @tab 63
+../tar_texi/tar.texi(,7723) @item oldgnu @tab 1.8e19 @tab Unlimited @tab
Unlimited @tab 63
+../tar_texi/tar.texi(,7724) @item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
+../tar_texi/tar.texi(,7725) @item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
+../tar_texi/tar.texi(,7726) @item posix @tab Unlimited @tab Unlimited @tab
Unlimited @tab Unlimited
+../tar_texi/tar.texi(,7727) @end multitable
+../tar_texi/tar.texi(,7728)
+../tar_texi/tar.texi(GNUTAR,7729) The default format for @acronym{GNU}
@command{tar} is defined at compilation
+../tar_texi/tar.texi(,7730) time. You may check it by running @command{tar
--help}, and examining
+../tar_texi/tar.texi(GNUTAR,7731) the last lines of its output. Usually,
@acronym{GNU} @command{tar} is configured
+../tar_texi/tar.texi(,7732) to create archives in @samp{gnu} format, however,
future version will
+../tar_texi/tar.texi(,7733) switch to @samp{posix}.
+../tar_texi/tar.texi(,7734)
+../tar_texi/tar.texi(,7735) @menu
+../tar_texi/tar.texi(,7736) * Compression:: Using Less Space
through Compression
+../tar_texi/tar.texi(,7737) * Attributes:: Handling File
Attributes
+../tar_texi/tar.texi(,7738) * Portability:: Making
@command{tar} Archives More Portable
+../tar_texi/tar.texi(,7739) * cpio:: Comparison of
@command{tar} and @command{cpio}
+../tar_texi/tar.texi(,7740) @end menu
+../tar_texi/tar.texi(,7741)
+../tar_texi/tar.texi(,7742) @node Compression
+../tar_texi/tar.texi(,7743) @section Using Less Space through Compression
+../tar_texi/tar.texi(,7744)
+../tar_texi/tar.texi(,7745) @menu
+../tar_texi/tar.texi(,7746) * gzip:: Creating and
Reading Compressed Archives
+../tar_texi/tar.texi(,7747) * sparse:: Archiving Sparse
Files
+../tar_texi/tar.texi(,7748) @end menu
+../tar_texi/tar.texi(,7749)
+../tar_texi/tar.texi(,7750) @node gzip
+../tar_texi/tar.texi(,7751) @subsection Creating and Reading Compressed
Archives
+../tar_texi/tar.texi(,7752) @cindex Compressed archives
+../tar_texi/tar.texi(,7753) @cindex Storing archives in compressed format
+../tar_texi/tar.texi(,7754)
+../tar_texi/tar.texi(GNUTAR,7755) @acronym{GNU} @command{tar} is able to
create and read compressed archives. It supports
+../tar_texi/tar.texi(,7756) @command{gzip} and @command{bzip2} compression
programs. For backward
+../tar_texi/tar.texi(,7757) compatibilty, it also supports @command{compress}
command, although
+../tar_texi/tar.texi(,7758) we strongly recommend against using it, since
there is a patent
+../tar_texi/tar.texi(,7759) covering the algorithm it uses and you could be
sued for patent
+../tar_texi/tar.texi(,7760) infringement merely by running @command{compress}!
Besides, it is less
+../tar_texi/tar.texi(,7761) effective than @command{gzip} and @command{bzip2}.
+../tar_texi/tar.texi(,7762)
+../tar_texi/tar.texi(,7763) Creating a compressed archive is simple: you just
specify a
+../tar_texi/tar.texi(,7764) @dfn{compression option} along with the usual
archive creation
+../tar_texi/tar.texi(,7765) commands. The compression option is @option{-z}
(@option{--gzip}) to
+../tar_texi/tar.texi(,7766) create a @command{gzip} compressed archive,
@option{-j}
+../tar_texi/tar.texi(,7767) (@option{--bzip2}) to create a @command{bzip2}
compressed archive, and
+../tar_texi/tar.texi(,7768) @option{-Z} (@option{--compress}) to use
@command{compress} program.
+../tar_texi/tar.texi(,7769) For example:
+../tar_texi/tar.texi(,7770)
+../tar_texi/tar.texi(,7771) @smallexample
+../tar_texi/tar.texi(,7772) $ @kbd{tar cfz archive.tar.gz .}
+../tar_texi/tar.texi(,7773) @end smallexample
+../tar_texi/tar.texi(,7774)
+../tar_texi/tar.texi(,7775) Reading compressed archive is even simpler: you
don't need to specify
+../tar_texi/tar.texi(GNUTAR,7776) any additional options as @acronym{GNU}
@command{tar} recognizes its format
+../tar_texi/tar.texi(,7777) automatically. Thus, the following commands will
list and extract the
+../tar_texi/tar.texi(,7778) archive created in previous example:
+../tar_texi/tar.texi(,7779)
+../tar_texi/tar.texi(,7780) @smallexample
+../tar_texi/tar.texi(,7781) # List the compressed archive
+../tar_texi/tar.texi(,7782) $ @kbd{tar tf archive.tar.gz}
+../tar_texi/tar.texi(,7783) # Extract the compressed archive
+../tar_texi/tar.texi(,7784) $ @kbd{tar xf archive.tar.gz}
+../tar_texi/tar.texi(,7785) @end smallexample
+../tar_texi/tar.texi(,7786)
+../tar_texi/tar.texi(,7787) The only case when you have to specify a
decompression option while
+../tar_texi/tar.texi(,7788) reading the archive is when reading from a pipe or
from a tape drive
+../tar_texi/tar.texi(GNUTAR,7789) that does not support random access.
However, in this case @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,7790) will indicate which option you should use. For
example:
+../tar_texi/tar.texi(,7791)
+../tar_texi/tar.texi(,7792) @smallexample
+../tar_texi/tar.texi(,7793) $ @kbd{cat archive.tar.gz | tar tf -}
+../tar_texi/tar.texi(,7794) tar: Archive is compressed. Use -z option
+../tar_texi/tar.texi(,7795) tar: Error is not recoverable: exiting now
+../tar_texi/tar.texi(,7796) @end smallexample
+../tar_texi/tar.texi(,7797)
+../tar_texi/tar.texi(,7798) If you see such diagnostics, just add the
suggested option to the
+../tar_texi/tar.texi(GNUTAR,7799) invocation of @acronym{GNU} @command{tar}:
+../tar_texi/tar.texi(,7800)
+../tar_texi/tar.texi(,7801) @smallexample
+../tar_texi/tar.texi(,7802) $ @kbd{cat archive.tar.gz | tar tfz -}
+../tar_texi/tar.texi(,7803) @end smallexample
+../tar_texi/tar.texi(,7804)
+../tar_texi/tar.texi(,7805) Notice also, that there are several restrictions
on operations on
+../tar_texi/tar.texi(,7806) compressed archives. First of all, compressed
archives cannot be
+../tar_texi/tar.texi(,7807) modified, i.e., you cannot update
(@option{--update} (@option{-u})) them or delete
+../tar_texi/tar.texi(,7808) (@option{--delete}) members from them. Likewise,
you cannot append
+../tar_texi/tar.texi(,7809) another @command{tar} archive to a compressed
archive using
+../tar_texi/tar.texi(,7810) @option{--append} (@option{-r})). Secondly,
multi-volume archives cannot be
+../tar_texi/tar.texi(,7811) compressed.
+../tar_texi/tar.texi(,7812)
+../tar_texi/tar.texi(GNUTAR,7813) The following table summarizes compression
options used by @acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,7814)
+../tar_texi/tar.texi(,7815) @table @option
+../tar_texi/tar.texi(,7816) @opindex gzip
+../tar_texi/tar.texi(,7817) @opindex ungzip
+../tar_texi/tar.texi(,7818) @item -z
+../tar_texi/tar.texi(,7819) @itemx --gzip
+../tar_texi/tar.texi(,7820) @itemx --ungzip
+../tar_texi/tar.texi(,7821) Filter the archive through @command{gzip}.
+../tar_texi/tar.texi(,7822)
+../tar_texi/tar.texi(,7823) You can use @option{--gzip} and @option{--gunzip}
on physical devices
+../tar_texi/tar.texi(,7824) (tape drives, etc.) and remote files as well as on
normal files; data
+../tar_texi/tar.texi(,7825) to or from such devices or remote files is
reblocked by another copy
+../tar_texi/tar.texi(,7826) of the @command{tar} program to enforce the
specified (or default) record
+../tar_texi/tar.texi(,7827) size. The default compression parameters are
used; if you need to
+../tar_texi/tar.texi(,7828) override them, set @env{GZIP} environment
variable, e.g.:
+../tar_texi/tar.texi(,7829)
+../tar_texi/tar.texi(,7830) @smallexample
+../tar_texi/tar.texi(,7831) $ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+../tar_texi/tar.texi(,7832) @end smallexample
+../tar_texi/tar.texi(,7833)
+../tar_texi/tar.texi(,7834) @noindent
+../tar_texi/tar.texi(,7835) Another way would be to avoid the @option{--gzip}
(@option{--gunzip}, @option{--ungzip}, @option{-z}) option and run
+../tar_texi/tar.texi(,7836) @command{gzip} explicitly:
+../tar_texi/tar.texi(,7837)
+../tar_texi/tar.texi(,7838) @smallexample
+../tar_texi/tar.texi(,7839) $ @kbd{tar cf - subdir | gzip --best -c - >
archive.tar.gz}
+../tar_texi/tar.texi(,7840) @end smallexample
+../tar_texi/tar.texi(,7841)
+../tar_texi/tar.texi(,7842) @cindex corrupted archives
+../tar_texi/tar.texi(,7843) About corrupted compressed archives:
@command{gzip}'ed files have no
+../tar_texi/tar.texi(,7844) redundancy, for maximum compression. The adaptive
nature of the
+../tar_texi/tar.texi(,7845) compression scheme means that the compression
tables are implicitly
+../tar_texi/tar.texi(,7846) spread all over the archive. If you lose a few
blocks, the dynamic
+../tar_texi/tar.texi(,7847) construction of the compression tables becomes
unsynchronized, and there
+../tar_texi/tar.texi(,7848) is little chance that you could recover later in
the archive.
+../tar_texi/tar.texi(,7849)
+../tar_texi/tar.texi(,7850) There are pending suggestions for having a
per-volume or per-file
+../tar_texi/tar.texi(GNUTAR,7851) compression in @acronym{GNU} @command{tar}.
This would allow for viewing the
+../tar_texi/tar.texi(,7852) contents without decompression, and for
resynchronizing decompression at
+../tar_texi/tar.texi(,7853) every volume or file, in case of corrupted
archives. Doing so, we might
+../tar_texi/tar.texi(,7854) lose some compressibility. But this would have
make recovering easier.
+../tar_texi/tar.texi(,7855) So, there are pros and cons. We'll see!
+../tar_texi/tar.texi(,7856)
+../tar_texi/tar.texi(,7857) @opindex bzip2
+../tar_texi/tar.texi(,7858) @item -j
+../tar_texi/tar.texi(,7859) @itemx --bzip2
+../tar_texi/tar.texi(,7860) Filter the archive through @code{bzip2}.
Otherwise like @option{--gzip}.
+../tar_texi/tar.texi(,7861)
+../tar_texi/tar.texi(,7862) @opindex compress
+../tar_texi/tar.texi(,7863) @opindex uncompress
+../tar_texi/tar.texi(,7864) @item -Z
+../tar_texi/tar.texi(,7865) @itemx --compress
+../tar_texi/tar.texi(,7866) @itemx --uncompress
+../tar_texi/tar.texi(,7867) Filter the archive through @command{compress}.
Otherwise like @option{--gzip}.
+../tar_texi/tar.texi(,7868)
+../tar_texi/tar.texi(,7869) The @acronym{GNU} Project recommends you not use
+../tar_texi/tar.texi(,7870) @command{compress}, because there is a patent
covering the algorithm it
+../tar_texi/tar.texi(,7871) uses. You could be sued for patent infringement
merely by running
+../tar_texi/tar.texi(,7872) @command{compress}.
+../tar_texi/tar.texi(,7873)
+../tar_texi/tar.texi(,7874) @opindex use-compress-program
+../tar_texi/tar.texi(,7875) @item address@hidden
+../tar_texi/tar.texi(,7876) Use external compression program @var{prog}. Use
this option if you
+../tar_texi/tar.texi(GNUTAR,7877) have a compression program that
@acronym{GNU} @command{tar} does not support. There
+../tar_texi/tar.texi(,7878) are two requirements to which @var{prog} should
comply:
+../tar_texi/tar.texi(,7879)
+../tar_texi/tar.texi(,7880) First, when called without options, it should read
data from standard
+../tar_texi/tar.texi(,7881) input, compress it and output it on standard
output.
+../tar_texi/tar.texi(,7882)
+../tar_texi/tar.texi(,7883) Secondly, if called with @option{-d} argument, it
should do exactly
+../tar_texi/tar.texi(,7884) the opposite, i.e., read the compressed data from
the standard input
+../tar_texi/tar.texi(,7885) and produce uncompressed data on the standard
output.
+../tar_texi/tar.texi(,7886) @end table
+../tar_texi/tar.texi(,7887)
+../tar_texi/tar.texi(,7888) @cindex gpg, using with tar
+../tar_texi/tar.texi(,7889) @cindex gnupg, using with tar
+../tar_texi/tar.texi(,7890) @cindex Using encrypted archives
+../tar_texi/tar.texi(,7891) The @option{--use-compress-program} option, in
particular, lets you
+../tar_texi/tar.texi(,7892) implement your own filters, not necessarily
dealing with
+../tar_texi/tar.texi(,7893) compression/decomression. For example, suppose
you wish to implement
+../tar_texi/tar.texi(,7894) PGP encryption on top of compression, using
@command{gpg} (@pxref{Top,
+../tar_texi/tar.texi(,7895) gpg, gpg ---- encryption and signing tool, gpg,
GNU Privacy Guard
+../tar_texi/tar.texi(,7896) Manual}). The following script does that:
+../tar_texi/tar.texi(,7897)
+../tar_texi/tar.texi(,7898) @smallexample
+../tar_texi/tar.texi(,7899) @group
+../tar_texi/tar.texi(,7900) #! /bin/sh
+../tar_texi/tar.texi(,7901) case $1 in
+../tar_texi/tar.texi(,7902) -d) gpg --decrypt - | gzip -d -c;;
+../tar_texi/tar.texi(,7903) '') gzip -c | gpg -s ;;
+../tar_texi/tar.texi(,7904) *) echo "Unknown option $1">&2; exit 1;;
+../tar_texi/tar.texi(,7905) esac
+../tar_texi/tar.texi(,7906) @end group
+../tar_texi/tar.texi(,7907) @end smallexample
+../tar_texi/tar.texi(,7908)
+../tar_texi/tar.texi(,7909) Suppose you name it @file{gpgz} and save it
somewhere in your
+../tar_texi/tar.texi(,7910) @env{PATH}. Then the following command will
create a commpressed
+../tar_texi/tar.texi(,7911) archive signed with your private key:
+../tar_texi/tar.texi(,7912)
+../tar_texi/tar.texi(,7913) @smallexample
+../tar_texi/tar.texi(,7914) $ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
+../tar_texi/tar.texi(,7915) @end smallexample
+../tar_texi/tar.texi(,7916)
+../tar_texi/tar.texi(,7917) @noindent
+../tar_texi/tar.texi(,7918) Likewise, the following command will list its
contents:
+../tar_texi/tar.texi(,7919)
+../tar_texi/tar.texi(,7920) @smallexample
+../tar_texi/tar.texi(,7921) $ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
+../tar_texi/tar.texi(,7922) @end smallexample
+../tar_texi/tar.texi(,7923)
+../tar_texi/tar.texi(,7962)
+../tar_texi/tar.texi(,7963) @node sparse
+../tar_texi/tar.texi(,7964) @subsection Archiving Sparse Files
+../tar_texi/tar.texi(,7965) @cindex Sparse Files
+../tar_texi/tar.texi(,7966)
+../tar_texi/tar.texi(,7967) Files in the file system occasionally have
@dfn{holes}. A @dfn{hole}
+../tar_texi/tar.texi(,7968) in a file is a section of the file's contents
which was never written.
+../tar_texi/tar.texi(,7969) The contents of a hole reads as all zeros. On
many operating systems,
+../tar_texi/tar.texi(,7970) actual disk storage is not allocated for holes,
but they are counted
+../tar_texi/tar.texi(,7971) in the length of the file. If you archive such a
file, @command{tar}
+../tar_texi/tar.texi(,7972) could create an archive longer than the original.
To have @command{tar}
+../tar_texi/tar.texi(,7973) attempt to recognize the holes in a file, use
@option{--sparse}
+../tar_texi/tar.texi(,7974) (@option{-S}). When you use this option, then,
for any file using
+../tar_texi/tar.texi(,7975) less disk space than would be expected from its
length, @command{tar}
+../tar_texi/tar.texi(,7976) searches the file for consecutive stretches of
zeros. It then records
+../tar_texi/tar.texi(,7977) in the archive for the file where the consecutive
stretches of zeros
+../tar_texi/tar.texi(,7978) are, and only archives the ``real contents'' of
the file. On
+../tar_texi/tar.texi(,7979) extraction (using @option{--sparse} is not needed
on extraction) any
+../tar_texi/tar.texi(,7980) such files have holes created wherever the
continuous stretches of zeros
+../tar_texi/tar.texi(,7981) were found. Thus, if you use @option{--sparse},
@command{tar} archives
+../tar_texi/tar.texi(,7982) won't take more space than the original.
+../tar_texi/tar.texi(,7983)
+../tar_texi/tar.texi(,7984) @table @option
+../tar_texi/tar.texi(,7985) @opindex sparse
+../tar_texi/tar.texi(,7986) @item -S
+../tar_texi/tar.texi(,7987) @itemx --sparse
+../tar_texi/tar.texi(,7988) This option istructs @command{tar} to test each
file for sparseness
+../tar_texi/tar.texi(,7989) before attempting to archive it. If the file is
found to be sparse it
+../tar_texi/tar.texi(,7990) is treated specially, thus allowing to decrease
the amount of space
+../tar_texi/tar.texi(,7991) used by its image in the archive.
+../tar_texi/tar.texi(,7992)
+../tar_texi/tar.texi(,7993) This option is meaningful only when creating or
updating archives. It
+../tar_texi/tar.texi(,7994) has no effect on extraction.
+../tar_texi/tar.texi(,7995) @end table
+../tar_texi/tar.texi(,7996)
+../tar_texi/tar.texi(,7997) Consider using @option{--sparse} when performing
file system backups,
+../tar_texi/tar.texi(,7998) to avoid archiving the expanded forms of files
stored sparsely in the
+../tar_texi/tar.texi(,7999) system.
+../tar_texi/tar.texi(,8000)
+../tar_texi/tar.texi(,8001) Even if your system has no sparse files currently,
some may be
+../tar_texi/tar.texi(,8002) created in the future. If you use
@option{--sparse} while making file
+../tar_texi/tar.texi(,8003) system backups as a matter of course, you can be
assured the archive
+../tar_texi/tar.texi(,8004) will never take more space on the media than the
files take on disk
+../tar_texi/tar.texi(,8005) (otherwise, archiving a disk filled with sparse
files might take
+../tar_texi/tar.texi(,8006) hundreds of tapes). @xref{Incremental Dumps}.
+../tar_texi/tar.texi(,8007)
+../tar_texi/tar.texi(,8008) However, be aware that @option{--sparse} option
presents a serious
+../tar_texi/tar.texi(,8009) drawback. Namely, in order to determine if the
file is sparse
+../tar_texi/tar.texi(,8010) @command{tar} has to read it before trying to
archive it, so in total
+../tar_texi/tar.texi(,8011) the file is read @strong{twice}. So, always bear
in mind that the
+../tar_texi/tar.texi(,8012) time needed to process all files with this option
is roughly twice
+../tar_texi/tar.texi(,8013) the time needed to archive them without it.
+../tar_texi/tar.texi(FIXME,8038) @allow-recursion
+../tar_texi/tar.texi(FIXME,8038) @quote-arg
+../tar_texi/tar.texi(FIXME,8038)
+../tar_texi/tar.texi(,8039)
+../tar_texi/tar.texi(,8040) @cindex sparse formats, defined
+../tar_texi/tar.texi(GNUTAR,8041) When using @samp{POSIX} archive format,
@acronym{GNU} @command{tar} is able to store
+../tar_texi/tar.texi(,8042) sparse files using in three distinct ways, called
@dfn{sparse
+../tar_texi/tar.texi(,8043) formats}. A sparse format is identified by its
@dfn{number},
+../tar_texi/tar.texi(,8044) consisting, as usual of two decimal numbers,
delimited by a dot. By
+../tar_texi/tar.texi(,8045) default, format @samp{1.0} is used. If, for some
reason, you wish to
+../tar_texi/tar.texi(,8046) use an earlier format, you can select it using
+../tar_texi/tar.texi(,8047) @option{--sparse-version} option.
+../tar_texi/tar.texi(,8048)
+../tar_texi/tar.texi(,8049) @table @option
+../tar_texi/tar.texi(,8050) @opindex sparse-version
+../tar_texi/tar.texi(,8051) @item address@hidden
+../tar_texi/tar.texi(,8052)
+../tar_texi/tar.texi(,8053) Select the format to store sparse files in. Valid
@var{version} values
+../tar_texi/tar.texi(,8054) are: @samp{0.0}, @samp{0.1} and @samp{1.0}.
@xref{Sparse Formats},
+../tar_texi/tar.texi(,8055) for a detailed description of each format.
+../tar_texi/tar.texi(,8056) @end table
+../tar_texi/tar.texi(,8057)
+../tar_texi/tar.texi(,8058) Using @option{--sparse-format} option implies
@option{--sparse}.
+../tar_texi/tar.texi(,8059)
+../tar_texi/tar.texi(,8060) @node Attributes
+../tar_texi/tar.texi(,8061) @section Handling File Attributes
+../tar_texi/tar.texi(UNREVISED,8062) @quotation
+../tar_texi/tar.texi(UNREVISED,8062) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,8062) @end quotation
+../tar_texi/tar.texi(UNREVISED,8062)
+../tar_texi/tar.texi(,8063)
+../tar_texi/tar.texi(,8064) When @command{tar} reads files, it updates their
access times. To
+../tar_texi/tar.texi(,8065) avoid this, use the
@option{--atime-preserve[=METHOD]} option, which can either
+../tar_texi/tar.texi(,8066) reset the access time retroactively or avoid
changing it in the first
+../tar_texi/tar.texi(,8067) place.
+../tar_texi/tar.texi(,8068)
+../tar_texi/tar.texi(,8069) Handling of file attributes
+../tar_texi/tar.texi(,8070)
+../tar_texi/tar.texi(,8071) @table @option
+../tar_texi/tar.texi(,8072) @opindex atime-preserve
+../tar_texi/tar.texi(,8073) @item --atime-preserve
+../tar_texi/tar.texi(,8074) @itemx --atime-preserve=replace
+../tar_texi/tar.texi(,8075) @itemx --atime-preserve=system
+../tar_texi/tar.texi(,8076) Preserve the access times of files that are read.
This works only for
+../tar_texi/tar.texi(,8077) files that you own, unless you have superuser
privileges.
+../tar_texi/tar.texi(,8078)
+../tar_texi/tar.texi(,8079) @option{--atime-preserve=replace} works on most
systems, but it also
+../tar_texi/tar.texi(,8080) restores the data modification time and updates
the status change
+../tar_texi/tar.texi(,8081) time. Hence it doesn't interact with incremental
dumps nicely
+../tar_texi/tar.texi(,8082) (@pxref{Incremental Dumps}), and it can set access
or data modification times
+../tar_texi/tar.texi(,8083) incorrectly if other programs access the file
while @command{tar} is
+../tar_texi/tar.texi(,8084) running.
+../tar_texi/tar.texi(,8085)
+../tar_texi/tar.texi(,8086) @option{--atime-preserve=system} avoids changing
the access time in
+../tar_texi/tar.texi(,8087) the first place, if the operating system supports
this.
+../tar_texi/tar.texi(,8088) Unfortunately, this may or may not work on any
given operating system
+../tar_texi/tar.texi(,8089) or file system. If @command{tar} knows for sure
it won't work, it
+../tar_texi/tar.texi(,8090) complains right away.
+../tar_texi/tar.texi(,8091)
+../tar_texi/tar.texi(,8092) Currently @option{--atime-preserve} with no
operand defaults to
+../tar_texi/tar.texi(,8093) @option{--atime-preserve=replace}, but this is
intended to change to
+../tar_texi/tar.texi(,8094) @option{--atime-preserve=system} when the latter
is better-supported.
+../tar_texi/tar.texi(,8095)
+../tar_texi/tar.texi(,8096) @opindex touch
+../tar_texi/tar.texi(,8097) @item -m
+../tar_texi/tar.texi(,8098) @itemx --touch
+../tar_texi/tar.texi(,8099) Do not extract data modification time.
+../tar_texi/tar.texi(,8100)
+../tar_texi/tar.texi(,8101) When this option is used, @command{tar} leaves the
data modification times
+../tar_texi/tar.texi(,8102) of the files it extracts as the times when the
files were extracted,
+../tar_texi/tar.texi(,8103) instead of setting it to the times recorded in the
archive.
+../tar_texi/tar.texi(,8104)
+../tar_texi/tar.texi(,8105) This option is meaningless with @option{--list}
(@option{-t}).
+../tar_texi/tar.texi(,8106)
+../tar_texi/tar.texi(,8107) @opindex same-owner
+../tar_texi/tar.texi(,8108) @item --same-owner
+../tar_texi/tar.texi(,8109) Create extracted files with the same ownership
they have in the
+../tar_texi/tar.texi(,8110) archive.
+../tar_texi/tar.texi(,8111)
+../tar_texi/tar.texi(,8112) This is the default behavior for the superuser,
+../tar_texi/tar.texi(,8113) so this option is meaningful only for non-root
users, when @command{tar}
+../tar_texi/tar.texi(,8114) is executed on those systems able to give files
away. This is
+../tar_texi/tar.texi(,8115) considered as a security flaw by many people, at
least because it
+../tar_texi/tar.texi(,8116) makes quite difficult to correctly account users
for the disk space
+../tar_texi/tar.texi(,8117) they occupy. Also, the @code{suid} or @code{sgid}
attributes of
+../tar_texi/tar.texi(,8118) files are easily and silently lost when files are
given away.
+../tar_texi/tar.texi(,8119)
+../tar_texi/tar.texi(,8120) When writing an archive, @command{tar} writes the
user id and user name
+../tar_texi/tar.texi(,8121) separately. If it can't find a user name (because
the user id is not
+../tar_texi/tar.texi(,8122) in @file{/etc/passwd}), then it does not write
one. When restoring,
+../tar_texi/tar.texi(,8123) it tries to look the name (if one was written) up
in
+../tar_texi/tar.texi(,8124) @file{/etc/passwd}. If it fails, then it uses the
user id stored in
+../tar_texi/tar.texi(,8125) the archive instead.
+../tar_texi/tar.texi(,8126)
+../tar_texi/tar.texi(,8127) @opindex no-same-owner
+../tar_texi/tar.texi(,8128) @item --no-same-owner
+../tar_texi/tar.texi(,8129) @itemx -o
+../tar_texi/tar.texi(,8130) Do not attempt to restore ownership when
extracting. This is the
+../tar_texi/tar.texi(,8131) default behavior for ordinary users, so this
option has an effect
+../tar_texi/tar.texi(,8132) only for the superuser.
+../tar_texi/tar.texi(,8133)
+../tar_texi/tar.texi(,8134) @opindex numeric-owner
+../tar_texi/tar.texi(,8135) @item --numeric-owner
+../tar_texi/tar.texi(,8136) The @option{--numeric-owner} option allows (ANSI)
archives to be written
+../tar_texi/tar.texi(,8137) without user/group name information or such
information to be ignored
+../tar_texi/tar.texi(,8138) when extracting. It effectively disables the
generation and/or use
+../tar_texi/tar.texi(,8139) of user/group name information. This option
forces extraction using
+../tar_texi/tar.texi(,8140) the numeric ids from the archive, ignoring the
names.
+../tar_texi/tar.texi(,8141)
+../tar_texi/tar.texi(,8142) This is useful in certain circumstances, when
restoring a backup from
+../tar_texi/tar.texi(,8143) an emergency floppy with different passwd/group
files for example.
+../tar_texi/tar.texi(,8144) It is otherwise impossible to extract files with
the right ownerships
+../tar_texi/tar.texi(,8145) if the password file in use during the extraction
does not match the
+../tar_texi/tar.texi(,8146) one belonging to the file system(s) being
extracted. This occurs,
+../tar_texi/tar.texi(,8147) for example, if you are restoring your files after
a major crash and
+../tar_texi/tar.texi(,8148) had booted from an emergency floppy with no
password file or put your
+../tar_texi/tar.texi(,8149) disk into another machine to do the restore.
+../tar_texi/tar.texi(,8150)
+../tar_texi/tar.texi(,8151) The numeric ids are @emph{always} saved into
@command{tar} archives.
+../tar_texi/tar.texi(,8152) The identifying names are added at create time
when provided by the
+../tar_texi/tar.texi(,8153) system, unless @option{--old-archive}
(@option{-o}) is used. Numeric ids could be
+../tar_texi/tar.texi(,8154) used when moving archives between a collection of
machines using
+../tar_texi/tar.texi(,8155) a centralized management for attribution of
numeric ids to users
+../tar_texi/tar.texi(,8156) and groups. This is often made through using the
NIS capabilities.
+../tar_texi/tar.texi(,8157)
+../tar_texi/tar.texi(,8158) When making a @command{tar} file for distribution
to other sites, it
+../tar_texi/tar.texi(,8159) is sometimes cleaner to use a single owner for all
files in the
+../tar_texi/tar.texi(,8160) distribution, and nicer to specify the write
permission bits of the
+../tar_texi/tar.texi(,8161) files as stored in the archive independently of
their actual value on
+../tar_texi/tar.texi(,8162) the file system. The way to prepare a clean
distribution is usually
+../tar_texi/tar.texi(,8163) to have some Makefile rule creating a directory,
copying all needed
+../tar_texi/tar.texi(,8164) files in that directory, then setting ownership
and permissions as
+../tar_texi/tar.texi(,8165) wanted (there are a lot of possible schemes), and
only then making a
+../tar_texi/tar.texi(,8166) @command{tar} archive out of this directory,
before cleaning
+../tar_texi/tar.texi(,8167) everything out. Of course, we could add a lot of
options to
+../tar_texi/tar.texi(GNUTAR,8168) @acronym{GNU} @command{tar} for fine tuning
permissions and ownership.
+../tar_texi/tar.texi(GNUTAR,8169) This is not the good way, I think.
@acronym{GNU} @command{tar} is
+../tar_texi/tar.texi(,8170) already crowded with options and moreover, the
approach just explained
+../tar_texi/tar.texi(,8171) gives you a great deal of control already.
+../tar_texi/tar.texi(,8172)
+../tar_texi/tar.texi(xopindex,8173) @opindex address@hidden, short description}
+../tar_texi/tar.texi(xopindex,8174) @opindex address@hidden, short description}
+../tar_texi/tar.texi(,8175) @item -p
+../tar_texi/tar.texi(,8176) @itemx --same-permissions
+../tar_texi/tar.texi(,8177) @itemx --preserve-permissions
+../tar_texi/tar.texi(,8178) Extract all protection information.
+../tar_texi/tar.texi(,8179)
+../tar_texi/tar.texi(,8180) This option causes @command{tar} to set the modes
(access permissions) of
+../tar_texi/tar.texi(,8181) extracted files exactly as recorded in the
archive. If this option
+../tar_texi/tar.texi(,8182) is not used, the current @code{umask} setting
limits the permissions
+../tar_texi/tar.texi(,8183) on extracted files. This option is by default
enabled when
+../tar_texi/tar.texi(,8184) @command{tar} is executed by a superuser.
+../tar_texi/tar.texi(,8185)
+../tar_texi/tar.texi(,8186)
+../tar_texi/tar.texi(,8187) This option is meaningless with @option{--list}
(@option{-t}).
+../tar_texi/tar.texi(,8188)
+../tar_texi/tar.texi(,8189) @opindex preserve
+../tar_texi/tar.texi(,8190) @item --preserve
+../tar_texi/tar.texi(,8191) Same as both @option{--same-permissions} and
@option{--same-order}.
+../tar_texi/tar.texi(,8192)
+../tar_texi/tar.texi(,8193) The @option{--preserve} option has no equivalent
short option name.
+../tar_texi/tar.texi(,8194) It is equivalent to @option{--same-permissions}
plus @option{--same-order}.
+../tar_texi/tar.texi(,8195)
+../tar_texi/tar.texi(FIXME,8197) @allow-recursion
+../tar_texi/tar.texi(FIXME,8197) @quote-arg
+../tar_texi/tar.texi(FIXME,8197)
+../tar_texi/tar.texi(,8198)
+../tar_texi/tar.texi(,8199) @end table
+../tar_texi/tar.texi(,8200)
+../tar_texi/tar.texi(,8201) @node Portability
+../tar_texi/tar.texi(,8202) @section Making @command{tar} Archives More
Portable
+../tar_texi/tar.texi(,8203)
+../tar_texi/tar.texi(,8204) Creating a @command{tar} archive on a particular
system that is meant to be
+../tar_texi/tar.texi(,8205) useful later on many other machines and with other
versions of @command{tar}
+../tar_texi/tar.texi(,8206) is more challenging than you might think.
@command{tar} archive formats
+../tar_texi/tar.texi(,8207) have been evolving since the first versions of
Unix. Many such formats
+../tar_texi/tar.texi(,8208) are around, and are not always compatible with
each other. This section
+../tar_texi/tar.texi(,8209) discusses a few problems, and gives some advice
about making @command{tar}
+../tar_texi/tar.texi(,8210) archives more portable.
+../tar_texi/tar.texi(,8211)
+../tar_texi/tar.texi(,8212) One golden rule is simplicity. For example, limit
your @command{tar}
+../tar_texi/tar.texi(,8213) archives to contain only regular files and
directories, avoiding
+../tar_texi/tar.texi(,8214) other kind of special files. Do not attempt to
save sparse files or
+../tar_texi/tar.texi(,8215) contiguous files as such. Let's discuss a few
more problems, in turn.
+../tar_texi/tar.texi(,8216)
+../tar_texi/tar.texi(FIXME,8218) @allow-recursion
+../tar_texi/tar.texi(FIXME,8218) @quote-arg
+../tar_texi/tar.texi(FIXME,8218)
+../tar_texi/tar.texi(,8219)
+../tar_texi/tar.texi(,8220) @menu
+../tar_texi/tar.texi(,8221) * Portable Names:: Portable Names
+../tar_texi/tar.texi(,8222) * dereference:: Symbolic Links
+../tar_texi/tar.texi(,8223) * old:: Old V7 Archives
+../tar_texi/tar.texi(,8224) * ustar:: Ustar Archives
+../tar_texi/tar.texi(,8225) * gnu:: GNU and old GNU
format archives.
+../tar_texi/tar.texi(,8226) * posix:: @acronym{POSIX}
archives
+../tar_texi/tar.texi(,8227) * Checksumming:: Checksumming
Problems
+../tar_texi/tar.texi(,8228) * Large or Negative Values:: Large files,
negative time stamps, etc.
+../tar_texi/tar.texi(,8229) * Other Tars:: How to Extract
GNU-Specific Data Using
+../tar_texi/tar.texi(,8230) Other
@command{tar} Implementations
+../tar_texi/tar.texi(,8231) @end menu
+../tar_texi/tar.texi(,8232)
+../tar_texi/tar.texi(,8233) @node Portable Names
+../tar_texi/tar.texi(,8234) @subsection Portable Names
+../tar_texi/tar.texi(,8235)
+../tar_texi/tar.texi(,8236) Use portable file and member names. A name is
portable if it contains
+../tar_texi/tar.texi(,8237) only ASCII letters and digits, @samp{/}, @samp{.},
@samp{_}, and
+../tar_texi/tar.texi(,8238) @samp{-}; it cannot be empty, start with @samp{-}
or @samp{//}, or
+../tar_texi/tar.texi(,8239) contain @samp{/-}. Avoid deep directory nesting.
For portability to
+../tar_texi/tar.texi(,8240) old Unix hosts, limit your file name components to
14 characters or
+../tar_texi/tar.texi(,8241) less.
+../tar_texi/tar.texi(,8242)
+../tar_texi/tar.texi(,8243) If you intend to have your @command{tar} archives
to be read under
+../tar_texi/tar.texi(,8244) MSDOS, you should not rely on case distinction for
file names, and you
+../tar_texi/tar.texi(,8245) might use the @acronym{GNU} @command{doschk}
program for helping you
+../tar_texi/tar.texi(,8246) further diagnosing illegal MSDOS names, which are
even more limited
+../tar_texi/tar.texi(,8247) than System V's.
+../tar_texi/tar.texi(,8248)
+../tar_texi/tar.texi(,8249) @node dereference
+../tar_texi/tar.texi(,8250) @subsection Symbolic Links
+../tar_texi/tar.texi(,8251) @cindex File names, using symbolic links
+../tar_texi/tar.texi(,8252) @cindex Symbolic link as file name
+../tar_texi/tar.texi(,8253)
+../tar_texi/tar.texi(,8254) @opindex dereference
+../tar_texi/tar.texi(,8255) Normally, when @command{tar} archives a symbolic
link, it writes a
+../tar_texi/tar.texi(,8256) block to the archive naming the target of the
link. In that way, the
+../tar_texi/tar.texi(,8257) @command{tar} archive is a faithful record of the
file system contents.
+../tar_texi/tar.texi(,8258) @option{--dereference} (@option{-h}) is used with
@option{--create} (@option{-c}), and causes
+../tar_texi/tar.texi(,8259) @command{tar} to archive the files symbolic links
point to, instead of
+../tar_texi/tar.texi(,8260) the links themselves. When this option is used,
when @command{tar}
+../tar_texi/tar.texi(,8261) encounters a symbolic link, it will archive the
linked-to file,
+../tar_texi/tar.texi(,8262) instead of simply recording the presence of a
symbolic link.
+../tar_texi/tar.texi(,8263)
+../tar_texi/tar.texi(,8264) The name under which the file is stored in the
file system is not
+../tar_texi/tar.texi(,8265) recorded in the archive. To record both the
symbolic link name and
+../tar_texi/tar.texi(,8266) the file name in the system, archive the file
under both names. If
+../tar_texi/tar.texi(,8267) all links were recorded automatically by
@command{tar}, an extracted file
+../tar_texi/tar.texi(,8268) might be linked to a file name that no longer
exists in the file
+../tar_texi/tar.texi(,8269) system.
+../tar_texi/tar.texi(,8270)
+../tar_texi/tar.texi(,8271) If a linked-to file is encountered again by
@command{tar} while creating
+../tar_texi/tar.texi(,8272) the same archive, an entire second copy of it will
be stored. (This
+../tar_texi/tar.texi(,8273) @emph{might} be considered a bug.)
+../tar_texi/tar.texi(,8274)
+../tar_texi/tar.texi(,8275) So, for portable archives, do not archive symbolic
links as such,
+../tar_texi/tar.texi(,8276) and use @option{--dereference} (@option{-h}): many
systems do not support
+../tar_texi/tar.texi(,8277) symbolic links, and moreover, your distribution
might be unusable if
+../tar_texi/tar.texi(,8278) it contains unresolved symbolic links.
+../tar_texi/tar.texi(,8279)
+../tar_texi/tar.texi(,8280) @node old
+../tar_texi/tar.texi(,8281) @subsection Old V7 Archives
+../tar_texi/tar.texi(,8282) @cindex Format, old style
+../tar_texi/tar.texi(,8283) @cindex Old style format
+../tar_texi/tar.texi(,8284) @cindex Old style archives
+../tar_texi/tar.texi(,8285) @cindex v7 archive format
+../tar_texi/tar.texi(,8286)
+../tar_texi/tar.texi(,8287) Certain old versions of @command{tar} cannot
handle additional
+../tar_texi/tar.texi(,8288) information recorded by newer @command{tar}
programs. To create an
+../tar_texi/tar.texi(,8289) archive in V7 format (not ANSI), which can be read
by these old
+../tar_texi/tar.texi(,8290) versions, specify the @option{--format=v7} option
in
+../tar_texi/tar.texi(,8291) conjunction with the @option{--create}
(@option{-c}) (@command{tar} also
+../tar_texi/tar.texi(,8292) accepts @option{--portability} or
@option{--old-archive} for this
+../tar_texi/tar.texi(,8293) option). When you specify it,
+../tar_texi/tar.texi(,8294) @command{tar} leaves out information about
directories, pipes, fifos,
+../tar_texi/tar.texi(,8295) contiguous files, and device files, and specifies
file ownership by
+../tar_texi/tar.texi(,8296) group and user IDs instead of group and user names.
+../tar_texi/tar.texi(,8297)
+../tar_texi/tar.texi(,8298) When updating an archive, do not use
@option{--format=v7}
+../tar_texi/tar.texi(,8299) unless the archive was created using this option.
+../tar_texi/tar.texi(,8300)
+../tar_texi/tar.texi(,8301) In most cases, a @emph{new} format archive can be
read by an @emph{old}
+../tar_texi/tar.texi(,8302) @command{tar} program without serious trouble, so
this option should
+../tar_texi/tar.texi(,8303) seldom be needed. On the other hand, most modern
@command{tar}s are
+../tar_texi/tar.texi(,8304) able to read old format archives, so it might be
safer for you to
+../tar_texi/tar.texi(,8305) always use @option{--format=v7} for your
distributions. Notice,
+../tar_texi/tar.texi(,8306) however, that @samp{ustar} format is a better
alternative, as it is
+../tar_texi/tar.texi(,8307) free from many of @samp{v7}'s drawbacks.
+../tar_texi/tar.texi(,8308)
+../tar_texi/tar.texi(,8309) @node ustar
+../tar_texi/tar.texi(,8310) @subsection Ustar Archive Format
+../tar_texi/tar.texi(,8311)
+../tar_texi/tar.texi(,8312) @cindex ustar archive format
+../tar_texi/tar.texi(,8313) Archive format defined by @acronym{POSIX}.1-1988
specification is called
+../tar_texi/tar.texi(,8314) @code{ustar}. Although it is more flexible than
the V7 format, it
+../tar_texi/tar.texi(,8315) still has many restrictions (@xref{Formats,ustar},
for the detailed
+../tar_texi/tar.texi(,8316) description of @code{ustar} format). Along with
V7 format,
+../tar_texi/tar.texi(,8317) @code{ustar} format is a good choice for archives
intended to be read
+../tar_texi/tar.texi(,8318) with other implementations of @command{tar}.
+../tar_texi/tar.texi(,8319)
+../tar_texi/tar.texi(,8320) To create archive in @code{ustar} format, use
@option{--format=ustar}
+../tar_texi/tar.texi(,8321) option in conjunction with the @option{--create}
(@option{-c}).
+../tar_texi/tar.texi(,8322)
+../tar_texi/tar.texi(,8323) @node gnu
+../tar_texi/tar.texi(GNUTAR,8324) @subsection @acronym{GNU} and old
@acronym{GNU} @command{tar} format
+../tar_texi/tar.texi(,8325)
+../tar_texi/tar.texi(,8326) @cindex GNU archive format
+../tar_texi/tar.texi(,8327) @cindex Old GNU archive format
+../tar_texi/tar.texi(GNUTAR,8328) @acronym{GNU} @command{tar} was based on an
early draft of the
+../tar_texi/tar.texi(,8329) @acronym{POSIX} 1003.1 @code{ustar} standard.
@acronym{GNU} extensions to
+../tar_texi/tar.texi(,8330) @command{tar}, such as the support for file names
longer than 100
+../tar_texi/tar.texi(,8331) characters, use portions of the @command{tar}
header record which were
+../tar_texi/tar.texi(,8332) specified in that @acronym{POSIX} draft as unused.
Subsequent changes in
+../tar_texi/tar.texi(,8333) @acronym{POSIX} have allocated the same parts of
the header record for
+../tar_texi/tar.texi(GNUTAR,8334) other purposes. As a result, @acronym{GNU}
@command{tar} format is
+../tar_texi/tar.texi(,8335) incompatible with the current @acronym{POSIX}
specification, and with
+../tar_texi/tar.texi(,8336) @command{tar} programs that follow it.
+../tar_texi/tar.texi(,8337)
+../tar_texi/tar.texi(,8338) In the majority of cases, @command{tar} will be
configured to create
+../tar_texi/tar.texi(,8339) this format by default. This will change in the
future releases, since
+../tar_texi/tar.texi(,8340) we plan to make @samp{POSIX} format the default.
+../tar_texi/tar.texi(,8341)
+../tar_texi/tar.texi(GNUTAR,8342) To force creation a @acronym{GNU}
@command{tar} archive, use option
+../tar_texi/tar.texi(,8343) @option{--format=gnu}.
+../tar_texi/tar.texi(,8344)
+../tar_texi/tar.texi(,8345) @node posix
+../tar_texi/tar.texi(GNUTAR,8346) @subsection @acronym{GNU} @command{tar} and
@acronym{POSIX} @command{tar}
+../tar_texi/tar.texi(,8347)
+../tar_texi/tar.texi(,8348) @cindex POSIX archive format
+../tar_texi/tar.texi(,8349) @cindex PAX archive format
+../tar_texi/tar.texi(GNUTAR,8350) Starting from version 1.14 @acronym{GNU}
@command{tar} features full support for
+../tar_texi/tar.texi(,8351) @acronym{POSIX.1-2001} archives.
+../tar_texi/tar.texi(,8352)
+../tar_texi/tar.texi(,8353) A @acronym{POSIX} conformant archive will be
created if @command{tar}
+../tar_texi/tar.texi(,8354) was given @option{--format=posix}
(@option{--format=pax}) option. No
+../tar_texi/tar.texi(,8355) special option is required to read and extract
from a @acronym{POSIX}
+../tar_texi/tar.texi(,8356) archive.
+../tar_texi/tar.texi(,8357)
+../tar_texi/tar.texi(,8358) @menu
+../tar_texi/tar.texi(,8359) * PAX keywords:: Controlling Extended Header
Keywords.
+../tar_texi/tar.texi(,8360) @end menu
+../tar_texi/tar.texi(,8361)
+../tar_texi/tar.texi(,8362) @node PAX keywords
+../tar_texi/tar.texi(,8363) @subsubsection Controlling Extended Header Keywords
+../tar_texi/tar.texi(,8364)
+../tar_texi/tar.texi(,8365) @table @option
+../tar_texi/tar.texi(,8366) @opindex pax-option
+../tar_texi/tar.texi(,8367) @item address@hidden
+../tar_texi/tar.texi(,8368) Handle keywords in @acronym{PAX} extended headers.
This option is
+../tar_texi/tar.texi(,8369) equivalent to @option{-o} option of the
@command{pax} utility.
+../tar_texi/tar.texi(,8370) @end table
+../tar_texi/tar.texi(,8371)
+../tar_texi/tar.texi(,8372) @var{Keyword-list} is a comma-separated
+../tar_texi/tar.texi(,8373) list of keyword options, each keyword option
taking one of
+../tar_texi/tar.texi(,8374) the following forms:
+../tar_texi/tar.texi(,8375)
+../tar_texi/tar.texi(,8376) @table @code
+../tar_texi/tar.texi(,8377) @item address@hidden
+../tar_texi/tar.texi(,8378) When used with one of archive-creation commands,
+../tar_texi/tar.texi(,8379) this option instructs @command{tar} to omit from
extended header records
+../tar_texi/tar.texi(,8380) that it produces any keywords matching the string
@var{pattern}.
+../tar_texi/tar.texi(,8381)
+../tar_texi/tar.texi(,8382) When used in extract or list mode, this option
instructs tar
+../tar_texi/tar.texi(,8383) to ignore any keywords matching the given
@var{pattern} in the extended
+../tar_texi/tar.texi(,8384) header records. In both cases, matching is
performed using the pattern
+../tar_texi/tar.texi(,8385) matching notation described in @acronym{POSIX
1003.2}, 3.13
+../tar_texi/tar.texi(,8386) (@pxref{wildcards}). For example:
+../tar_texi/tar.texi(,8387)
+../tar_texi/tar.texi(,8388) @smallexample
+../tar_texi/tar.texi(,8389) --pax-option delete=security.*
+../tar_texi/tar.texi(,8390) @end smallexample
+../tar_texi/tar.texi(,8391)
+../tar_texi/tar.texi(,8392) would suppress security-related information.
+../tar_texi/tar.texi(,8393)
+../tar_texi/tar.texi(,8394) @item address@hidden
+../tar_texi/tar.texi(,8395)
+../tar_texi/tar.texi(,8396) This keyword allows user control over the name
that is written into the
+../tar_texi/tar.texi(,8397) ustar header blocks for the extended headers. The
name is obtained
+../tar_texi/tar.texi(,8398) from @var{string} after making the following
substitutions:
+../tar_texi/tar.texi(,8399)
+../tar_texi/tar.texi(,8400) @multitable @columnfractions .25 .55
+../tar_texi/tar.texi(,8401) @headitem Meta-character @tab Replaced By
+../tar_texi/tar.texi(,8402) @item %d @tab The directory name of the file,
equivalent to the
+../tar_texi/tar.texi(,8403) result of the @command{dirname} utility on the
translated pathname.
+../tar_texi/tar.texi(,8404) @item %f @tab The filename of the file,
equivalent to the result
+../tar_texi/tar.texi(,8405) of the @command{basename} utility on the
translated pathname.
+../tar_texi/tar.texi(,8406) @item %p @tab The process ID of the @command{tar}
process.
+../tar_texi/tar.texi(,8407) @item %% @tab A @samp{%} character.
+../tar_texi/tar.texi(,8408) @end multitable
+../tar_texi/tar.texi(,8409)
+../tar_texi/tar.texi(,8410) Any other @samp{%} characters in @var{string}
produce undefined
+../tar_texi/tar.texi(,8411) results.
+../tar_texi/tar.texi(,8412)
+../tar_texi/tar.texi(,8413) If no option @samp{exthdr.name=string} is
specified, @command{tar}
+../tar_texi/tar.texi(,8414) will use the following default value:
+../tar_texi/tar.texi(,8415)
+../tar_texi/tar.texi(,8416) @smallexample
+../tar_texi/tar.texi(,8417) %d/PaxHeaders.%p/%f
+../tar_texi/tar.texi(,8418) @end smallexample
+../tar_texi/tar.texi(,8419)
+../tar_texi/tar.texi(,8420) @item address@hidden
+../tar_texi/tar.texi(,8421) This keyword allows user control over the name
that is written into
+../tar_texi/tar.texi(,8422) the ustar header blocks for global extended header
records. The name
+../tar_texi/tar.texi(,8423) is obtained from the contents of @var{string},
after making
+../tar_texi/tar.texi(,8424) the following substitutions:
+../tar_texi/tar.texi(,8425)
+../tar_texi/tar.texi(,8426) @multitable @columnfractions .25 .55
+../tar_texi/tar.texi(,8427) @headitem Meta-character @tab Replaced By
+../tar_texi/tar.texi(,8428) @item %n @tab An integer that represents the
+../tar_texi/tar.texi(,8429) sequence number of the global extended header
record in the archive,
+../tar_texi/tar.texi(,8430) starting at 1.
+../tar_texi/tar.texi(,8431) @item %p @tab The process ID of the @command{tar}
process.
+../tar_texi/tar.texi(,8432) @item %% @tab A @samp{%} character.
+../tar_texi/tar.texi(,8433) @end multitable
+../tar_texi/tar.texi(,8434)
+../tar_texi/tar.texi(,8435) Any other @samp{%} characters in @var{string}
produce undefined results.
+../tar_texi/tar.texi(,8436)
+../tar_texi/tar.texi(,8437) If no option @samp{globexthdr.name=string} is
specified, @command{tar}
+../tar_texi/tar.texi(,8438) will use the following default value:
+../tar_texi/tar.texi(,8439)
+../tar_texi/tar.texi(,8440) @smallexample
+../tar_texi/tar.texi(,8441) $TMPDIR/GlobalHead.%p.%n
+../tar_texi/tar.texi(,8442) @end smallexample
+../tar_texi/tar.texi(,8443)
+../tar_texi/tar.texi(,8444) @noindent
+../tar_texi/tar.texi(,8445) where @samp{$TMPDIR} represents the value of the
@var{TMPDIR}
+../tar_texi/tar.texi(,8446) environment variable. If @var{TMPDIR} is not set,
@command{tar}
+../tar_texi/tar.texi(,8447) uses @samp{/tmp}.
+../tar_texi/tar.texi(,8448)
+../tar_texi/tar.texi(,8449) @item @address@hidden
+../tar_texi/tar.texi(,8450) When used with one of archive-creation commands,
these keyword/value pairs
+../tar_texi/tar.texi(,8451) will be included at the beginning of the archive
in a global extended
+../tar_texi/tar.texi(,8452) header record. When used with one of
archive-reading commands,
+../tar_texi/tar.texi(,8453) @command{tar} will behave as if it has encountered
these keyword/value
+../tar_texi/tar.texi(,8454) pairs at the beginning of the archive in a global
extended header
+../tar_texi/tar.texi(,8455) record.
+../tar_texi/tar.texi(,8456)
+../tar_texi/tar.texi(,8457) @item @var{keyword}:address@hidden
+../tar_texi/tar.texi(,8458) When used with one of archive-creation commands,
these keyword/value pairs
+../tar_texi/tar.texi(,8459) will be included as records at the beginning of an
extended header for
+../tar_texi/tar.texi(,8460) each file. This is effectively equivalent to
@address@hidden
+../tar_texi/tar.texi(,8461) form except that it creates no global extended
header records.
+../tar_texi/tar.texi(,8462)
+../tar_texi/tar.texi(,8463) When used with one of archive-reading commands,
@command{tar} will
+../tar_texi/tar.texi(,8464) behave as if these keyword/value pairs were
included as records at the
+../tar_texi/tar.texi(,8465) end of each extended header; thus, they will
override any global or
+../tar_texi/tar.texi(,8466) file-specific extended header record keywords of
the same names.
+../tar_texi/tar.texi(,8467) For example, in the command:
+../tar_texi/tar.texi(,8468)
+../tar_texi/tar.texi(,8469) @smallexample
+../tar_texi/tar.texi(,8470) tar --format=posix --create \
+../tar_texi/tar.texi(,8471) --file archive --pax-option gname:=user .
+../tar_texi/tar.texi(,8472) @end smallexample
+../tar_texi/tar.texi(,8473)
+../tar_texi/tar.texi(,8474) the group name will be forced to a new value for
all files
+../tar_texi/tar.texi(,8475) stored in the archive.
+../tar_texi/tar.texi(,8476) @end table
+../tar_texi/tar.texi(,8477)
+../tar_texi/tar.texi(,8478) @node Checksumming
+../tar_texi/tar.texi(,8479) @subsection Checksumming Problems
+../tar_texi/tar.texi(,8480)
+../tar_texi/tar.texi(,8481) SunOS and HP-UX @command{tar} fail to accept
archives created using
+../tar_texi/tar.texi(GNUTAR,8482) @acronym{GNU} @command{tar} and containing
non-ASCII file names, that
+../tar_texi/tar.texi(,8483) is, file names having characters with the eight
bit set, because they
+../tar_texi/tar.texi(GNUTAR,8484) use signed checksums, while @acronym{GNU}
@command{tar} uses unsigned
+../tar_texi/tar.texi(,8485) checksums while creating archives, as per
@acronym{POSIX} standards. On
+../tar_texi/tar.texi(GNUTAR,8486) reading, @acronym{GNU} @command{tar}
computes both checksums and
+../tar_texi/tar.texi(,8487) accept any. It is somewhat worrying that a lot of
people may go
+../tar_texi/tar.texi(,8488) around doing backup of their files using faulty
(or at least
+../tar_texi/tar.texi(,8489) non-standard) software, not learning about it
until it's time to
+../tar_texi/tar.texi(,8490) restore their missing files with an incompatible
file extractor, or
+../tar_texi/tar.texi(,8491) vice versa.
+../tar_texi/tar.texi(,8492)
+../tar_texi/tar.texi(GNUTAR,8493) @acronym{GNU} @command{tar} compute
checksums both ways, and accept
+../tar_texi/tar.texi(,8494) any on read, so @acronym{GNU} tar can read Sun
tapes even with their
+../tar_texi/tar.texi(GNUTAR,8495) wrong checksums. @acronym{GNU}
@command{tar} produces the standard
+../tar_texi/tar.texi(,8496) checksum, however, raising incompatibilities with
Sun. That is to
+../tar_texi/tar.texi(GNUTAR,8497) say, @acronym{GNU} @command{tar} has not
been modified to
+../tar_texi/tar.texi(,8498) @emph{produce} incorrect archives to be read by
buggy @command{tar}'s.
+../tar_texi/tar.texi(,8499) I've been told that more recent Sun @command{tar}
now read standard
+../tar_texi/tar.texi(,8500) archives, so maybe Sun did a similar patch, after
all?
+../tar_texi/tar.texi(,8501)
+../tar_texi/tar.texi(,8502) The story seems to be that when Sun first imported
@command{tar}
+../tar_texi/tar.texi(,8503) sources on their system, they recompiled it
without realizing that
+../tar_texi/tar.texi(,8504) the checksums were computed differently, because
of a change in
+../tar_texi/tar.texi(,8505) the default signing of @code{char}'s in their
compiler. So they
+../tar_texi/tar.texi(,8506) started computing checksums wrongly. When they
later realized their
+../tar_texi/tar.texi(,8507) mistake, they merely decided to stay compatible
with it, and with
+../tar_texi/tar.texi(,8508) themselves afterwards. Presumably, but I do not
really know, HP-UX
+../tar_texi/tar.texi(,8509) has chosen that their @command{tar} archives to be
compatible with Sun's.
+../tar_texi/tar.texi(,8510) The current standards do not favor Sun
@command{tar} format. In any
+../tar_texi/tar.texi(,8511) case, it now falls on the shoulders of SunOS and
HP-UX users to get
+../tar_texi/tar.texi(,8512) a @command{tar} able to read the good archives
they receive.
+../tar_texi/tar.texi(,8513)
+../tar_texi/tar.texi(,8514) @node Large or Negative Values
+../tar_texi/tar.texi(,8515) @subsection Large or Negative Values
+../tar_texi/tar.texi(,8516) @cindex large values
+../tar_texi/tar.texi(,8517) @cindex future time stamps
+../tar_texi/tar.texi(,8518) @cindex negative time stamps
+../tar_texi/tar.texi(UNREVISED,8519) @quotation
+../tar_texi/tar.texi(UNREVISED,8519) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,8519) @end quotation
+../tar_texi/tar.texi(UNREVISED,8519)
+../tar_texi/tar.texi(,8520)
+../tar_texi/tar.texi(,8521) The above sections suggest to use @samp{oldest
possible} archive
+../tar_texi/tar.texi(,8522) format if in doubt. However, sometimes it is not
possible. If you
+../tar_texi/tar.texi(,8523) attempt to archive a file whose metadata cannot be
represented using
+../tar_texi/tar.texi(GNUTAR,8524) required format, @acronym{GNU} @command{tar}
will print error message and ignore such a
+../tar_texi/tar.texi(,8525) file. You will than have to switch to a format
that is able to
+../tar_texi/tar.texi(,8526) handle such values. The format summary table
(@pxref{Formats}) will
+../tar_texi/tar.texi(,8527) help you to do so.
+../tar_texi/tar.texi(,8528)
+../tar_texi/tar.texi(,8529) In particular, when trying to archive files larger
than 8GB or with
+../tar_texi/tar.texi(,8530) timestamps not in the range 1970-01-01 00:00:00
through 2242-03-16
+../tar_texi/tar.texi(,8531) 12:56:31 @sc{utc}, you will have to chose between
@acronym{GNU} and
+../tar_texi/tar.texi(,8532) @acronym{POSIX} archive formats. When considering
which format to
+../tar_texi/tar.texi(,8533) choose, bear in mind that the @acronym{GNU} format
uses
+../tar_texi/tar.texi(,8534) two's-complement base-256 notation to store values
that do not fit
+../tar_texi/tar.texi(,8535) into standard @acronym{ustar} range. Such
archives can generally be
+../tar_texi/tar.texi(GNUTAR,8536) read only by a @acronym{GNU} @command{tar}
implementation. Moreover, they sometimes
+../tar_texi/tar.texi(GNUTAR,8537) cannot be correctly restored on another
hosts even by @acronym{GNU} @command{tar}. For
+../tar_texi/tar.texi(,8538) example, using two's complement representation for
negative time
+../tar_texi/tar.texi(,8539) stamps that assumes a signed 32-bit @code{time_t}
generates archives
+../tar_texi/tar.texi(,8540) that are not portable to hosts with differing
@code{time_t}
+../tar_texi/tar.texi(,8541) representations.
+../tar_texi/tar.texi(,8542)
+../tar_texi/tar.texi(,8543) On the other hand, @acronym{POSIX} archives,
generally speaking, can
+../tar_texi/tar.texi(,8544) be extracted by any tar implementation that
understands older
+../tar_texi/tar.texi(,8545) @acronym{ustar} format. The only exception are
files larger than 8GB.
+../tar_texi/tar.texi(,8546)
+../tar_texi/tar.texi(FIXME,8548) @allow-recursion
+../tar_texi/tar.texi(FIXME,8548) @quote-arg
+../tar_texi/tar.texi(FIXME,8548)
+../tar_texi/tar.texi(,8549)
+../tar_texi/tar.texi(,8550) @node Other Tars
+../tar_texi/tar.texi(,8551) @subsection How to Extract GNU-Specific Data Using
Other @command{tar} Implementations
+../tar_texi/tar.texi(,8552)
+../tar_texi/tar.texi(,8553) In previous sections you became acquainted with
various quircks
+../tar_texi/tar.texi(,8554) necessary to make your archives portable.
Sometimes you may need to
+../tar_texi/tar.texi(,8555) extract archives containing GNU-specific members
using some
+../tar_texi/tar.texi(,8556) third-party @command{tar} implementation or an
older version of
+../tar_texi/tar.texi(GNUTAR,8557) @acronym{GNU} @command{tar}. Of course your
best bet is to have @acronym{GNU} @command{tar} installed,
+../tar_texi/tar.texi(,8558) but if it is for some reason impossible, this
section will explain
+../tar_texi/tar.texi(,8559) how to cope without it.
+../tar_texi/tar.texi(,8560)
+../tar_texi/tar.texi(,8561) When we speak about @dfn{GNU-specific} members we
mean two classes of
+../tar_texi/tar.texi(,8562) them: members split between the volumes of a
multi-volume archive and
+../tar_texi/tar.texi(,8563) sparse members. You will be able to always
recover such members if
+../tar_texi/tar.texi(,8564) the archive is in PAX format. In addition split
members can be
+../tar_texi/tar.texi(,8565) recovered from archives in old GNU format. The
following subsections
+../tar_texi/tar.texi(,8566) describe the required procedures in detail.
+../tar_texi/tar.texi(,8567)
+../tar_texi/tar.texi(,8568) @menu
+../tar_texi/tar.texi(,8569) * Split Recovery:: Members Split Between
Volumes
+../tar_texi/tar.texi(,8570) * Sparse Recovery:: Sparse Members
+../tar_texi/tar.texi(,8571) @end menu
+../tar_texi/tar.texi(,8572)
+../tar_texi/tar.texi(,8573) @node Split Recovery
+../tar_texi/tar.texi(,8574) @subsubsection Extracting Members Split Between
Volumes
+../tar_texi/tar.texi(,8575)
+../tar_texi/tar.texi(,8576) @cindex Mutli-volume archives, extracting using
non-GNU tars
+../tar_texi/tar.texi(,8577) If a member is split between several volumes of an
old GNU format archive
+../tar_texi/tar.texi(,8578) most third party @command{tar} implementation will
fail to extract
+../tar_texi/tar.texi(,8579) it. To extract it, use @command{tarcat} program
(@pxref{Tarcat}).
+../tar_texi/tar.texi(,8580) This program is available from
+../tar_texi/tar.texi(GNUTAR,8581)
@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @acronym{GNU}
@command{tar}
+../tar_texi/tar.texi(,8582) home page}. It concatenates several archive
volumes into a single
+../tar_texi/tar.texi(,8583) valid archive. For example, if you have three
volumes named from
+../tar_texi/tar.texi(,8584) @file{vol-1.tar} to @file{vol-2.tar}, you can do
the following to
+../tar_texi/tar.texi(,8585) extract them using a third-party @command{tar}:
+../tar_texi/tar.texi(,8586)
+../tar_texi/tar.texi(,8587) @smallexample
+../tar_texi/tar.texi(,8588) $ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar
xf -}
+../tar_texi/tar.texi(,8589) @end smallexample
+../tar_texi/tar.texi(,8590)
+../tar_texi/tar.texi(,8591) @cindex Mutli-volume archives in PAX format,
extracting using non-GNU tars
+../tar_texi/tar.texi(,8592) You could use this approach for many (although not
all) PAX
+../tar_texi/tar.texi(,8593) format archives as well. However, extracting
split members from a PAX
+../tar_texi/tar.texi(,8594) archive is a much easier task, because PAX volumes
are constructed in
+../tar_texi/tar.texi(,8595) such a way that each part of a split member is
extracted as a
+../tar_texi/tar.texi(,8596) different file by @command{tar} implementations
that are not aware of
+../tar_texi/tar.texi(,8597) GNU extensions. More specifically, the very first
part retains its
+../tar_texi/tar.texi(,8598) original name, and all subsequent parts are named
using the pattern:
+../tar_texi/tar.texi(,8599)
+../tar_texi/tar.texi(,8600) @smallexample
+../tar_texi/tar.texi(,8601) %d/GNUFileParts.%p/%f.%n
+../tar_texi/tar.texi(,8602) @end smallexample
+../tar_texi/tar.texi(,8603)
+../tar_texi/tar.texi(,8604) @noindent
+../tar_texi/tar.texi(,8605) where symbols preceeded by @samp{%} are @dfn{macro
characters} that
+../tar_texi/tar.texi(,8606) have the following meaning:
+../tar_texi/tar.texi(,8607)
+../tar_texi/tar.texi(,8608) @multitable @columnfractions .25 .55
+../tar_texi/tar.texi(,8609) @headitem Meta-character @tab Replaced By
+../tar_texi/tar.texi(,8610) @item %d @tab The directory name of the file,
equivalent to the
+../tar_texi/tar.texi(,8611) result of the @command{dirname} utility on its
full name.
+../tar_texi/tar.texi(,8612) @item %f @tab The file name of the file,
equivalent to the result
+../tar_texi/tar.texi(,8613) of the @command{basename} utility on its full name.
+../tar_texi/tar.texi(,8614) @item %p @tab The process ID of the @command{tar}
process that
+../tar_texi/tar.texi(,8615) created the archive.
+../tar_texi/tar.texi(,8616) @item %n @tab Ordinal number of this particular
part.
+../tar_texi/tar.texi(,8617) @end multitable
+../tar_texi/tar.texi(,8618)
+../tar_texi/tar.texi(,8619) For example, if, a file @file{var/longfile} was
split during archive
+../tar_texi/tar.texi(,8620) creation between three volumes, and the creator
@command{tar} process
+../tar_texi/tar.texi(,8621) had process ID @samp{27962}, then the member names
will be:
+../tar_texi/tar.texi(,8622)
+../tar_texi/tar.texi(,8623) @smallexample
+../tar_texi/tar.texi(,8624) var/longfile
+../tar_texi/tar.texi(,8625) var/GNUFileParts.27962/longfile.1
+../tar_texi/tar.texi(,8626) var/GNUFileParts.27962/longfile.2
+../tar_texi/tar.texi(,8627) @end smallexample
+../tar_texi/tar.texi(,8628)
+../tar_texi/tar.texi(,8629) When you extract your archive using a third-party
@command{tar}, these
+../tar_texi/tar.texi(,8630) files will be created on your disk, and the only
thing you will need
+../tar_texi/tar.texi(,8631) to do to restore your file in its original form is
concatenate them in
+../tar_texi/tar.texi(,8632) the proper order, for example:
+../tar_texi/tar.texi(,8633)
+../tar_texi/tar.texi(,8634) @smallexample
+../tar_texi/tar.texi(,8635) @group
+../tar_texi/tar.texi(,8636) $ @kbd{cd var}
+../tar_texi/tar.texi(,8637) $ @kbd{cat GNUFileParts.27962/longfile.1 \
+../tar_texi/tar.texi(,8638) GNUFileParts.27962/longfile.2 >> longfile}
+../tar_texi/tar.texi(,8639) $ rm -f GNUFileParts.27962
+../tar_texi/tar.texi(,8640) @end group
+../tar_texi/tar.texi(,8641) @end smallexample
+../tar_texi/tar.texi(,8642)
+../tar_texi/tar.texi(,8643) Notice, that if the @command{tar} implementation
you use supports PAX
+../tar_texi/tar.texi(,8644) format archives, it will probably emit warnings
about unknown keywords
+../tar_texi/tar.texi(,8645) during extraction. They will lool like this:
+../tar_texi/tar.texi(,8646)
+../tar_texi/tar.texi(,8647) @smallexample
+../tar_texi/tar.texi(,8648) @group
+../tar_texi/tar.texi(,8649) Tar file too small
+../tar_texi/tar.texi(,8650) Unknown extended header keyword
'GNU.volume.filename' ignored.
+../tar_texi/tar.texi(,8651) Unknown extended header keyword 'GNU.volume.size'
ignored.
+../tar_texi/tar.texi(,8652) Unknown extended header keyword
'GNU.volume.offset' ignored.
+../tar_texi/tar.texi(,8653) @end group
+../tar_texi/tar.texi(,8654) @end smallexample
+../tar_texi/tar.texi(,8655)
+../tar_texi/tar.texi(,8656) @noindent
+../tar_texi/tar.texi(,8657) You can safely ignore these warnings.
+../tar_texi/tar.texi(,8658)
+../tar_texi/tar.texi(,8659) If your @command{tar} implementation is not
PAX-aware, you will get
+../tar_texi/tar.texi(,8660) more warnigns and more files generated on your
disk, e.g.:
+../tar_texi/tar.texi(,8661)
+../tar_texi/tar.texi(,8662) @smallexample
+../tar_texi/tar.texi(,8663) @group
+../tar_texi/tar.texi(,8664) $ @kbd{tar xf vol-1.tar}
+../tar_texi/tar.texi(,8665) var/PaxHeaders.27962/longfile: Unknown file type
'x', extracted as
+../tar_texi/tar.texi(,8666) normal file
+../tar_texi/tar.texi(,8667) Unexpected EOF in archive
+../tar_texi/tar.texi(,8668) $ @kbd{tar xf vol-2.tar}
+../tar_texi/tar.texi(,8669) tmp/GlobalHead.27962.1: Unknown file type 'g',
extracted as normal file
+../tar_texi/tar.texi(,8670) GNUFileParts.27962/PaxHeaders.27962/sparsefile.1:
Unknown file type
+../tar_texi/tar.texi(,8671) 'x', extracted as normal file
+../tar_texi/tar.texi(,8672) @end group
+../tar_texi/tar.texi(,8673) @end smallexample
+../tar_texi/tar.texi(,8674)
+../tar_texi/tar.texi(,8675) Ignore these warnings. The @file{PaxHeaders.*}
directories created
+../tar_texi/tar.texi(,8676) will contain files with @dfn{extended header
keywords} describing the
+../tar_texi/tar.texi(,8677) extracted files. You can delete them, unless they
describe sparse
+../tar_texi/tar.texi(,8678) members. Read further to learn more about them.
+../tar_texi/tar.texi(,8679)
+../tar_texi/tar.texi(,8680) @node Sparse Recovery
+../tar_texi/tar.texi(,8681) @subsubsection Extracting Sparse Members
+../tar_texi/tar.texi(,8682)
+../tar_texi/tar.texi(,8683) @cindex sparse files, extracting with non-GNU tars
+../tar_texi/tar.texi(,8684) Any @command{tar} implementation will be able to
extract sparse members from a
+../tar_texi/tar.texi(,8685) PAX archive. However, the extracted files will be
@dfn{condensed},
+../tar_texi/tar.texi(,8686) i.e. any zero blocks will be removed from them.
When we restore such
+../tar_texi/tar.texi(,8687) a condensed file to its original form, by adding
zero bloks (or
+../tar_texi/tar.texi(,8688) @dfn{holes}) back to their original locations, we
call this process
+../tar_texi/tar.texi(,8689) @dfn{expanding} a compressed sparse file.
+../tar_texi/tar.texi(,8690)
+../tar_texi/tar.texi(,8691) @pindex xsparse
+../tar_texi/tar.texi(,8692) To expand a file, you will need a simple auxiliary
program called
+../tar_texi/tar.texi(,8693) @command{xsparse}. It is available in source form
from
+../tar_texi/tar.texi(GNUTAR,8694)
@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @acronym{GNU}
@command{tar}
+../tar_texi/tar.texi(,8695) home page}.
+../tar_texi/tar.texi(,8696)
+../tar_texi/tar.texi(,8697) @cindex sparse files v.1.0, extracting with
non-GNU tars
+../tar_texi/tar.texi(,8698) Let's begin with archive members in @dfn{sparse
format
+../tar_texi/tar.texi(,8699) version address@hidden@xref{PAX 1}.}, which are
the easiest to expand.
+../tar_texi/tar.texi(,8700) The condensed file will contain both file map and
file data, so no
+../tar_texi/tar.texi(,8701) additional data will be needed to restore it. If
the original file
+../tar_texi/tar.texi(,8702) name was @address@hidden/@var{name}}, then the
condensed file will be
+../tar_texi/tar.texi(,8703) named
@address@hidden/@/address@hidden/@/@var{name}}, where
+../tar_texi/tar.texi(,8704) @var{n} is a decimal address@hidden speaking,
@var{n} is a
+../tar_texi/tar.texi(,8705) @dfn{process ID} of the @command{tar} process
which created the
+../tar_texi/tar.texi(,8706) archive (@pxref{PAX keywords}).}.
+../tar_texi/tar.texi(,8707)
+../tar_texi/tar.texi(,8708) To expand a version 1.0 file, run
@command{xsparse} as follows:
+../tar_texi/tar.texi(,8709)
+../tar_texi/tar.texi(,8710) @smallexample
+../tar_texi/tar.texi(,8711) $ @kbd{xsparse @file{cond-file}}
+../tar_texi/tar.texi(,8712) @end smallexample
+../tar_texi/tar.texi(,8713)
+../tar_texi/tar.texi(,8714) @noindent
+../tar_texi/tar.texi(,8715) where @file{cond-file} is the name of the
condensed file. The utility
+../tar_texi/tar.texi(,8716) will deduce the name for the resulting expanded
file using the
+../tar_texi/tar.texi(,8717) following algorithm:
+../tar_texi/tar.texi(,8718)
+../tar_texi/tar.texi(,8719) @enumerate 1
+../tar_texi/tar.texi(,8720) @item If @file{cond-file} does not contain any
directories,
+../tar_texi/tar.texi(,8721) @file{../cond-file} will be used;
+../tar_texi/tar.texi(,8722)
+../tar_texi/tar.texi(,8723) @item If @file{cond-file} has the form
+../tar_texi/tar.texi(,8724) @address@hidden/@var{t}/@var{name}}, where both
@var{t} and @var{name}
+../tar_texi/tar.texi(,8725) are simple names, with no @samp{/} characters in
them, the output file
+../tar_texi/tar.texi(,8726) name will be @address@hidden/@var{name}}.
+../tar_texi/tar.texi(,8727)
+../tar_texi/tar.texi(,8728) @item Otherwise, if @file{cond-file} has the form
+../tar_texi/tar.texi(,8729) @address@hidden/@var{name}}, the output file name
will be
+../tar_texi/tar.texi(,8730) @address@hidden
+../tar_texi/tar.texi(,8731) @end enumerate
+../tar_texi/tar.texi(,8732)
+../tar_texi/tar.texi(,8733) In the unlikely case when this algorithm does not
suite your needs,
+../tar_texi/tar.texi(,8734) you can explicitely specify output file name as a
second argument to
+../tar_texi/tar.texi(,8735) the command:
+../tar_texi/tar.texi(,8736)
+../tar_texi/tar.texi(,8737) @smallexample
+../tar_texi/tar.texi(,8738) $ @kbd{xsparse @file{cond-file}}
+../tar_texi/tar.texi(,8739) @end smallexample
+../tar_texi/tar.texi(,8740)
+../tar_texi/tar.texi(,8741) It is often a good idea to run @command{xsparse}
in @dfn{dry run} mode
+../tar_texi/tar.texi(,8742) first. In this mode, the command does not
actually expand the file,
+../tar_texi/tar.texi(,8743) but verbosely lists all actions it would be taking
to do so. The dry
+../tar_texi/tar.texi(,8744) run mode is enabled by @option{-n} command line
argument:
+../tar_texi/tar.texi(,8745)
+../tar_texi/tar.texi(,8746) @smallexample
+../tar_texi/tar.texi(,8747) @group
+../tar_texi/tar.texi(,8748) $ @kbd{xsparse -n
/home/gray/GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8749) Reading v.1.0 sparse map
+../tar_texi/tar.texi(,8750) Expanding file
`/home/gray/GNUSparseFile.6058/sparsefile' to
+../tar_texi/tar.texi(,8751) `/home/gray/sparsefile'
+../tar_texi/tar.texi(,8752) Finished dry run
+../tar_texi/tar.texi(,8753) @end group
+../tar_texi/tar.texi(,8754) @end smallexample
+../tar_texi/tar.texi(,8755)
+../tar_texi/tar.texi(,8756) To actually expand the file, you would run:
+../tar_texi/tar.texi(,8757)
+../tar_texi/tar.texi(,8758) @smallexample
+../tar_texi/tar.texi(,8759) $ @kbd{xsparse
/home/gray/GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8760) @end smallexample
+../tar_texi/tar.texi(,8761)
+../tar_texi/tar.texi(,8762) @noindent
+../tar_texi/tar.texi(,8763) The program behaves the same way all UNIX
utilities do: it will keep
+../tar_texi/tar.texi(,8764) quiet unless it has simething important to tell
you (e.g. an error
+../tar_texi/tar.texi(,8765) condition or something). If you wish it to
produce verbose output,
+../tar_texi/tar.texi(,8766) similar to that from the dry run mode, give it
@option{-v} option:
+../tar_texi/tar.texi(,8767)
+../tar_texi/tar.texi(,8768) @smallexample
+../tar_texi/tar.texi(,8769) @group
+../tar_texi/tar.texi(,8770) $ @kbd{xsparse -v
/home/gray/GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8771) Reading v.1.0 sparse map
+../tar_texi/tar.texi(,8772) Expanding file
`/home/gray/GNUSparseFile.6058/sparsefile' to
+../tar_texi/tar.texi(,8773) `/home/gray/sparsefile'
+../tar_texi/tar.texi(,8774) Done
+../tar_texi/tar.texi(,8775) @end group
+../tar_texi/tar.texi(,8776) @end smallexample
+../tar_texi/tar.texi(,8777)
+../tar_texi/tar.texi(,8778) Additionally, if your @command{tar} implementation
has extracted the
+../tar_texi/tar.texi(,8779) @dfn{extended headers} for this file, you can
instruct @command{xstar}
+../tar_texi/tar.texi(,8780) to use them in order to verify the integrity of
the expanded file.
+../tar_texi/tar.texi(,8781) The option @option{-x} sets the name of the
extended header file to
+../tar_texi/tar.texi(,8782) use. Continuing our example:
+../tar_texi/tar.texi(,8783)
+../tar_texi/tar.texi(,8784) @smallexample
+../tar_texi/tar.texi(,8785) @group
+../tar_texi/tar.texi(,8786) $ @kbd{xsparse -v -x
/home/gray/PaxHeaders.6058/sparsefile \
+../tar_texi/tar.texi(,8787) /home/gray/GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8788) Reading extended header file
+../tar_texi/tar.texi(,8789) Found variable GNU.sparse.major = 1
+../tar_texi/tar.texi(,8790) Found variable GNU.sparse.minor = 0
+../tar_texi/tar.texi(,8791) Found variable GNU.sparse.name = sparsefile
+../tar_texi/tar.texi(,8792) Found variable GNU.sparse.realsize = 217481216
+../tar_texi/tar.texi(,8793) Reading v.1.0 sparse map
+../tar_texi/tar.texi(,8794) Expanding file
`/home/gray/GNUSparseFile.6058/sparsefile' to
+../tar_texi/tar.texi(,8795) `/home/gray/sparsefile'
+../tar_texi/tar.texi(,8796) Done
+../tar_texi/tar.texi(,8797) @end group
+../tar_texi/tar.texi(,8798) @end smallexample
+../tar_texi/tar.texi(,8799)
+../tar_texi/tar.texi(,8800) @anchor{extracting sparse v.0.x}
+../tar_texi/tar.texi(,8801) @cindex sparse files v.0.1, extracting with
non-GNU tars
+../tar_texi/tar.texi(,8802) @cindex sparse files v.0.0, extracting with
non-GNU tars
+../tar_texi/tar.texi(,8803) An @dfn{extended header} is a special
@command{tar} archive header
+../tar_texi/tar.texi(,8804) that precedes an archive member and contains a set
of
+../tar_texi/tar.texi(,8805) @dfn{variables}, describing the member properties
that cannot be
+../tar_texi/tar.texi(,8806) stored in the standard @code{ustar} header. While
optional for
+../tar_texi/tar.texi(,8807) expanding sparse version 1.0 members, use of
extended headers is
+../tar_texi/tar.texi(,8808) mandatory when expanding sparse members in older
sparse formats: v.0.0
+../tar_texi/tar.texi(,8809) and v.0.1 (The sparse formats are described in
detail in @pxref{Sparse
+../tar_texi/tar.texi(,8810) Formats}). So, for this format, the question is:
how to obtain
+../tar_texi/tar.texi(,8811) extended headers from the archive?
+../tar_texi/tar.texi(,8812)
+../tar_texi/tar.texi(,8813) If you use a @command{tar} implementation that
does not support PAX
+../tar_texi/tar.texi(,8814) format, extended headers for each member will be
extracted as a
+../tar_texi/tar.texi(,8815) separate file. If we represent the member name as
+../tar_texi/tar.texi(,8816) @address@hidden/@var{name}}, then the extended
header file will be
+../tar_texi/tar.texi(,8817) named
@address@hidden/@/address@hidden/@/@var{name}}, where
+../tar_texi/tar.texi(,8818) @var{n} is an integer number.
+../tar_texi/tar.texi(,8819)
+../tar_texi/tar.texi(,8820) Things become more difficult if your @command{tar}
implementation
+../tar_texi/tar.texi(,8821) does support PAX headers, because in this case you
will have to
+../tar_texi/tar.texi(,8822) manually extract the headers. We recommend the
following algorithm:
+../tar_texi/tar.texi(,8823)
+../tar_texi/tar.texi(,8824) @enumerate 1
+../tar_texi/tar.texi(,8825) @item
+../tar_texi/tar.texi(,8826) Consult the documentation for your @command{tar}
implementation for an
+../tar_texi/tar.texi(,8827) option that will print @dfn{block numbers} along
with the archive
+../tar_texi/tar.texi(GNUTAR,8828) listing (analogous to @acronym{GNU}
@command{tar}'s @option{-R} option). For example,
+../tar_texi/tar.texi(,8829) @command{star} has @option{-block-number}.
+../tar_texi/tar.texi(,8830)
+../tar_texi/tar.texi(,8831) @item
+../tar_texi/tar.texi(,8832) Obtain the verbose listing using the @samp{block
number} option, and
+../tar_texi/tar.texi(,8833) find the position of the sparse member in question
and the member
+../tar_texi/tar.texi(,8834) immediately following it. For example, running
@command{star} on our
+../tar_texi/tar.texi(,8835) archive we obtain:
+../tar_texi/tar.texi(,8836)
+../tar_texi/tar.texi(,8837) @smallexample
+../tar_texi/tar.texi(,8838) @group
+../tar_texi/tar.texi(,8839) $ @kbd{star -t -v -block-number -f arc.tar}
+../tar_texi/tar.texi(,8840) @dots{}
+../tar_texi/tar.texi(,8841) star: Unknown extended header keyword
'GNU.sparse.size' ignored.
+../tar_texi/tar.texi(,8842) star: Unknown extended header keyword
'GNU.sparse.numblocks' ignored.
+../tar_texi/tar.texi(,8843) star: Unknown extended header keyword
'GNU.sparse.name' ignored.
+../tar_texi/tar.texi(,8844) star: Unknown extended header keyword
'GNU.sparse.map' ignored.
+../tar_texi/tar.texi(,8845) block 56: 425984 -rw-r--r-- gray/users
Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
+../tar_texi/tar.texi(,8846) block 897: 65391 -rw-r--r-- gray/users
Jun 24 20:06 2006 README
+../tar_texi/tar.texi(,8847) @dots{}
+../tar_texi/tar.texi(,8848) @end group
+../tar_texi/tar.texi(,8849) @end smallexample
+../tar_texi/tar.texi(,8850)
+../tar_texi/tar.texi(,8851) @noindent
+../tar_texi/tar.texi(,8852) (as usual, ignore the warnings about unknown
keywords.)
+../tar_texi/tar.texi(,8853)
+../tar_texi/tar.texi(,8854) @item
+../tar_texi/tar.texi(,8855) Let @var{size} be the size of the sparse member,
@var{Bs} be its block number
+../tar_texi/tar.texi(,8856) and @var{Bn} be the block number of the next
member.
+../tar_texi/tar.texi(,8857) Compute:
+../tar_texi/tar.texi(,8858)
+../tar_texi/tar.texi(,8859) @smallexample
+../tar_texi/tar.texi(,8860) @var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2
+../tar_texi/tar.texi(,8861) @end smallexample
+../tar_texi/tar.texi(,8862)
+../tar_texi/tar.texi(,8863) @noindent
+../tar_texi/tar.texi(,8864) This number gives the size of the extended header
part in tar @dfn{blocks}.
+../tar_texi/tar.texi(,8865) In our example, this formula gives: @code{897 - 56
- 425984 / 512 - 2
+../tar_texi/tar.texi(,8866) = 7}.
+../tar_texi/tar.texi(,8867)
+../tar_texi/tar.texi(,8868) @item
+../tar_texi/tar.texi(,8869) Use @command{dd} to extract the headers:
+../tar_texi/tar.texi(,8870)
+../tar_texi/tar.texi(,8871) @smallexample
+../tar_texi/tar.texi(,8872) @kbd{dd address@hidden address@hidden bs=512
address@hidden address@hidden
+../tar_texi/tar.texi(,8873) @end smallexample
+../tar_texi/tar.texi(,8874)
+../tar_texi/tar.texi(,8875) @noindent
+../tar_texi/tar.texi(,8876) where @var{archive} is the archive name,
@var{hname} is a name of the
+../tar_texi/tar.texi(,8877) file to store the extended header in, @var{Bs} and
@var{N} are
+../tar_texi/tar.texi(,8878) computed in previous steps.
+../tar_texi/tar.texi(,8879)
+../tar_texi/tar.texi(,8880) In our example, this command will be
+../tar_texi/tar.texi(,8881)
+../tar_texi/tar.texi(,8882) @smallexample
+../tar_texi/tar.texi(,8883) $ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56
count=7}
+../tar_texi/tar.texi(,8884) @end smallexample
+../tar_texi/tar.texi(,8885) @end enumerate
+../tar_texi/tar.texi(,8886)
+../tar_texi/tar.texi(,8887) Finally, you can expand the condensed file, using
the obtained header:
+../tar_texi/tar.texi(,8888)
+../tar_texi/tar.texi(,8889) @smallexample
+../tar_texi/tar.texi(,8890) @group
+../tar_texi/tar.texi(,8891) $ @kbd{xsparse -v -x xhdr
GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8892) Reading extended header file
+../tar_texi/tar.texi(,8893) Found variable GNU.sparse.size = 217481216
+../tar_texi/tar.texi(,8894) Found variable GNU.sparse.numblocks = 208
+../tar_texi/tar.texi(,8895) Found variable GNU.sparse.name = sparsefile
+../tar_texi/tar.texi(,8896) Found variable GNU.sparse.map =
0,2048,1050624,2048,@dots{}
+../tar_texi/tar.texi(,8897) Expanding file `GNUSparseFile.28124/sparsefile' to
`sparsefile'
+../tar_texi/tar.texi(,8898) Done
+../tar_texi/tar.texi(,8899) @end group
+../tar_texi/tar.texi(,8900) @end smallexample
+../tar_texi/tar.texi(,8901)
+../tar_texi/tar.texi(,8902) @node cpio
+../tar_texi/tar.texi(,8903) @section Comparison of @command{tar} and
@command{cpio}
+../tar_texi/tar.texi(UNREVISED,8904) @quotation
+../tar_texi/tar.texi(UNREVISED,8904) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,8904) @end quotation
+../tar_texi/tar.texi(UNREVISED,8904)
+../tar_texi/tar.texi(,8905)
+../tar_texi/tar.texi(FIXME,8906) @allow-recursion
+../tar_texi/tar.texi(FIXME,8906) @quote-arg
+../tar_texi/tar.texi(FIXME,8906)
+../tar_texi/tar.texi(,8907)
+../tar_texi/tar.texi(,8908) The @command{cpio} archive formats, like
@command{tar}, do have maximum
+../tar_texi/tar.texi(,8909) pathname lengths. The binary and old ASCII
formats have a max path
+../tar_texi/tar.texi(,8910) length of 256, and the new ASCII and CRC ASCII
formats have a max
+../tar_texi/tar.texi(,8911) path length of 1024. @acronym{GNU} @command{cpio}
can read and write archives
+../tar_texi/tar.texi(,8912) with arbitrary pathname lengths, but other
@command{cpio} implementations
+../tar_texi/tar.texi(,8913) may crash unexplainedly trying to read them.
+../tar_texi/tar.texi(,8914)
+../tar_texi/tar.texi(,8915) @command{tar} handles symbolic links in the form
in which it comes in BSD;
+../tar_texi/tar.texi(,8916) @command{cpio} doesn't handle symbolic links in
the form in which it comes
+../tar_texi/tar.texi(,8917) in System V prior to SVR4, and some vendors may
have added symlinks
+../tar_texi/tar.texi(,8918) to their system without enhancing @command{cpio}
to know about them.
+../tar_texi/tar.texi(,8919) Others may have enhanced it in a way other than
the way I did it
+../tar_texi/tar.texi(,8920) at Sun, and which was adopted by AT&T (and which
is, I think, also
+../tar_texi/tar.texi(,8921) present in the @command{cpio} that Berkeley picked
up from AT&T and put
+../tar_texi/tar.texi(,8922) into a later BSD release---I think I gave them my
changes).
+../tar_texi/tar.texi(,8923)
+../tar_texi/tar.texi(,8924) (SVR4 does some funny stuff with @command{tar};
basically, its @command{cpio}
+../tar_texi/tar.texi(,8925) can handle @command{tar} format input, and write
it on output, and it
+../tar_texi/tar.texi(,8926) probably handles symbolic links. They may not
have bothered doing
+../tar_texi/tar.texi(,8927) anything to enhance @command{tar} as a result.)
+../tar_texi/tar.texi(,8928)
+../tar_texi/tar.texi(,8929) @command{cpio} handles special files; traditional
@command{tar} doesn't.
+../tar_texi/tar.texi(,8930)
+../tar_texi/tar.texi(,8931) @command{tar} comes with V7, System III, System V,
and BSD source;
+../tar_texi/tar.texi(,8932) @command{cpio} comes only with System III, System
V, and later BSD
+../tar_texi/tar.texi(,8933) (4.3-tahoe and later).
+../tar_texi/tar.texi(,8934)
+../tar_texi/tar.texi(,8935) @command{tar}'s way of handling multiple hard
links to a file can handle
+../tar_texi/tar.texi(,8936) file systems that support 32-bit inumbers (e.g.,
the BSD file system);
+../tar_texi/tar.texi(,8937) @command{cpio}s way requires you to play some
games (in its "binary"
+../tar_texi/tar.texi(,8938) format, i-numbers are only 16 bits, and in its
"portable ASCII" format,
+../tar_texi/tar.texi(,8939) they're 18 bits---it would have to play games with
the "file system ID"
+../tar_texi/tar.texi(,8940) field of the header to make sure that the file
system ID/i-number pairs
+../tar_texi/tar.texi(,8941) of different files were always different), and I
don't know which
+../tar_texi/tar.texi(,8942) @command{cpio}s, if any, play those games. Those
that don't might get
+../tar_texi/tar.texi(,8943) confused and think two files are the same file
when they're not, and
+../tar_texi/tar.texi(,8944) make hard links between them.
+../tar_texi/tar.texi(,8945)
+../tar_texi/tar.texi(,8946) @command{tar}s way of handling multiple hard links
to a file places only
+../tar_texi/tar.texi(,8947) one copy of the link on the tape, but the name
attached to that copy
+../tar_texi/tar.texi(,8948) is the @emph{only} one you can use to retrieve the
file; @command{cpio}s
+../tar_texi/tar.texi(,8949) way puts one copy for every link, but you can
retrieve it using any
+../tar_texi/tar.texi(,8950) of the names.
+../tar_texi/tar.texi(,8951)
+../tar_texi/tar.texi(,8952) @quotation
+../tar_texi/tar.texi(,8953) What type of check sum (if any) is used, and how
is this calculated.
+../tar_texi/tar.texi(,8954) @end quotation
+../tar_texi/tar.texi(,8955)
+../tar_texi/tar.texi(,8956) See the attached manual pages for @command{tar}
and @command{cpio} format.
+../tar_texi/tar.texi(,8957) @command{tar} uses a checksum which is the sum of
all the bytes in the
+../tar_texi/tar.texi(,8958) @command{tar} header for a file; @command{cpio}
uses no checksum.
+../tar_texi/tar.texi(,8959)
+../tar_texi/tar.texi(,8960) @quotation
+../tar_texi/tar.texi(,8961) If anyone knows why @command{cpio} was made when
@command{tar} was present
+../tar_texi/tar.texi(,8962) at the unix scene,
+../tar_texi/tar.texi(,8963) @end quotation
+../tar_texi/tar.texi(,8964)
+../tar_texi/tar.texi(,8965) It wasn't. @command{cpio} first showed up in
PWB/UNIX 1.0; no
+../tar_texi/tar.texi(,8966) generally-available version of UNIX had
@command{tar} at the time. I don't
+../tar_texi/tar.texi(,8967) know whether any version that was generally
available @emph{within AT&T}
+../tar_texi/tar.texi(,8968) had @command{tar}, or, if so, whether the people
within AT&T who did
+../tar_texi/tar.texi(,8969) @command{cpio} knew about it.
+../tar_texi/tar.texi(,8970)
+../tar_texi/tar.texi(,8971) On restore, if there is a corruption on a tape
@command{tar} will stop at
+../tar_texi/tar.texi(,8972) that point, while @command{cpio} will skip over it
and try to restore the
+../tar_texi/tar.texi(,8973) rest of the files.
+../tar_texi/tar.texi(,8974)
+../tar_texi/tar.texi(,8975) The main difference is just in the command syntax
and header format.
+../tar_texi/tar.texi(,8976)
+../tar_texi/tar.texi(,8977) @command{tar} is a little more tape-oriented in
that everything is blocked
+../tar_texi/tar.texi(,8978) to start on a record boundary.
+../tar_texi/tar.texi(,8979)
+../tar_texi/tar.texi(,8980) @quotation
+../tar_texi/tar.texi(,8981) Is there any differences between the ability to
recover crashed
+../tar_texi/tar.texi(,8982) archives between the two of them. (Is there any
chance of recovering
+../tar_texi/tar.texi(,8983) crashed archives at all.)
+../tar_texi/tar.texi(,8984) @end quotation
+../tar_texi/tar.texi(,8985)
+../tar_texi/tar.texi(,8986) Theoretically it should be easier under
@command{tar} since the blocking
+../tar_texi/tar.texi(,8987) lets you find a header with some variation of
@samp{dd address@hidden
+../tar_texi/tar.texi(,8988) However, modern @command{cpio}'s and variations
have an option to just
+../tar_texi/tar.texi(,8989) search for the next file header after an error
with a reasonable chance
+../tar_texi/tar.texi(,8990) of resyncing. However, lots of tape driver
software won't allow you to
+../tar_texi/tar.texi(,8991) continue past a media error which should be the
only reason for getting
+../tar_texi/tar.texi(,8992) out of sync unless a file changed sizes while you
were writing the
+../tar_texi/tar.texi(,8993) archive.
+../tar_texi/tar.texi(,8994)
+../tar_texi/tar.texi(,8995) @quotation
+../tar_texi/tar.texi(,8996) If anyone knows why @command{cpio} was made when
@command{tar} was present
+../tar_texi/tar.texi(,8997) at the unix scene, please tell me about this too.
+../tar_texi/tar.texi(,8998) @end quotation
+../tar_texi/tar.texi(,8999)
+../tar_texi/tar.texi(,9000) Probably because it is more media efficient (by
not blocking everything
+../tar_texi/tar.texi(,9001) and using only the space needed for the headers
where @command{tar}
+../tar_texi/tar.texi(,9002) always uses 512 bytes per file header) and it
knows how to archive
+../tar_texi/tar.texi(,9003) special files.
+../tar_texi/tar.texi(,9004)
+../tar_texi/tar.texi(,9005) You might want to look at the freely available
alternatives. The
+../tar_texi/tar.texi(GNUTAR,9006) major ones are @command{afio}, @acronym{GNU}
@command{tar}, and
+../tar_texi/tar.texi(,9007) @command{pax}, each of which have their own
extensions with some
+../tar_texi/tar.texi(,9008) backwards compatibility.
+../tar_texi/tar.texi(,9009)
+../tar_texi/tar.texi(,9010) Sparse files were @command{tar}red as sparse files
(which you can
+../tar_texi/tar.texi(,9011) easily test, because the resulting archive gets
smaller, and
+../tar_texi/tar.texi(,9012) @acronym{GNU} @command{cpio} can no longer read
it).
+../tar_texi/tar.texi(,9013)
+../tar_texi/tar.texi(,9014) @node Media
+../tar_texi/tar.texi(,9015) @chapter Tapes and Other Archive Media
+../tar_texi/tar.texi(UNREVISED,9016) @quotation
+../tar_texi/tar.texi(UNREVISED,9016) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9016) @end quotation
+../tar_texi/tar.texi(UNREVISED,9016)
+../tar_texi/tar.texi(,9017)
+../tar_texi/tar.texi(,9018) A few special cases about tape handling warrant
more detailed
+../tar_texi/tar.texi(,9019) description. These special cases are discussed
below.
+../tar_texi/tar.texi(,9020)
+../tar_texi/tar.texi(,9021) Many complexities surround the use of
@command{tar} on tape drives. Since
+../tar_texi/tar.texi(,9022) the creation and manipulation of archives located
on magnetic tape was
+../tar_texi/tar.texi(,9023) the original purpose of @command{tar}, it contains
many features making
+../tar_texi/tar.texi(,9024) such manipulation easier.
+../tar_texi/tar.texi(,9025)
+../tar_texi/tar.texi(,9026) Archives are usually written on dismountable
media---tape cartridges,
+../tar_texi/tar.texi(,9027) mag tapes, or floppy disks.
+../tar_texi/tar.texi(,9028)
+../tar_texi/tar.texi(,9029) The amount of data a tape or disk holds depends
not only on its size,
+../tar_texi/tar.texi(,9030) but also on how it is formatted. A 2400 foot long
reel of mag tape
+../tar_texi/tar.texi(,9031) holds 40 megabytes of data when formatted at 1600
bits per inch. The
+../tar_texi/tar.texi(,9032) physically smaller EXABYTE tape cartridge holds
2.3 gigabytes.
+../tar_texi/tar.texi(,9033)
+../tar_texi/tar.texi(,9034) Magnetic media are re-usable---once the archive on
a tape is no longer
+../tar_texi/tar.texi(,9035) needed, the archive can be erased and the tape or
disk used over.
+../tar_texi/tar.texi(,9036) Media quality does deteriorate with use, however.
Most tapes or disks
+../tar_texi/tar.texi(,9037) should be discarded when they begin to produce
data errors. EXABYTE
+../tar_texi/tar.texi(,9038) tape cartridges should be discarded when they
generate an @dfn{error
+../tar_texi/tar.texi(,9039) count} (number of non-usable bits) of more than
10k.
+../tar_texi/tar.texi(,9040)
+../tar_texi/tar.texi(,9041) Magnetic media are written and erased using
magnetic fields, and
+../tar_texi/tar.texi(,9042) should be protected from such fields to avoid
damage to stored data.
+../tar_texi/tar.texi(,9043) Sticking a floppy disk to a filing cabinet using a
magnet is probably
+../tar_texi/tar.texi(,9044) not a good idea.
+../tar_texi/tar.texi(,9045)
+../tar_texi/tar.texi(,9046) @menu
+../tar_texi/tar.texi(,9047) * Device:: Device selection
and switching
+../tar_texi/tar.texi(,9048) * Remote Tape Server::
+../tar_texi/tar.texi(,9049) * Common Problems and Solutions::
+../tar_texi/tar.texi(,9050) * Blocking:: Blocking
+../tar_texi/tar.texi(,9051) * Many:: Many archives on
one tape
+../tar_texi/tar.texi(,9052) * Using Multiple Tapes:: Using Multiple
Tapes
+../tar_texi/tar.texi(,9053) * label:: Including a Label
in the Archive
+../tar_texi/tar.texi(,9054) * verify::
+../tar_texi/tar.texi(,9055) * Write Protection::
+../tar_texi/tar.texi(,9056) @end menu
+../tar_texi/tar.texi(,9057)
+../tar_texi/tar.texi(,9058) @node Device
+../tar_texi/tar.texi(,9059) @section Device Selection and Switching
+../tar_texi/tar.texi(UNREVISED,9060) @quotation
+../tar_texi/tar.texi(UNREVISED,9060) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9060) @end quotation
+../tar_texi/tar.texi(UNREVISED,9060)
+../tar_texi/tar.texi(,9061)
+../tar_texi/tar.texi(,9062) @table @option
+../tar_texi/tar.texi(,9063) @item -f address@hidden:address@hidden
+../tar_texi/tar.texi(,9064) @itemx address@hidden:address@hidden
+../tar_texi/tar.texi(,9065) Use archive file or device @var{file} on
@var{hostname}.
+../tar_texi/tar.texi(,9066) @end table
+../tar_texi/tar.texi(,9067)
+../tar_texi/tar.texi(,9068) This option is used to specify the file name of
the archive @command{tar}
+../tar_texi/tar.texi(,9069) works on.
+../tar_texi/tar.texi(,9070)
+../tar_texi/tar.texi(,9071) If the file name is @samp{-}, @command{tar} reads
the archive from standard
+../tar_texi/tar.texi(,9072) input (when listing or extracting), or writes it
to standard output
+../tar_texi/tar.texi(,9073) (when creating). If the @samp{-} file name is
given when updating an
+../tar_texi/tar.texi(,9074) archive, @command{tar} will read the original
archive from its standard
+../tar_texi/tar.texi(,9075) input, and will write the entire new archive to
its standard output.
+../tar_texi/tar.texi(,9076)
+../tar_texi/tar.texi(,9077) If the file name contains a @samp{:}, it is
interpreted as
+../tar_texi/tar.texi(,9078) @samp{hostname:file name}. If the @var{hostname}
contains an @dfn{at}
+../tar_texi/tar.texi(,9079) sign (@samp{@@}), it is treated as
@samp{user@@hostname:file name}. In
+../tar_texi/tar.texi(,9080) either case, @command{tar} will invoke the command
@command{rsh} (or
+../tar_texi/tar.texi(,9081) @command{remsh}) to start up an
@command{/usr/libexec/rmt} on the remote
+../tar_texi/tar.texi(,9082) machine. If you give an alternate login name, it
will be given to the
+../tar_texi/tar.texi(,9083) @command{rsh}.
+../tar_texi/tar.texi(,9084) Naturally, the remote machine must have an
executable
+../tar_texi/tar.texi(,9085) @command{/usr/libexec/rmt}. This program is free
software from the
+../tar_texi/tar.texi(,9086) University of California, and a copy of the source
code can be found
+../tar_texi/tar.texi(,9087) with the sources for @command{tar}; it's compiled
and installed by default.
+../tar_texi/tar.texi(,9088) The exact path to this utility is determined when
configuring the package.
+../tar_texi/tar.texi(,9089) It is @address@hidden/libexec/rmt}, where
@var{prefix} stands for
+../tar_texi/tar.texi(,9090) your installation prefix. This location may also
be overridden at
+../tar_texi/tar.texi(,9091) runtime by using @address@hidden option
(@xref{Option Summary,
+../tar_texi/tar.texi(,9092) ---rmt-command}, for detailed description of this
option. @xref{Remote
+../tar_texi/tar.texi(,9093) Tape Server}, for the description of @command{rmt}
command).
+../tar_texi/tar.texi(,9094)
+../tar_texi/tar.texi(,9095) If this option is not given, but the environment
variable @env{TAPE}
+../tar_texi/tar.texi(,9096) is set, its value is used; otherwise, old versions
of @command{tar}
+../tar_texi/tar.texi(,9097) used a default archive name (which was picked when
@command{tar} was
+../tar_texi/tar.texi(,9098) compiled). The default is normally set up to be
the @dfn{first} tape
+../tar_texi/tar.texi(,9099) drive or other transportable I/O medium on the
system.
+../tar_texi/tar.texi(,9100)
+../tar_texi/tar.texi(GNUTAR,9101) Starting with version 1.11.5, @acronym{GNU}
@command{tar} uses
+../tar_texi/tar.texi(,9102) standard input and standard output as the default
device, and I will
+../tar_texi/tar.texi(,9103) not try anymore supporting automatic device
detection at installation
+../tar_texi/tar.texi(,9104) time. This was failing really in too many cases,
it was hopeless.
+../tar_texi/tar.texi(,9105) This is now completely left to the installer to
override standard
+../tar_texi/tar.texi(,9106) input and standard output for default device, if
this seems
+../tar_texi/tar.texi(,9107) preferable. Further, I think @emph{most} actual
usages of
+../tar_texi/tar.texi(,9108) @command{tar} are done with pipes or disks, not
really tapes,
+../tar_texi/tar.texi(,9109) cartridges or diskettes.
+../tar_texi/tar.texi(,9110)
+../tar_texi/tar.texi(,9111) Some users think that using standard input and
output is running
+../tar_texi/tar.texi(,9112) after trouble. This could lead to a nasty
surprise on your screen if
+../tar_texi/tar.texi(,9113) you forget to specify an output file
name---especially if you are going
+../tar_texi/tar.texi(,9114) through a network or terminal server capable of
buffering large amounts
+../tar_texi/tar.texi(,9115) of output. We had so many bug reports in that
area of configuring
+../tar_texi/tar.texi(,9116) default tapes automatically, and so many
contradicting requests, that
+../tar_texi/tar.texi(,9117) we finally consider the problem to be portably
intractable. We could
+../tar_texi/tar.texi(,9118) of course use something like @samp{/dev/tape} as a
default, but this
+../tar_texi/tar.texi(,9119) is @emph{also} running after various kind of
trouble, going from hung
+../tar_texi/tar.texi(,9120) processes to accidental destruction of real tapes.
After having seen
+../tar_texi/tar.texi(,9121) all this mess, using standard input and output as
a default really
+../tar_texi/tar.texi(,9122) sounds like the only clean choice left, and a very
useful one too.
+../tar_texi/tar.texi(,9123)
+../tar_texi/tar.texi(GNUTAR,9124) @acronym{GNU} @command{tar} reads and writes
archive in records, I
+../tar_texi/tar.texi(,9125) suspect this is the main reason why block devices
are preferred over
+../tar_texi/tar.texi(,9126) character devices. Most probably, block devices
are more efficient
+../tar_texi/tar.texi(,9127) too. The installer could also check for
@samp{DEFTAPE} in
+../tar_texi/tar.texi(,9128) @file{<sys/mtio.h>}.
+../tar_texi/tar.texi(,9129)
+../tar_texi/tar.texi(,9130) @table @option
+../tar_texi/tar.texi(xopindex,9131) @opindex address@hidden, short description}
+../tar_texi/tar.texi(,9132) @item --force-local
+../tar_texi/tar.texi(,9133) Archive file is local even if it contains a colon.
+../tar_texi/tar.texi(,9134)
+../tar_texi/tar.texi(,9135) @opindex rsh-command
+../tar_texi/tar.texi(,9136) @item address@hidden
+../tar_texi/tar.texi(,9137) Use remote @var{command} instead of @command{rsh}.
This option exists
+../tar_texi/tar.texi(,9138) so that people who use something other than the
standard @command{rsh}
+../tar_texi/tar.texi(,9139) (e.g., a Kerberized @command{rsh}) can access a
remote device.
+../tar_texi/tar.texi(,9140)
+../tar_texi/tar.texi(,9141) When this command is not used, the shell command
found when
+../tar_texi/tar.texi(,9142) the @command{tar} program was installed is used
instead. This is
+../tar_texi/tar.texi(,9143) the first found of @file{/usr/ucb/rsh},
@file{/usr/bin/remsh},
+../tar_texi/tar.texi(,9144) @file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or
@file{/usr/bin/nsh}.
+../tar_texi/tar.texi(,9145) The installer may have overridden this by defining
the environment
+../tar_texi/tar.texi(,9146) variable @env{RSH} @emph{at installation time}.
+../tar_texi/tar.texi(,9147)
+../tar_texi/tar.texi(,9148) @item -[0-7][lmh]
+../tar_texi/tar.texi(,9149) Specify drive and density.
+../tar_texi/tar.texi(,9150)
+../tar_texi/tar.texi(xopindex,9151) @opindex address@hidden, short description}
+../tar_texi/tar.texi(,9152) @item -M
+../tar_texi/tar.texi(,9153) @itemx --multi-volume
+../tar_texi/tar.texi(,9154) Create/list/extract multi-volume archive.
+../tar_texi/tar.texi(,9155)
+../tar_texi/tar.texi(,9156) This option causes @command{tar} to write a
@dfn{multi-volume} archive---one
+../tar_texi/tar.texi(,9157) that may be larger than will fit on the medium
used to hold it.
+../tar_texi/tar.texi(,9158) @xref{Multi-Volume Archives}.
+../tar_texi/tar.texi(,9159)
+../tar_texi/tar.texi(xopindex,9160) @opindex address@hidden, short description}
+../tar_texi/tar.texi(,9161) @item -L @var{num}
+../tar_texi/tar.texi(,9162) @itemx address@hidden
+../tar_texi/tar.texi(,9163) Change tape after writing @var{num} x 1024 bytes.
+../tar_texi/tar.texi(,9164)
+../tar_texi/tar.texi(,9165) This option might be useful when your tape drivers
do not properly
+../tar_texi/tar.texi(,9166) detect end of physical tapes. By being slightly
conservative on the
+../tar_texi/tar.texi(,9167) maximum tape length, you might avoid the problem
entirely.
+../tar_texi/tar.texi(,9168)
+../tar_texi/tar.texi(xopindex,9169) @opindex address@hidden, short description}
+../tar_texi/tar.texi(xopindex,9170) @opindex address@hidden, short description}
+../tar_texi/tar.texi(,9171) @item -F @var{file}
+../tar_texi/tar.texi(,9172) @itemx address@hidden
+../tar_texi/tar.texi(,9173) @itemx address@hidden
+../tar_texi/tar.texi(,9174) Execute @file{file} at end of each tape. This
implies
+../tar_texi/tar.texi(,9175) @option{--multi-volume} (@option{-M}).
@xref{info-script}, for a detailed
+../tar_texi/tar.texi(,9176) description of this option.
+../tar_texi/tar.texi(,9177) @end table
+../tar_texi/tar.texi(,9178)
+../tar_texi/tar.texi(,9179) @node Remote Tape Server
+../tar_texi/tar.texi(,9180) @section The Remote Tape Server
+../tar_texi/tar.texi(,9181)
+../tar_texi/tar.texi(,9182) @cindex remote tape drive
+../tar_texi/tar.texi(,9183) @pindex rmt
+../tar_texi/tar.texi(,9184) In order to access the tape drive on a remote
machine, @command{tar}
+../tar_texi/tar.texi(,9185) uses the remote tape server written at the
University of California at
+../tar_texi/tar.texi(,9186) Berkeley. The remote tape server must be
installed as
+../tar_texi/tar.texi(,9187) @address@hidden/libexec/rmt} on any machine whose
tape drive you
+../tar_texi/tar.texi(,9188) want to use. @command{tar} calls @command{rmt} by
running an
+../tar_texi/tar.texi(,9189) @command{rsh} or @command{remsh} to the remote
machine, optionally
+../tar_texi/tar.texi(,9190) using a different login name if one is supplied.
+../tar_texi/tar.texi(,9191)
+../tar_texi/tar.texi(,9192) A copy of the source for the remote tape server is
provided. It is
+../tar_texi/tar.texi(,9193) Copyright @copyright{} 1983 by the Regents of the
University of
+../tar_texi/tar.texi(,9194) California, but can be freely distributed. It is
compiled and
+../tar_texi/tar.texi(,9195) installed by default.
+../tar_texi/tar.texi(,9196)
+../tar_texi/tar.texi(,9197) @cindex absolute file names
+../tar_texi/tar.texi(,9198) Unless you use the @option{--absolute-names}
(@option{-P}) option,
+../tar_texi/tar.texi(GNUTAR,9199) @acronym{GNU} @command{tar} will not allow
you to create an archive that contains
+../tar_texi/tar.texi(,9200) absolute file names (a file name beginning with
@samp{/}.) If you try,
+../tar_texi/tar.texi(,9201) @command{tar} will automatically remove the
leading @samp{/} from the
+../tar_texi/tar.texi(,9202) file names it stores in the archive. It will also
type a warning
+../tar_texi/tar.texi(,9203) message telling you what it is doing.
+../tar_texi/tar.texi(,9204)
+../tar_texi/tar.texi(,9205) When reading an archive that was created with a
different
+../tar_texi/tar.texi(GNUTAR,9206) @command{tar} program, @acronym{GNU}
@command{tar} automatically
+../tar_texi/tar.texi(,9207) extracts entries in the archive which have
absolute file names as if
+../tar_texi/tar.texi(,9208) the file names were not absolute. This is an
important feature. A
+../tar_texi/tar.texi(,9209) visitor here once gave a @command{tar} tape to an
operator to restore;
+../tar_texi/tar.texi(GNUTAR,9210) the operator used Sun @command{tar} instead
of @acronym{GNU} @command{tar},
+../tar_texi/tar.texi(,9211) and the result was that it replaced large portions
of
+../tar_texi/tar.texi(,9212) our @file{/bin} and friends with versions from the
tape; needless to
+../tar_texi/tar.texi(,9213) say, we were unhappy about having to recover the
file system from
+../tar_texi/tar.texi(,9214) backup tapes.
+../tar_texi/tar.texi(,9215)
+../tar_texi/tar.texi(,9216) For example, if the archive contained a file
@file{/usr/bin/computoy},
+../tar_texi/tar.texi(GNUTAR,9217) @acronym{GNU} @command{tar} would extract
the file to @file{usr/bin/computoy},
+../tar_texi/tar.texi(,9218) relative to the current directory. If you want to
extract the files in
+../tar_texi/tar.texi(,9219) an archive to the same absolute names that they
had when the archive
+../tar_texi/tar.texi(,9220) was created, you should do a @samp{cd /} before
extracting the files
+../tar_texi/tar.texi(,9221) from the archive, or you should either use the
@option{--absolute-names}
+../tar_texi/tar.texi(,9222) option, or use the command @samp{tar -C / @dots{}}.
+../tar_texi/tar.texi(,9223)
+../tar_texi/tar.texi(,9224) @cindex Ultrix 3.1 and write failure
+../tar_texi/tar.texi(,9225) Some versions of Unix (Ultrix 3.1 is known to have
this problem),
+../tar_texi/tar.texi(,9226) can claim that a short write near the end of a
tape succeeded,
+../tar_texi/tar.texi(,9227) when it actually failed. This will result in the
-M option not
+../tar_texi/tar.texi(,9228) working correctly. The best workaround at the
moment is to use a
+../tar_texi/tar.texi(,9229) significantly larger blocking factor than the
default 20.
+../tar_texi/tar.texi(,9230)
+../tar_texi/tar.texi(,9231) In order to update an archive, @command{tar} must
be able to backspace the
+../tar_texi/tar.texi(,9232) archive in order to reread or rewrite a record
that was just read (or
+../tar_texi/tar.texi(,9233) written). This is currently possible only on two
kinds of files: normal
+../tar_texi/tar.texi(,9234) disk files (or any other file that can be
backspaced with @samp{lseek}),
+../tar_texi/tar.texi(,9235) and industry-standard 9-track magnetic tape (or
any other kind of tape
+../tar_texi/tar.texi(,9236) that can be backspaced with the @code{MTIOCTOP}
@code{ioctl}.
+../tar_texi/tar.texi(,9237)
+../tar_texi/tar.texi(,9238) This means that the @option{--append},
@option{--concatenate}, and
+../tar_texi/tar.texi(,9239) @option{--delete} commands will not work on any
other kind of file.
+../tar_texi/tar.texi(,9240) Some media simply cannot be backspaced, which
means these commands and
+../tar_texi/tar.texi(,9241) options will never be able to work on them. These
non-backspacing
+../tar_texi/tar.texi(,9242) media include pipes and cartridge tape drives.
+../tar_texi/tar.texi(,9243)
+../tar_texi/tar.texi(,9244) Some other media can be backspaced, and
@command{tar} will work on them
+../tar_texi/tar.texi(,9245) once @command{tar} is modified to do so.
+../tar_texi/tar.texi(,9246)
+../tar_texi/tar.texi(,9247) Archives created with the @option{--multi-volume},
@option{--label}, and
+../tar_texi/tar.texi(,9248) @option{--incremental} (@option{-G}) options may
not be readable by other version
+../tar_texi/tar.texi(,9249) of @command{tar}. In particular, restoring a file
that was split over
+../tar_texi/tar.texi(,9250) a volume boundary will require some careful work
with @command{dd}, if
+../tar_texi/tar.texi(,9251) it can be done at all. Other versions of
@command{tar} may also create
+../tar_texi/tar.texi(,9252) an empty file whose name is that of the volume
header. Some versions
+../tar_texi/tar.texi(,9253) of @command{tar} may create normal files instead
of directories archived
+../tar_texi/tar.texi(,9254) with the @option{--incremental} (@option{-G})
option.
+../tar_texi/tar.texi(,9255)
+../tar_texi/tar.texi(,9256) @node Common Problems and Solutions
+../tar_texi/tar.texi(,9257) @section Some Common Problems and their Solutions
+../tar_texi/tar.texi(,9258)
+../tar_texi/tar.texi(,9260)
+../tar_texi/tar.texi(,9261) @format
+../tar_texi/tar.texi(,9262) errors from system:
+../tar_texi/tar.texi(,9263) permission denied
+../tar_texi/tar.texi(,9264) no such file or directory
+../tar_texi/tar.texi(,9265) not owner
+../tar_texi/tar.texi(,9266)
+../tar_texi/tar.texi(,9267) errors from @command{tar}:
+../tar_texi/tar.texi(,9268) directory checksum error
+../tar_texi/tar.texi(,9269) header format error
+../tar_texi/tar.texi(,9270)
+../tar_texi/tar.texi(,9271) errors from media/system:
+../tar_texi/tar.texi(,9272) i/o error
+../tar_texi/tar.texi(,9273) device busy
+../tar_texi/tar.texi(,9274) @end format
+../tar_texi/tar.texi(,9275)
+../tar_texi/tar.texi(,9277)
+../tar_texi/tar.texi(,9278) @node Blocking
+../tar_texi/tar.texi(,9279) @section Blocking
+../tar_texi/tar.texi(UNREVISED,9280) @quotation
+../tar_texi/tar.texi(UNREVISED,9280) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9280) @end quotation
+../tar_texi/tar.texi(UNREVISED,9280)
+../tar_texi/tar.texi(,9281)
+../tar_texi/tar.texi(,9282) @dfn{Block} and @dfn{record} terminology is rather
confused, and it
+../tar_texi/tar.texi(,9283) is also confusing to the expert reader. On the
other hand, readers
+../tar_texi/tar.texi(,9284) who are new to the field have a fresh mind, and
they may safely skip
+../tar_texi/tar.texi(,9285) the next two paragraphs, as the remainder of this
manual uses those
+../tar_texi/tar.texi(,9286) two terms in a quite consistent way.
+../tar_texi/tar.texi(,9287)
+../tar_texi/tar.texi(,9288) John Gilmore, the writer of the public domain
@command{tar} from which
+../tar_texi/tar.texi(GNUTAR,9289) @acronym{GNU} @command{tar} was originally
derived, wrote (June 1995):
+../tar_texi/tar.texi(,9290)
+../tar_texi/tar.texi(,9291) @quotation
+../tar_texi/tar.texi(,9292) The nomenclature of tape drives comes from IBM,
where I believe
+../tar_texi/tar.texi(,9293) they were invented for the IBM 650 or so. On IBM
mainframes, what
+../tar_texi/tar.texi(,9294) is recorded on tape are tape blocks. The logical
organization of
+../tar_texi/tar.texi(,9295) data is into records. There are various ways of
putting records into
+../tar_texi/tar.texi(,9296) blocks, including @code{F} (fixed sized records),
@code{V} (variable
+../tar_texi/tar.texi(,9297) sized records), @code{FB} (fixed blocked: fixed
size records, @var{n}
+../tar_texi/tar.texi(,9298) to a block), @code{VB} (variable size records,
@var{n} to a block),
+../tar_texi/tar.texi(,9299) @code{VSB} (variable spanned blocked: variable
sized records that can
+../tar_texi/tar.texi(,9300) occupy more than one block), etc. The @code{JCL}
@samp{DD RECFORM=}
+../tar_texi/tar.texi(,9301) parameter specified this to the operating system.
+../tar_texi/tar.texi(,9302)
+../tar_texi/tar.texi(,9303) The Unix man page on @command{tar} was totally
confused about this.
+../tar_texi/tar.texi(,9304) When I wrote @code{PD TAR}, I used the
historically correct terminology
+../tar_texi/tar.texi(,9305) (@command{tar} writes data records, which are
grouped into blocks).
+../tar_texi/tar.texi(,9306) It appears that the bogus terminology made it into
@acronym{POSIX} (no surprise
+../tar_texi/tar.texi(,9307) here), and now address@hidden has migrated that
terminology back
+../tar_texi/tar.texi(,9308) into the source code too.
+../tar_texi/tar.texi(,9309) @end quotation
+../tar_texi/tar.texi(,9310)
+../tar_texi/tar.texi(,9311) The term @dfn{physical block} means the basic
transfer chunk from or
+../tar_texi/tar.texi(,9312) to a device, after which reading or writing may
stop without anything
+../tar_texi/tar.texi(,9313) being lost. In this manual, the term @dfn{block}
usually refers to
+../tar_texi/tar.texi(,9314) a disk physical block, @emph{assuming} that each
disk block is 512
+../tar_texi/tar.texi(,9315) bytes in length. It is true that some disk
devices have different
+../tar_texi/tar.texi(,9316) physical blocks, but @command{tar} ignore these
differences in its own
+../tar_texi/tar.texi(,9317) format, which is meant to be portable, so a
@command{tar} block is always
+../tar_texi/tar.texi(,9318) 512 bytes in length, and @dfn{block} always mean a
@command{tar} block.
+../tar_texi/tar.texi(,9319) The term @dfn{logical block} often represents the
basic chunk of
+../tar_texi/tar.texi(,9320) allocation of many disk blocks as a single entity,
which the operating
+../tar_texi/tar.texi(,9321) system treats somewhat atomically; this concept is
only barely used
+../tar_texi/tar.texi(GNUTAR,9322) in @acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,9323)
+../tar_texi/tar.texi(,9324) The term @dfn{physical record} is another way to
speak of a physical
+../tar_texi/tar.texi(,9325) block, those two terms are somewhat
interchangeable. In this manual,
+../tar_texi/tar.texi(,9326) the term @dfn{record} usually refers to a tape
physical block,
+../tar_texi/tar.texi(,9327) @emph{assuming} that the @command{tar} archive is
kept on magnetic tape.
+../tar_texi/tar.texi(,9328) It is true that archives may be put on disk or
used with pipes,
+../tar_texi/tar.texi(,9329) but nevertheless, @command{tar} tries to read and
write the archive one
+../tar_texi/tar.texi(,9330) @dfn{record} at a time, whatever the medium in
use. One record is made
+../tar_texi/tar.texi(,9331) up of an integral number of blocks, and this
operation of putting many
+../tar_texi/tar.texi(,9332) disk blocks into a single tape block is called
@dfn{reblocking}, or
+../tar_texi/tar.texi(,9333) more simply, @dfn{blocking}. The term
@dfn{logical record} refers to
+../tar_texi/tar.texi(,9334) the logical organization of many characters into
something meaningful
+../tar_texi/tar.texi(,9335) to the application. The term @dfn{unit record}
describes a small set
+../tar_texi/tar.texi(,9336) of characters which are transmitted whole to or by
the application,
+../tar_texi/tar.texi(,9337) and often refers to a line of text. Those two
last terms are unrelated
+../tar_texi/tar.texi(GNUTAR,9338) to what we call a @dfn{record} in
@acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,9339)
+../tar_texi/tar.texi(,9340) When writing to tapes, @command{tar} writes the
contents of the archive
+../tar_texi/tar.texi(,9341) in chunks known as @dfn{records}. To change the
default blocking
+../tar_texi/tar.texi(,9342) factor, use the @address@hidden (@option{-b
+../tar_texi/tar.texi(,9343) @var{512-size}}) option. Each record will then be
composed of
+../tar_texi/tar.texi(,9344) @var{512-size} blocks. (Each @command{tar} block
is 512 bytes.
+../tar_texi/tar.texi(,9345) @xref{Standard}.) Each file written to the
archive uses at least one
+../tar_texi/tar.texi(,9346) full record. As a result, using a larger record
size can result in
+../tar_texi/tar.texi(,9347) more wasted space for small files. On the other
hand, a larger record
+../tar_texi/tar.texi(,9348) size can often be read and written much more
efficiently.
+../tar_texi/tar.texi(,9349)
+../tar_texi/tar.texi(,9350) Further complicating the problem is that some tape
drives ignore the
+../tar_texi/tar.texi(,9351) blocking entirely. For these, a larger record
size can still improve
+../tar_texi/tar.texi(,9352) performance (because the software layers above the
tape drive still
+../tar_texi/tar.texi(,9353) honor the blocking), but not as dramatically as on
tape drives that
+../tar_texi/tar.texi(,9354) honor blocking.
+../tar_texi/tar.texi(,9355)
+../tar_texi/tar.texi(,9356) When reading an archive, @command{tar} can usually
figure out the
+../tar_texi/tar.texi(,9357) record size on itself. When this is the case, and
a non-standard
+../tar_texi/tar.texi(,9358) record size was used when the archive was created,
@command{tar} will
+../tar_texi/tar.texi(,9359) print a message about a non-standard blocking
factor, and then operate
+../tar_texi/tar.texi(,9360) normally. On some tape devices, however,
@command{tar} cannot figure
+../tar_texi/tar.texi(,9361) out the record size itself. On most of those, you
can specify a
+../tar_texi/tar.texi(,9362) blocking factor (with @option{--blocking-factor})
larger than the
+../tar_texi/tar.texi(,9363) actual blocking factor, and then use the
@option{--read-full-records}
+../tar_texi/tar.texi(,9364) (@option{-B}) option. (If you specify a blocking
factor with
+../tar_texi/tar.texi(,9365) @option{--blocking-factor} and don't use the
+../tar_texi/tar.texi(,9366) @option{--read-full-records} option, then
@command{tar} will not
+../tar_texi/tar.texi(,9367) attempt to figure out the recording size itself.)
On some devices,
+../tar_texi/tar.texi(,9368) you must always specify the record size exactly
with
+../tar_texi/tar.texi(,9369) @option{--blocking-factor} when reading, because
@command{tar} cannot
+../tar_texi/tar.texi(,9370) figure it out. In any case, use @option{--list}
(@option{-t}) before
+../tar_texi/tar.texi(,9371) doing any extractions to see whether @command{tar}
is reading the archive
+../tar_texi/tar.texi(,9372) correctly.
+../tar_texi/tar.texi(,9373)
+../tar_texi/tar.texi(,9374) @command{tar} blocks are all fixed size (512
bytes), and its scheme for
+../tar_texi/tar.texi(,9375) putting them into records is to put a whole number
of them (one or
+../tar_texi/tar.texi(,9376) more) into each record. @command{tar} records are
all the same size;
+../tar_texi/tar.texi(,9377) at the end of the file there's a block containing
all zeros, which
+../tar_texi/tar.texi(,9378) is how you tell that the remainder of the last
record(s) are garbage.
+../tar_texi/tar.texi(,9379)
+../tar_texi/tar.texi(,9380) In a standard @command{tar} file (no options), the
block size is 512
+../tar_texi/tar.texi(,9381) and the record size is 10240, for a blocking
factor of 20. What the
+../tar_texi/tar.texi(,9382) @option{--blocking-factor} option does is sets the
blocking factor,
+../tar_texi/tar.texi(,9383) changing the record size while leaving the block
size at 512 bytes.
+../tar_texi/tar.texi(,9384) 20 was fine for ancient 800 or 1600 bpi
reel-to-reel tape drives;
+../tar_texi/tar.texi(,9385) most tape drives these days prefer much bigger
records in order to
+../tar_texi/tar.texi(,9386) stream and not waste tape. When writing tapes for
myself, some tend
+../tar_texi/tar.texi(,9387) to use a factor of the order of 2048, say, giving
a record size of
+../tar_texi/tar.texi(,9388) around one megabyte.
+../tar_texi/tar.texi(,9389)
+../tar_texi/tar.texi(,9390) If you use a blocking factor larger than 20, older
@command{tar}
+../tar_texi/tar.texi(,9391) programs might not be able to read the archive, so
we recommend this
+../tar_texi/tar.texi(GNUTAR,9392) as a limit to use in practice.
@acronym{GNU} @command{tar}, however,
+../tar_texi/tar.texi(,9393) will support arbitrarily large record sizes,
limited only by the
+../tar_texi/tar.texi(,9394) amount of virtual memory or the physical
characteristics of the tape
+../tar_texi/tar.texi(,9395) device.
+../tar_texi/tar.texi(,9396)
+../tar_texi/tar.texi(,9397) @menu
+../tar_texi/tar.texi(,9398) * Format Variations:: Format Variations
+../tar_texi/tar.texi(,9399) * Blocking Factor:: The Blocking
Factor of an Archive
+../tar_texi/tar.texi(,9400) @end menu
+../tar_texi/tar.texi(,9401)
+../tar_texi/tar.texi(,9402) @node Format Variations
+../tar_texi/tar.texi(,9403) @subsection Format Variations
+../tar_texi/tar.texi(,9404) @cindex Format Parameters
+../tar_texi/tar.texi(,9405) @cindex Format Options
+../tar_texi/tar.texi(,9406) @cindex Options, archive format specifying
+../tar_texi/tar.texi(,9407) @cindex Options, format specifying
+../tar_texi/tar.texi(UNREVISED,9408) @quotation
+../tar_texi/tar.texi(UNREVISED,9408) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9408) @end quotation
+../tar_texi/tar.texi(UNREVISED,9408)
+../tar_texi/tar.texi(,9409)
+../tar_texi/tar.texi(,9410) Format parameters specify how an archive is
written on the archive
+../tar_texi/tar.texi(,9411) media. The best choice of format parameters will
vary depending on
+../tar_texi/tar.texi(,9412) the type and number of files being archived, and
on the media used to
+../tar_texi/tar.texi(,9413) store the archive.
+../tar_texi/tar.texi(,9414)
+../tar_texi/tar.texi(,9415) To specify format parameters when accessing or
creating an archive,
+../tar_texi/tar.texi(,9416) you can use the options described in the following
sections.
+../tar_texi/tar.texi(,9417) If you do not specify any format parameters,
@command{tar} uses
+../tar_texi/tar.texi(,9418) default parameters. You cannot modify a
compressed archive.
+../tar_texi/tar.texi(,9419) If you create an archive with the
@option{--blocking-factor} option
+../tar_texi/tar.texi(,9420) specified (@pxref{Blocking Factor}), you must
specify that
+../tar_texi/tar.texi(,9421) blocking-factor when operating on the archive.
@xref{Formats}, for other
+../tar_texi/tar.texi(,9422) examples of format parameter considerations.
+../tar_texi/tar.texi(,9423)
+../tar_texi/tar.texi(,9424) @node Blocking Factor
+../tar_texi/tar.texi(,9425) @subsection The Blocking Factor of an Archive
+../tar_texi/tar.texi(,9426) @cindex Blocking Factor
+../tar_texi/tar.texi(,9427) @cindex Record Size
+../tar_texi/tar.texi(,9428) @cindex Number of blocks per record
+../tar_texi/tar.texi(,9429) @cindex Number of bytes per record
+../tar_texi/tar.texi(,9430) @cindex Bytes per record
+../tar_texi/tar.texi(,9431) @cindex Blocks per record
+../tar_texi/tar.texi(UNREVISED,9432) @quotation
+../tar_texi/tar.texi(UNREVISED,9432) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9432) @end quotation
+../tar_texi/tar.texi(UNREVISED,9432)
+../tar_texi/tar.texi(,9433)
+../tar_texi/tar.texi(,9434) @opindex blocking-factor
+../tar_texi/tar.texi(,9435) The data in an archive is grouped into blocks,
which are 512 bytes.
+../tar_texi/tar.texi(,9436) Blocks are read and written in whole number
multiples called
+../tar_texi/tar.texi(,9437) @dfn{records}. The number of blocks in a record
(i.e. the size of a
+../tar_texi/tar.texi(,9438) record in units of 512 bytes) is called the
@dfn{blocking factor}.
+../tar_texi/tar.texi(,9439) The @address@hidden (@option{-b
+../tar_texi/tar.texi(,9440) @var{512-size}}) option specifies the blocking
factor of an archive.
+../tar_texi/tar.texi(,9441) The default blocking factor is typically 20 (i.e.,
10240 bytes), but
+../tar_texi/tar.texi(,9442) can be specified at installation. To find out the
blocking factor of
+../tar_texi/tar.texi(,9443) an existing archive, use @samp{tar --list
address@hidden
+../tar_texi/tar.texi(,9444) This may not work on some devices.
+../tar_texi/tar.texi(,9445)
+../tar_texi/tar.texi(,9446) Records are separated by gaps, which waste space
on the archive media.
+../tar_texi/tar.texi(,9447) If you are archiving on magnetic tape, using a
larger blocking factor
+../tar_texi/tar.texi(,9448) (and therefore larger records) provides faster
throughput and allows you
+../tar_texi/tar.texi(,9449) to fit more data on a tape (because there are
fewer gaps). If you are
+../tar_texi/tar.texi(,9450) archiving on cartridge, a very large blocking
factor (say 126 or more)
+../tar_texi/tar.texi(,9451) greatly increases performance. A smaller blocking
factor, on the other
+../tar_texi/tar.texi(,9452) hand, may be useful when archiving small files, to
avoid archiving lots
+../tar_texi/tar.texi(,9453) of nulls as @command{tar} fills out the archive to
the end of the record.
+../tar_texi/tar.texi(,9454) In general, the ideal record size depends on the
size of the
+../tar_texi/tar.texi(,9455) inter-record gaps on the tape you are using, and
the average size of the
+../tar_texi/tar.texi(,9456) files you are archiving. @xref{create}, for
information on
+../tar_texi/tar.texi(,9457) writing archives.
+../tar_texi/tar.texi(,9458)
+../tar_texi/tar.texi(FIXME,9459) @allow-recursion
+../tar_texi/tar.texi(FIXME,9459) @quote-arg
+../tar_texi/tar.texi(FIXME,9459)
+../tar_texi/tar.texi(,9460)
+../tar_texi/tar.texi(,9461) Archives with blocking factors larger than 20
cannot be read
+../tar_texi/tar.texi(,9462) by very old versions of @command{tar}, or by some
newer versions
+../tar_texi/tar.texi(,9463) of @command{tar} running on old machines with
small address spaces.
+../tar_texi/tar.texi(GNUTAR,9464) With @acronym{GNU} @command{tar}, the
blocking factor of an archive is limited
+../tar_texi/tar.texi(,9465) only by the maximum record size of the device
containing the archive,
+../tar_texi/tar.texi(,9466) or by the amount of available virtual memory.
+../tar_texi/tar.texi(,9467)
+../tar_texi/tar.texi(,9468) Also, on some systems, not using adequate blocking
factors, as sometimes
+../tar_texi/tar.texi(,9469) imposed by the device drivers, may yield
unexpected diagnostics. For
+../tar_texi/tar.texi(,9470) example, this has been reported:
+../tar_texi/tar.texi(,9471)
+../tar_texi/tar.texi(,9472) @smallexample
+../tar_texi/tar.texi(,9473) Cannot write to /dev/dlt: Invalid argument
+../tar_texi/tar.texi(,9474) @end smallexample
+../tar_texi/tar.texi(,9475)
+../tar_texi/tar.texi(,9476) @noindent
+../tar_texi/tar.texi(,9477) In such cases, it sometimes happen that the
@command{tar} bundled by
+../tar_texi/tar.texi(GNUTAR,9478) the system is aware of block size
idiosyncrasies, while @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,9479) requires an explicit specification for the block
size,
+../tar_texi/tar.texi(,9480) which it cannot guess. This yields some people to
consider
+../tar_texi/tar.texi(GNUTAR,9481) @acronym{GNU} @command{tar} is misbehaving,
because by comparison,
+../tar_texi/tar.texi(,9482) @cite{the bundle @command{tar} works OK}. Adding
@address@hidden 256}},
+../tar_texi/tar.texi(,9483) for example, might resolve the problem.
+../tar_texi/tar.texi(,9484)
+../tar_texi/tar.texi(,9485) If you use a non-default blocking factor when you
create an archive, you
+../tar_texi/tar.texi(,9486) must specify the same blocking factor when you
modify that archive. Some
+../tar_texi/tar.texi(,9487) archive devices will also require you to specify
the blocking factor when
+../tar_texi/tar.texi(,9488) reading that archive, however this is not
typically the case. Usually, you
+../tar_texi/tar.texi(,9489) can use @option{--list} (@option{-t}) without
specifying a blocking address@hidden
+../tar_texi/tar.texi(,9490) reports a non-default record size and then lists
the archive members as
+../tar_texi/tar.texi(,9491) it would normally. To extract files from an
archive with a non-standard
+../tar_texi/tar.texi(,9492) blocking factor (particularly if you're not sure
what the blocking factor
+../tar_texi/tar.texi(,9493) is), you can usually use the
@option{--read-full-records} (@option{-B}) option while
+../tar_texi/tar.texi(,9494) specifying a blocking factor larger then the
blocking factor of the archive
+../tar_texi/tar.texi(,9495) (i.e. @samp{tar --extract --read-full-records
--blocking-factor=300}.
+../tar_texi/tar.texi(,9496) @xref{list}, for more information on the
@option{--list} (@option{-t})
+../tar_texi/tar.texi(,9497) operation. @xref{Reading}, for a more detailed
explanation of that option.
+../tar_texi/tar.texi(,9498)
+../tar_texi/tar.texi(,9499) @table @option
+../tar_texi/tar.texi(,9500) @item address@hidden
+../tar_texi/tar.texi(,9501) @itemx -b @var{number}
+../tar_texi/tar.texi(,9502) Specifies the blocking factor of an archive. Can
be used with any
+../tar_texi/tar.texi(,9503) operation, but is usually not necessary with
@option{--list} (@option{-t}).
+../tar_texi/tar.texi(,9504) @end table
+../tar_texi/tar.texi(,9505)
+../tar_texi/tar.texi(,9506) Device blocking
+../tar_texi/tar.texi(,9507)
+../tar_texi/tar.texi(,9508) @table @option
+../tar_texi/tar.texi(,9509) @item -b @var{blocks}
+../tar_texi/tar.texi(,9510) @itemx address@hidden
+../tar_texi/tar.texi(,9511) Set record size to @address@hidden * 512} bytes.
+../tar_texi/tar.texi(,9512)
+../tar_texi/tar.texi(,9513) This option is used to specify a @dfn{blocking
factor} for the archive.
+../tar_texi/tar.texi(,9514) When reading or writing the archive,
@command{tar}, will do reads and writes
+../tar_texi/tar.texi(,9515) of the archive in records of @address@hidden
bytes. This is true
+../tar_texi/tar.texi(,9516) even when the archive is compressed. Some devices
requires that all
+../tar_texi/tar.texi(,9517) write operations be a multiple of a certain size,
and so, @command{tar}
+../tar_texi/tar.texi(,9518) pads the archive out to the next record boundary.
+../tar_texi/tar.texi(,9519)
+../tar_texi/tar.texi(,9520) The default blocking factor is set when
@command{tar} is compiled, and is
+../tar_texi/tar.texi(,9521) typically 20. Blocking factors larger than 20
cannot be read by very
+../tar_texi/tar.texi(,9522) old versions of @command{tar}, or by some newer
versions of @command{tar}
+../tar_texi/tar.texi(,9523) running on old machines with small address spaces.
+../tar_texi/tar.texi(,9524)
+../tar_texi/tar.texi(,9525) With a magnetic tape, larger records give faster
throughput and fit
+../tar_texi/tar.texi(,9526) more data on a tape (because there are fewer
inter-record gaps).
+../tar_texi/tar.texi(,9527) If the archive is in a disk file or a pipe, you
may want to specify
+../tar_texi/tar.texi(,9528) a smaller blocking factor, since a large one will
result in a large
+../tar_texi/tar.texi(,9529) number of null bytes at the end of the archive.
+../tar_texi/tar.texi(,9530)
+../tar_texi/tar.texi(,9531) When writing cartridge or other streaming tapes, a
much larger
+../tar_texi/tar.texi(,9532) blocking factor (say 126 or more) will greatly
increase performance.
+../tar_texi/tar.texi(,9533) However, you must specify the same blocking factor
when reading or
+../tar_texi/tar.texi(,9534) updating the archive.
+../tar_texi/tar.texi(,9535)
+../tar_texi/tar.texi(,9536) Apparently, Exabyte drives have a physical block
size of 8K bytes.
+../tar_texi/tar.texi(,9537) If we choose our blocksize as a multiple of 8k
bytes, then the problem
+../tar_texi/tar.texi(,9538) seems to disappear. Id est, we are using block
size of 112 right
+../tar_texi/tar.texi(,9539) now, and we haven't had the problem since we
address@hidden
+../tar_texi/tar.texi(,9540)
+../tar_texi/tar.texi(GNUTAR,9541) With @acronym{GNU} @command{tar} the
blocking factor is limited only
+../tar_texi/tar.texi(,9542) by the maximum record size of the device
containing the archive, or by
+../tar_texi/tar.texi(,9543) the amount of available virtual memory.
+../tar_texi/tar.texi(,9544)
+../tar_texi/tar.texi(,9545) However, deblocking or reblocking is virtually
avoided in a special
+../tar_texi/tar.texi(,9546) case which often occurs in practice, but which
requires all the
+../tar_texi/tar.texi(,9547) following conditions to be simultaneously true:
+../tar_texi/tar.texi(,9548) @itemize @bullet
+../tar_texi/tar.texi(,9549) @item
+../tar_texi/tar.texi(,9550) the archive is subject to a compression option,
+../tar_texi/tar.texi(,9551) @item
+../tar_texi/tar.texi(,9552) the archive is not handled through standard input
or output, nor
+../tar_texi/tar.texi(,9553) redirected nor piped,
+../tar_texi/tar.texi(,9554) @item
+../tar_texi/tar.texi(,9555) the archive is directly handled to a local disk,
instead of any special
+../tar_texi/tar.texi(,9556) device,
+../tar_texi/tar.texi(,9557) @item
+../tar_texi/tar.texi(,9558) @option{--blocking-factor} is not explicitly
specified on the @command{tar}
+../tar_texi/tar.texi(,9559) invocation.
+../tar_texi/tar.texi(,9560) @end itemize
+../tar_texi/tar.texi(,9561)
+../tar_texi/tar.texi(,9562) If the output goes directly to a local disk, and
not through
+../tar_texi/tar.texi(,9563) stdout, then the last write is not extended to a
full record size.
+../tar_texi/tar.texi(,9564) Otherwise, reblocking occurs. Here are a few
other remarks on this
+../tar_texi/tar.texi(,9565) topic:
+../tar_texi/tar.texi(,9566)
+../tar_texi/tar.texi(,9567) @itemize @bullet
+../tar_texi/tar.texi(,9568)
+../tar_texi/tar.texi(,9569) @item
+../tar_texi/tar.texi(,9570) @command{gzip} will complain about trailing
garbage if asked to
+../tar_texi/tar.texi(,9571) uncompress a compressed archive on tape, there is
an option to turn
+../tar_texi/tar.texi(,9572) the message off, but it breaks the regularity of
simply having to use
+../tar_texi/tar.texi(,9573) @address@hidden -d} for decompression. It would
be nice if gzip was
+../tar_texi/tar.texi(,9574) silently ignoring any number of trailing zeros.
I'll ask Jean-loup
+../tar_texi/tar.texi(,9575) Gailly, by sending a copy of this message to him.
+../tar_texi/tar.texi(,9576)
+../tar_texi/tar.texi(,9577) @item
+../tar_texi/tar.texi(,9578) @command{compress} does not show this problem, but
as Jean-loup pointed
+../tar_texi/tar.texi(,9579) out to Michael, @samp{compress -d} silently adds
garbage after
+../tar_texi/tar.texi(,9580) the result of decompression, which tar ignores
because it already
+../tar_texi/tar.texi(,9581) recognized its end-of-file indicator. So this bug
may be safely
+../tar_texi/tar.texi(,9582) ignored.
+../tar_texi/tar.texi(,9583)
+../tar_texi/tar.texi(,9584) @item
+../tar_texi/tar.texi(,9585) @samp{gzip -d -q} will be silent about the
trailing zeros indeed,
+../tar_texi/tar.texi(,9586) but will still return an exit status of 2 which
tar reports in turn.
+../tar_texi/tar.texi(,9587) @command{tar} might ignore the exit status
returned, but I hate doing
+../tar_texi/tar.texi(,9588) that, as it weakens the protection @command{tar}
offers users against
+../tar_texi/tar.texi(,9589) other possible problems at decompression time. If
@command{gzip} was
+../tar_texi/tar.texi(,9590) silently skipping trailing zeros @emph{and} also
avoiding setting the
+../tar_texi/tar.texi(,9591) exit status in this innocuous case, that would
solve this situation.
+../tar_texi/tar.texi(,9592)
+../tar_texi/tar.texi(,9593) @item
+../tar_texi/tar.texi(,9594) @command{tar} should become more solid at not
stopping to read a pipe at
+../tar_texi/tar.texi(,9595) the first null block encountered. This
inelegantly breaks the pipe.
+../tar_texi/tar.texi(,9596) @command{tar} should rather drain the pipe out
before exiting itself.
+../tar_texi/tar.texi(,9597) @end itemize
+../tar_texi/tar.texi(,9598)
+../tar_texi/tar.texi(xopindex,9599) @opindex address@hidden, short description}
+../tar_texi/tar.texi(,9600) @item -i
+../tar_texi/tar.texi(,9601) @itemx --ignore-zeros
+../tar_texi/tar.texi(,9602) Ignore blocks of zeros in archive (means EOF).
+../tar_texi/tar.texi(,9603)
+../tar_texi/tar.texi(,9604) The @option{--ignore-zeros} (@option{-i}) option
causes @command{tar} to ignore blocks
+../tar_texi/tar.texi(,9605) of zeros in the archive. Normally a block of
zeros indicates the
+../tar_texi/tar.texi(,9606) end of the archive, but when reading a damaged
archive, or one which
+../tar_texi/tar.texi(,9607) was created by concatenating several archives
together, this option
+../tar_texi/tar.texi(,9608) allows @command{tar} to read the entire archive.
This option is not on
+../tar_texi/tar.texi(,9609) by default because many versions of @command{tar}
write garbage after
+../tar_texi/tar.texi(,9610) the zeroed blocks.
+../tar_texi/tar.texi(,9611)
+../tar_texi/tar.texi(,9612) Note that this option causes @command{tar} to read
to the end of the
+../tar_texi/tar.texi(,9613) archive file, which may sometimes avoid problems
when multiple files
+../tar_texi/tar.texi(,9614) are stored on a single physical tape.
+../tar_texi/tar.texi(,9615)
+../tar_texi/tar.texi(xopindex,9616) @opindex address@hidden, short description}
+../tar_texi/tar.texi(,9617) @item -B
+../tar_texi/tar.texi(,9618) @itemx --read-full-records
+../tar_texi/tar.texi(,9619) Reblock as we read (for reading 4.2BSD pipes).
+../tar_texi/tar.texi(,9620)
+../tar_texi/tar.texi(,9621) If @option{--read-full-records} is used,
@command{tar}
+../tar_texi/tar.texi(,9622) will not panic if an attempt to read a record from
the archive does
+../tar_texi/tar.texi(,9623) not return a full record. Instead, @command{tar}
will keep reading
+../tar_texi/tar.texi(,9624) until it has obtained a full
+../tar_texi/tar.texi(,9625) record.
+../tar_texi/tar.texi(,9626)
+../tar_texi/tar.texi(,9627) This option is turned on by default when
@command{tar} is reading
+../tar_texi/tar.texi(,9628) an archive from standard input, or from a remote
machine. This is
+../tar_texi/tar.texi(,9629) because on BSD Unix systems, a read of a pipe will
return however
+../tar_texi/tar.texi(,9630) much happens to be in the pipe, even if it is less
than @command{tar}
+../tar_texi/tar.texi(,9631) requested. If this option was not used,
@command{tar} would fail as
+../tar_texi/tar.texi(,9632) soon as it read an incomplete record from the pipe.
+../tar_texi/tar.texi(,9633)
+../tar_texi/tar.texi(,9634) This option is also useful with the commands for
updating an archive.
+../tar_texi/tar.texi(,9635)
+../tar_texi/tar.texi(,9636) @end table
+../tar_texi/tar.texi(,9637)
+../tar_texi/tar.texi(,9638) Tape blocking
+../tar_texi/tar.texi(,9639)
+../tar_texi/tar.texi(FIXME,9640) @allow-recursion
+../tar_texi/tar.texi(FIXME,9640) @quote-arg
+../tar_texi/tar.texi(FIXME,9640)
+../tar_texi/tar.texi(,9641)
+../tar_texi/tar.texi(,9642) @cindex blocking factor
+../tar_texi/tar.texi(,9643) @cindex tape blocking
+../tar_texi/tar.texi(,9644)
+../tar_texi/tar.texi(,9645) When handling various tapes or cartridges, you
have to take care of
+../tar_texi/tar.texi(,9646) selecting a proper blocking, that is, the number
of disk blocks you
+../tar_texi/tar.texi(,9647) put together as a single tape block on the tape,
without intervening
+../tar_texi/tar.texi(,9648) tape gaps. A @dfn{tape gap} is a small landing
area on the tape
+../tar_texi/tar.texi(,9649) with no information on it, used for decelerating
the tape to a
+../tar_texi/tar.texi(,9650) full stop, and for later regaining the reading or
writing speed.
+../tar_texi/tar.texi(,9651) When the tape driver starts reading a record, the
record has to
+../tar_texi/tar.texi(,9652) be read whole without stopping, as a tape gap is
needed to stop the
+../tar_texi/tar.texi(,9653) tape motion without loosing information.
+../tar_texi/tar.texi(,9654)
+../tar_texi/tar.texi(,9655) @cindex Exabyte blocking
+../tar_texi/tar.texi(,9656) @cindex DAT blocking
+../tar_texi/tar.texi(,9657) Using higher blocking (putting more disk blocks
per tape block) will use
+../tar_texi/tar.texi(,9658) the tape more efficiently as there will be less
tape gaps. But reading
+../tar_texi/tar.texi(,9659) such tapes may be more difficult for the system,
as more memory will be
+../tar_texi/tar.texi(,9660) required to receive at once the whole record.
Further, if there is a
+../tar_texi/tar.texi(,9661) reading error on a huge record, this is less
likely that the system will
+../tar_texi/tar.texi(,9662) succeed in recovering the information. So,
blocking should not be too
+../tar_texi/tar.texi(,9663) low, nor it should be too high. @command{tar}
uses by default a blocking of
+../tar_texi/tar.texi(,9664) 20 for historical reasons, and it does not really
matter when reading or
+../tar_texi/tar.texi(,9665) writing to disk. Current tape technology would
easily accommodate higher
+../tar_texi/tar.texi(,9666) blockings. Sun recommends a blocking of 126 for
Exabytes and 96 for DATs.
+../tar_texi/tar.texi(,9667) We were told that for some DLT drives, the
blocking should be a multiple
+../tar_texi/tar.texi(,9668) of 4Kb, preferably 64Kb (@address@hidden 128}}) or
256 for decent performance.
+../tar_texi/tar.texi(,9669) Other manufacturers may use different
recommendations for the same tapes.
+../tar_texi/tar.texi(,9670) This might also depends of the buffering
techniques used inside modern
+../tar_texi/tar.texi(,9671) tape controllers. Some imposes a minimum
blocking, or a maximum blocking.
+../tar_texi/tar.texi(,9672) Others request blocking to be some exponent of two.
+../tar_texi/tar.texi(,9673)
+../tar_texi/tar.texi(,9674) So, there is no fixed rule for blocking. But
blocking at read time
+../tar_texi/tar.texi(,9675) should ideally be the same as blocking used at
write time. At one place
+../tar_texi/tar.texi(,9676) I know, with a wide variety of equipment, they
found it best to use a
+../tar_texi/tar.texi(,9677) blocking of 32 to guarantee that their tapes are
fully interchangeable.
+../tar_texi/tar.texi(,9678)
+../tar_texi/tar.texi(,9679) I was also told that, for recycled tapes, prior
erasure (by the same
+../tar_texi/tar.texi(,9680) drive unit that will be used to create the
archives) sometimes lowers
+../tar_texi/tar.texi(,9681) the error rates observed at rewriting time.
+../tar_texi/tar.texi(,9682)
+../tar_texi/tar.texi(,9683) I might also use @option{--number-blocks} instead
of
+../tar_texi/tar.texi(,9684) @option{--block-number}, so @option{--block} will
then expand to
+../tar_texi/tar.texi(,9685) @option{--blocking-factor} unambiguously.
+../tar_texi/tar.texi(,9686)
+../tar_texi/tar.texi(,9687) @node Many
+../tar_texi/tar.texi(,9688) @section Many Archives on One Tape
+../tar_texi/tar.texi(,9689)
+../tar_texi/tar.texi(FIXME,9690) @allow-recursion
+../tar_texi/tar.texi(FIXME,9690) @quote-arg
+../tar_texi/tar.texi(FIXME,9690)
+../tar_texi/tar.texi(,9691)
+../tar_texi/tar.texi(,9692) @findex ntape @r{device}
+../tar_texi/tar.texi(,9693) Most tape devices have two entries in the
@file{/dev} directory, or
+../tar_texi/tar.texi(,9694) entries that come in pairs, which differ only in
the minor number for
+../tar_texi/tar.texi(,9695) this device. Let's take for example
@file{/dev/tape}, which often
+../tar_texi/tar.texi(,9696) points to the only or usual tape device of a given
system. There might
+../tar_texi/tar.texi(,9697) be a corresponding @file{/dev/nrtape} or
@file{/dev/ntape}. The simpler
+../tar_texi/tar.texi(,9698) name is the @emph{rewinding} version of the
device, while the name
+../tar_texi/tar.texi(,9699) having @samp{nr} in it is the @emph{no rewinding}
version of the same
+../tar_texi/tar.texi(,9700) device.
+../tar_texi/tar.texi(,9701)
+../tar_texi/tar.texi(,9702) A rewinding tape device will bring back the tape
to its beginning point
+../tar_texi/tar.texi(,9703) automatically when this device is opened or
closed. Since @command{tar}
+../tar_texi/tar.texi(,9704) opens the archive file before using it and closes
it afterwards, this
+../tar_texi/tar.texi(,9705) means that a simple:
+../tar_texi/tar.texi(,9706)
+../tar_texi/tar.texi(,9707) @smallexample
+../tar_texi/tar.texi(,9708) $ @kbd{tar cf /dev/tape @var{directory}}
+../tar_texi/tar.texi(,9709) @end smallexample
+../tar_texi/tar.texi(,9710)
+../tar_texi/tar.texi(,9711) @noindent
+../tar_texi/tar.texi(,9712) will reposition the tape to its beginning both
prior and after saving
+../tar_texi/tar.texi(,9713) @var{directory} contents to it, thus erasing prior
tape contents and
+../tar_texi/tar.texi(,9714) making it so that any subsequent write operation
will destroy what has
+../tar_texi/tar.texi(,9715) just been saved.
+../tar_texi/tar.texi(,9716)
+../tar_texi/tar.texi(,9717) @cindex tape positioning
+../tar_texi/tar.texi(,9718) So, a rewinding device is normally meant to hold
one and only one file.
+../tar_texi/tar.texi(,9719) If you want to put more than one @command{tar}
archive on a given tape, you
+../tar_texi/tar.texi(,9720) will need to avoid using the rewinding version of
the tape device. You
+../tar_texi/tar.texi(,9721) will also have to pay special attention to tape
positioning. Errors in
+../tar_texi/tar.texi(,9722) positioning may overwrite the valuable data
already on your tape. Many
+../tar_texi/tar.texi(,9723) people, burnt by past experiences, will only use
rewinding devices and
+../tar_texi/tar.texi(,9724) limit themselves to one file per tape, precisely
to avoid the risk of
+../tar_texi/tar.texi(,9725) such errors. Be fully aware that writing at the
wrong position on a
+../tar_texi/tar.texi(,9726) tape loses all information past this point and
most probably until the
+../tar_texi/tar.texi(,9727) end of the tape, and this destroyed information
@emph{cannot} be
+../tar_texi/tar.texi(,9728) recovered.
+../tar_texi/tar.texi(,9729)
+../tar_texi/tar.texi(,9730) To save @var{directory-1} as a first archive at
the beginning of a
+../tar_texi/tar.texi(,9731) tape, and leave that tape ready for a second
archive, you should use:
+../tar_texi/tar.texi(,9732)
+../tar_texi/tar.texi(,9733) @smallexample
+../tar_texi/tar.texi(,9734) $ @kbd{mt -f /dev/nrtape rewind}
+../tar_texi/tar.texi(,9735) $ @kbd{tar cf /dev/nrtape @var{directory-1}}
+../tar_texi/tar.texi(,9736) @end smallexample
+../tar_texi/tar.texi(,9737)
+../tar_texi/tar.texi(,9738) @cindex tape marks
+../tar_texi/tar.texi(,9739) @dfn{Tape marks} are special magnetic patterns
written on the tape
+../tar_texi/tar.texi(,9740) media, which are later recognizable by the reading
hardware. These
+../tar_texi/tar.texi(,9741) marks are used after each file, when there are
many on a single tape.
+../tar_texi/tar.texi(,9742) An empty file (that is to say, two tape marks in a
row) signal the
+../tar_texi/tar.texi(,9743) logical end of the tape, after which no file
exist. Usually,
+../tar_texi/tar.texi(,9744) non-rewinding tape device drivers will react to
the close request issued
+../tar_texi/tar.texi(,9745) by @command{tar} by first writing two tape marks
after your archive, and by
+../tar_texi/tar.texi(,9746) backspacing over one of these. So, if you remove
the tape at that time
+../tar_texi/tar.texi(,9747) from the tape drive, it is properly terminated.
But if you write
+../tar_texi/tar.texi(,9748) another file at the current position, the second
tape mark will be
+../tar_texi/tar.texi(,9749) erased by the new information, leaving only one
tape mark between files.
+../tar_texi/tar.texi(,9750)
+../tar_texi/tar.texi(,9751) So, you may now save @var{directory-2} as a second
archive after the
+../tar_texi/tar.texi(,9752) first on the same tape by issuing the command:
+../tar_texi/tar.texi(,9753)
+../tar_texi/tar.texi(,9754) @smallexample
+../tar_texi/tar.texi(,9755) $ @kbd{tar cf /dev/nrtape @var{directory-2}}
+../tar_texi/tar.texi(,9756) @end smallexample
+../tar_texi/tar.texi(,9757)
+../tar_texi/tar.texi(,9758) @noindent
+../tar_texi/tar.texi(,9759) and so on for all the archives you want to put on
the same tape.
+../tar_texi/tar.texi(,9760)
+../tar_texi/tar.texi(,9761) Another usual case is that you do not write all
the archives the same
+../tar_texi/tar.texi(,9762) day, and you need to remove and store the tape
between two archive
+../tar_texi/tar.texi(,9763) sessions. In general, you must remember how many
files are already
+../tar_texi/tar.texi(,9764) saved on your tape. Suppose your tape already has
16 files on it, and
+../tar_texi/tar.texi(,9765) that you are ready to write the 17th. You have to
take care of skipping
+../tar_texi/tar.texi(,9766) the first 16 tape marks before saving
@var{directory-17}, say, by using
+../tar_texi/tar.texi(,9767) these commands:
+../tar_texi/tar.texi(,9768)
+../tar_texi/tar.texi(,9769) @smallexample
+../tar_texi/tar.texi(,9770) $ @kbd{mt -f /dev/nrtape rewind}
+../tar_texi/tar.texi(,9771) $ @kbd{mt -f /dev/nrtape fsf 16}
+../tar_texi/tar.texi(,9772) $ @kbd{tar cf /dev/nrtape @var{directory-17}}
+../tar_texi/tar.texi(,9773) @end smallexample
+../tar_texi/tar.texi(,9774)
+../tar_texi/tar.texi(,9775) In all the previous examples, we put aside
blocking considerations, but
+../tar_texi/tar.texi(,9776) you should do the proper things for that as well.
@xref{Blocking}.
+../tar_texi/tar.texi(,9777)
+../tar_texi/tar.texi(,9778) @menu
+../tar_texi/tar.texi(,9779) * Tape Positioning:: Tape Positions and
Tape Marks
+../tar_texi/tar.texi(,9780) * mt:: The @command{mt}
Utility
+../tar_texi/tar.texi(,9781) @end menu
+../tar_texi/tar.texi(,9782)
+../tar_texi/tar.texi(,9783) @node Tape Positioning
+../tar_texi/tar.texi(,9784) @subsection Tape Positions and Tape Marks
+../tar_texi/tar.texi(UNREVISED,9785) @quotation
+../tar_texi/tar.texi(UNREVISED,9785) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9785) @end quotation
+../tar_texi/tar.texi(UNREVISED,9785)
+../tar_texi/tar.texi(,9786)
+../tar_texi/tar.texi(,9787) Just as archives can store more than one file from
the file system,
+../tar_texi/tar.texi(,9788) tapes can store more than one archive file. To
keep track of where
+../tar_texi/tar.texi(,9789) archive files (or any other type of file stored on
tape) begin and
+../tar_texi/tar.texi(,9790) end, tape archive devices write magnetic @dfn{tape
marks} on the
+../tar_texi/tar.texi(,9791) archive media. Tape drives write one tape mark
between files,
+../tar_texi/tar.texi(,9792) two at the end of all the file entries.
+../tar_texi/tar.texi(,9793)
+../tar_texi/tar.texi(,9794) If you think of data as a series of records
"rrrr"'s, and tape marks as
+../tar_texi/tar.texi(,9795) "*"'s, a tape might look like the following:
+../tar_texi/tar.texi(,9796)
+../tar_texi/tar.texi(,9797) @smallexample
+../tar_texi/tar.texi(,9798)
rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
+../tar_texi/tar.texi(,9799) @end smallexample
+../tar_texi/tar.texi(,9800)
+../tar_texi/tar.texi(,9801) Tape devices read and write tapes using a
read/write @dfn{tape
+../tar_texi/tar.texi(,9802) head}---a physical part of the device which can
only access one
+../tar_texi/tar.texi(,9803) point on the tape at a time. When you use
@command{tar} to read or
+../tar_texi/tar.texi(,9804) write archive data from a tape device, the device
will begin reading
+../tar_texi/tar.texi(,9805) or writing from wherever on the tape the tape head
happens to be,
+../tar_texi/tar.texi(,9806) regardless of which archive or what part of the
archive the tape
+../tar_texi/tar.texi(,9807) head is on. Before writing an archive, you should
make sure that no
+../tar_texi/tar.texi(,9808) data on the tape will be overwritten (unless it is
no longer needed).
+../tar_texi/tar.texi(,9809) Before reading an archive, you should make sure
the tape head is at
+../tar_texi/tar.texi(,9810) the beginning of the archive you want to read.
You can do it manually
+../tar_texi/tar.texi(,9811) via @code{mt} utility (@pxref{mt}). The
@code{restore} script does
+../tar_texi/tar.texi(,9812) that automatically (@pxref{Scripted Restoration}).
+../tar_texi/tar.texi(,9813)
+../tar_texi/tar.texi(,9814) If you want to add new archive file entries to a
tape, you should
+../tar_texi/tar.texi(,9815) advance the tape to the end of the existing file
entries, backspace
+../tar_texi/tar.texi(,9816) over the last tape mark, and write the new archive
file. If you were
+../tar_texi/tar.texi(,9817) to add two archives to the example above, the tape
might look like the
+../tar_texi/tar.texi(,9818) following:
+../tar_texi/tar.texi(,9819)
+../tar_texi/tar.texi(,9820) @smallexample
+../tar_texi/tar.texi(,9821)
rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
+../tar_texi/tar.texi(,9822) @end smallexample
+../tar_texi/tar.texi(,9823)
+../tar_texi/tar.texi(,9824) @node mt
+../tar_texi/tar.texi(,9825) @subsection The @command{mt} Utility
+../tar_texi/tar.texi(UNREVISED,9826) @quotation
+../tar_texi/tar.texi(UNREVISED,9826) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9826) @end quotation
+../tar_texi/tar.texi(UNREVISED,9826)
+../tar_texi/tar.texi(,9827)
+../tar_texi/tar.texi(FIXME,9829) @allow-recursion
+../tar_texi/tar.texi(FIXME,9829) @quote-arg
+../tar_texi/tar.texi(FIXME,9829)
+../tar_texi/tar.texi(,9830) @xref{Blocking Factor}.
+../tar_texi/tar.texi(,9831)
+../tar_texi/tar.texi(,9832) You can use the @command{mt} utility to advance or
rewind a tape past a
+../tar_texi/tar.texi(,9833) specified number of archive files on the tape.
This will allow you
+../tar_texi/tar.texi(,9834) to move to the beginning of an archive before
extracting or reading
+../tar_texi/tar.texi(,9835) it, or to the end of all the archives before
writing a new one.
+../tar_texi/tar.texi(FIXME,9837) @allow-recursion
+../tar_texi/tar.texi(FIXME,9837) @quote-arg
+../tar_texi/tar.texi(FIXME,9837)
+../tar_texi/tar.texi(,9838)
+../tar_texi/tar.texi(,9839) The syntax of the @command{mt} command is:
+../tar_texi/tar.texi(,9840)
+../tar_texi/tar.texi(,9841) @smallexample
+../tar_texi/tar.texi(,9842) @kbd{mt [-f @var{tapename}] @var{operation}
address@hidden
+../tar_texi/tar.texi(,9843) @end smallexample
+../tar_texi/tar.texi(,9844)
+../tar_texi/tar.texi(,9845) where @var{tapename} is the name of the tape
device, @var{number} is
+../tar_texi/tar.texi(,9846) the number of times an operation is performed
(with a default of one),
+../tar_texi/tar.texi(,9847) and @var{operation} is one of the following:
+../tar_texi/tar.texi(,9848)
+../tar_texi/tar.texi(FIXME,9849) @allow-recursion
+../tar_texi/tar.texi(FIXME,9849) @quote-arg
+../tar_texi/tar.texi(FIXME,9849)
+../tar_texi/tar.texi(,9850)
+../tar_texi/tar.texi(,9851) @table @option
+../tar_texi/tar.texi(,9852) @item eof
+../tar_texi/tar.texi(,9853) @itemx weof
+../tar_texi/tar.texi(,9854) Writes @var{number} tape marks at the current
position on the tape.
+../tar_texi/tar.texi(,9855)
+../tar_texi/tar.texi(,9856) @item fsf
+../tar_texi/tar.texi(,9857) Moves tape position forward @var{number} files.
+../tar_texi/tar.texi(,9858)
+../tar_texi/tar.texi(,9859) @item bsf
+../tar_texi/tar.texi(,9860) Moves tape position back @var{number} files.
+../tar_texi/tar.texi(,9861)
+../tar_texi/tar.texi(,9862) @item rewind
+../tar_texi/tar.texi(,9863) Rewinds the tape. (Ignores @var{number}).
+../tar_texi/tar.texi(,9864)
+../tar_texi/tar.texi(,9865) @item offline
+../tar_texi/tar.texi(,9866) @itemx rewoff1
+../tar_texi/tar.texi(,9867) Rewinds the tape and takes the tape device
off-line. (Ignores @var{number}).
+../tar_texi/tar.texi(,9868)
+../tar_texi/tar.texi(,9869) @item status
+../tar_texi/tar.texi(,9870) Prints status information about the tape unit.
+../tar_texi/tar.texi(,9871)
+../tar_texi/tar.texi(,9872) @end table
+../tar_texi/tar.texi(,9873)
+../tar_texi/tar.texi(FIXME,9874) @allow-recursion
+../tar_texi/tar.texi(FIXME,9874) @quote-arg
+../tar_texi/tar.texi(FIXME,9874)
+../tar_texi/tar.texi(,9875)
+../tar_texi/tar.texi(,9876) If you don't specify a @var{tapename},
@command{mt} uses the environment
+../tar_texi/tar.texi(,9877) variable @env{TAPE}; if @env{TAPE} is not set,
@command{mt} will use
+../tar_texi/tar.texi(,9878) the default device specified in your
@file{sys/mtio.h} file
+../tar_texi/tar.texi(,9879) (@code{DEFTAPE} variable). If this is not
defined, the program will
+../tar_texi/tar.texi(,9880) display a descriptive error message and exit with
code 1.
+../tar_texi/tar.texi(,9881)
+../tar_texi/tar.texi(,9882) @command{mt} returns a 0 exit status when the
operation(s) were
+../tar_texi/tar.texi(,9883) successful, 1 if the command was unrecognized, and
2 if an operation
+../tar_texi/tar.texi(,9884) failed.
+../tar_texi/tar.texi(,9885)
+../tar_texi/tar.texi(,9886) @node Using Multiple Tapes
+../tar_texi/tar.texi(,9887) @section Using Multiple Tapes
+../tar_texi/tar.texi(,9888)
+../tar_texi/tar.texi(,9889) Often you might want to write a large archive, one
larger than will fit
+../tar_texi/tar.texi(,9890) on the actual tape you are using. In such a case,
you can run multiple
+../tar_texi/tar.texi(,9891) @command{tar} commands, but this can be
inconvenient, particularly if you
+../tar_texi/tar.texi(,9892) are using options like @address@hidden or dumping
entire file systems.
+../tar_texi/tar.texi(,9893) Therefore, @command{tar} provides a special mode
for creating
+../tar_texi/tar.texi(,9894) multi-volume archives.
+../tar_texi/tar.texi(,9895)
+../tar_texi/tar.texi(,9896) @dfn{Multi-volume} archive is a single
@command{tar} archive, stored
+../tar_texi/tar.texi(,9897) on several media volumes of fixed size. Although
in this section we will
+../tar_texi/tar.texi(,9898) often call @samp{volume} a @dfn{tape}, there is
absolutely no
+../tar_texi/tar.texi(,9899) requirement for multi-volume archives to be stored
on tapes. Instead,
+../tar_texi/tar.texi(,9900) they can use whatever media type the user finds
convenient, they can
+../tar_texi/tar.texi(,9901) even be located on files.
+../tar_texi/tar.texi(,9902)
+../tar_texi/tar.texi(GNUTAR,9903) When creating a multi-volume arvhive,
@acronym{GNU} @command{tar} continues to fill
+../tar_texi/tar.texi(,9904) current volume until it runs out of space, then it
switches to
+../tar_texi/tar.texi(,9905) next volume (usually the operator is queried to
replace the tape on
+../tar_texi/tar.texi(,9906) this point), and continues working on the new
volume. This operation
+../tar_texi/tar.texi(GNUTAR,9907) continues untill all requested files are
dumped. If @acronym{GNU} @command{tar} detects
+../tar_texi/tar.texi(,9908) end of media while dumping a file, such a file is
archived in split
+../tar_texi/tar.texi(,9909) form. Some very big files can even be split
across several volumes.
+../tar_texi/tar.texi(,9910)
+../tar_texi/tar.texi(GNUTAR,9911) Each volume is itself a valid @acronym{GNU}
@command{tar} archive, so it can be read
+../tar_texi/tar.texi(,9912) without any special options. Consequently any
file member residing
+../tar_texi/tar.texi(,9913) entirely on one volume can be extracted or
otherwise operated upon
+../tar_texi/tar.texi(,9914) without needing the other volume. Sure enough, to
extract a split
+../tar_texi/tar.texi(,9915) member you would need all volumes its parts reside
on.
+../tar_texi/tar.texi(,9916)
+../tar_texi/tar.texi(,9917) Multi-volume archives suffer from several
limitations. In particular,
+../tar_texi/tar.texi(,9918) they cannot be compressed.
+../tar_texi/tar.texi(,9919)
+../tar_texi/tar.texi(GNUTAR,9920) @acronym{GNU} @command{tar} is able to
create multi-volume archives of two formats
+../tar_texi/tar.texi(,9921) (@pxref{Formats}): @samp{GNU} and @samp{POSIX}.
+../tar_texi/tar.texi(,9922)
+../tar_texi/tar.texi(,9923) @menu
+../tar_texi/tar.texi(,9924) * Multi-Volume Archives:: Archives Longer
than One Tape or Disk
+../tar_texi/tar.texi(,9925) * Tape Files:: Tape Files
+../tar_texi/tar.texi(,9926) * Tarcat:: Concatenate
Volumes into a Single Archive
+../tar_texi/tar.texi(,9927)
+../tar_texi/tar.texi(,9928) @end menu
+../tar_texi/tar.texi(,9929)
+../tar_texi/tar.texi(,9930) @node Multi-Volume Archives
+../tar_texi/tar.texi(,9931) @subsection Archives Longer than One Tape or Disk
+../tar_texi/tar.texi(,9932) @cindex Multi-volume archives
+../tar_texi/tar.texi(,9933)
+../tar_texi/tar.texi(,9934) @opindex multi-volume
+../tar_texi/tar.texi(,9935) To create an archive that is larger than will fit
on a single unit of
+../tar_texi/tar.texi(,9936) the media, use the @option{--multi-volume}
(@option{-M}) option in conjunction with
+../tar_texi/tar.texi(,9937) the @option{--create} option (@pxref{create}). A
@dfn{multi-volume}
+../tar_texi/tar.texi(,9938) archive can be manipulated like any other archive
(provided the
+../tar_texi/tar.texi(,9939) @option{--multi-volume} option is specified), but
is stored on more
+../tar_texi/tar.texi(,9940) than one tape or disk.
+../tar_texi/tar.texi(,9941)
+../tar_texi/tar.texi(,9942) When you specify @option{--multi-volume},
@command{tar} does not report an
+../tar_texi/tar.texi(,9943) error when it comes to the end of an archive
volume (when reading), or
+../tar_texi/tar.texi(,9944) the end of the media (when writing). Instead, it
prompts you to load
+../tar_texi/tar.texi(,9945) a new storage volume. If the archive is on a
magnetic tape, you
+../tar_texi/tar.texi(,9946) should change tapes when you see the prompt; if
the archive is on a
+../tar_texi/tar.texi(,9947) floppy disk, you should change disks; etc.
+../tar_texi/tar.texi(,9948)
+../tar_texi/tar.texi(,9949) @table @option
+../tar_texi/tar.texi(,9950) @item --multi-volume
+../tar_texi/tar.texi(,9951) @itemx -M
+../tar_texi/tar.texi(,9952) Creates a multi-volume archive, when used in
conjunction with
+../tar_texi/tar.texi(,9953) @option{--create} (@option{-c}). To perform any
other operation on a multi-volume
+../tar_texi/tar.texi(,9954) archive, specify @option{--multi-volume} in
conjunction with that
+../tar_texi/tar.texi(,9955) operation.
+../tar_texi/tar.texi(,9956) For example:
+../tar_texi/tar.texi(,9957)
+../tar_texi/tar.texi(,9958) @smallexample
+../tar_texi/tar.texi(,9959) $ @kbd{tar --create --multi-volume
--file=/dev/tape @var{files}}
+../tar_texi/tar.texi(,9960) @end smallexample
+../tar_texi/tar.texi(,9961) @end table
+../tar_texi/tar.texi(,9962)
+../tar_texi/tar.texi(,9963) The method @command{tar} uses to detect end of
tape is not perfect, and
+../tar_texi/tar.texi(,9964) fails on some operating systems or on some
devices. If @command{tar}
+../tar_texi/tar.texi(,9965) cannot detect the end of the tape itself, you can
use
+../tar_texi/tar.texi(,9966) @option{--tape-length} option to inform it about
the capacity of the
+../tar_texi/tar.texi(,9967) tape:
+../tar_texi/tar.texi(,9968)
+../tar_texi/tar.texi(,9969) @anchor{tape-length}
+../tar_texi/tar.texi(,9970) @table @option
+../tar_texi/tar.texi(,9971) @opindex tape-length
+../tar_texi/tar.texi(,9972) @item address@hidden
+../tar_texi/tar.texi(,9973) @itemx -L @var{size}
+../tar_texi/tar.texi(,9974) Set maximum length of a volume. The @var{size}
argument should then
+../tar_texi/tar.texi(,9975) be the usable size of the tape in units of 1024
bytes. This option
+../tar_texi/tar.texi(,9976) selects @option{--multi-volume} automatically.
For example:
+../tar_texi/tar.texi(,9977)
+../tar_texi/tar.texi(,9978) @smallexample
+../tar_texi/tar.texi(,9979) $ @kbd{tar --create --tape-length=41943040
--file=/dev/tape @var{files}}
+../tar_texi/tar.texi(,9980) @end smallexample
+../tar_texi/tar.texi(,9981) @end table
+../tar_texi/tar.texi(,9982)
+../tar_texi/tar.texi(,9983) @anchor{change volume prompt}
+../tar_texi/tar.texi(GNUTAR,9984) When @acronym{GNU} @command{tar} comes to
the end of a storage media, it asks you to
+../tar_texi/tar.texi(,9985) change the volume. The built-in prompt for POSIX
locale
+../tar_texi/tar.texi(GNUTAR,9986) address@hidden you run @acronym{GNU}
@command{tar} under a different locale, the
+../tar_texi/tar.texi(,9987) translation to the locale's language will be
used.}:
+../tar_texi/tar.texi(,9988)
+../tar_texi/tar.texi(,9989) @smallexample
+../tar_texi/tar.texi(,9990) Prepare volume address@hidden for address@hidden'
and hit return:
+../tar_texi/tar.texi(,9991) @end smallexample
+../tar_texi/tar.texi(,9992)
+../tar_texi/tar.texi(,9993) @noindent
+../tar_texi/tar.texi(,9994) where @var{n} is the ordinal number of the volume
to be created and
+../tar_texi/tar.texi(,9995) @var{archive} is archive file or device name.
+../tar_texi/tar.texi(,9996)
+../tar_texi/tar.texi(,9997) When prompting for a new tape, @command{tar}
accepts any of the following
+../tar_texi/tar.texi(,9998) responses:
+../tar_texi/tar.texi(,9999)
+../tar_texi/tar.texi(,10000) @table @kbd
+../tar_texi/tar.texi(,10001) @item ?
+../tar_texi/tar.texi(,10002) Request @command{tar} to explain possible
responses
+../tar_texi/tar.texi(,10003) @item q
+../tar_texi/tar.texi(,10004) Request @command{tar} to exit immediately.
+../tar_texi/tar.texi(,10005) @item n @var{file-name}
+../tar_texi/tar.texi(,10006) Request @command{tar} to write the next volume on
the file @var{file-name}.
+../tar_texi/tar.texi(,10007) @item !
+../tar_texi/tar.texi(,10008) Request @command{tar} to run a subshell. This
option can be disabled
+../tar_texi/tar.texi(,10009) by giving @option{--restrict} command line option
to
+../tar_texi/tar.texi(,10010) @address@hidden@xref{--restrict}, for more
information about
+../tar_texi/tar.texi(,10011) this option}.
+../tar_texi/tar.texi(,10012) @item y
+../tar_texi/tar.texi(,10013) Request @command{tar} to begin writing the next
volume.
+../tar_texi/tar.texi(,10014) @end table
+../tar_texi/tar.texi(,10015)
+../tar_texi/tar.texi(,10016) (You should only type @samp{y} after you have
changed the tape;
+../tar_texi/tar.texi(,10017) otherwise @command{tar} will write over the
volume it just finished.)
+../tar_texi/tar.texi(,10018)
+../tar_texi/tar.texi(,10019) @cindex Volume number file
+../tar_texi/tar.texi(,10020) @cindex volno file
+../tar_texi/tar.texi(,10021) @anchor{volno-file}
+../tar_texi/tar.texi(,10022) @opindex volno-file
+../tar_texi/tar.texi(,10023) The volume number used by @command{tar} in its
tape-changing prompt
+../tar_texi/tar.texi(,10024) can be changed; if you give the
+../tar_texi/tar.texi(,10025) @address@hidden option, then
+../tar_texi/tar.texi(,10026) @var{file-of-number} should be an unexisting file
to be created, or
+../tar_texi/tar.texi(,10027) else, a file already containing a decimal number.
That number will be
+../tar_texi/tar.texi(,10028) used as the volume number of the first volume
written. When
+../tar_texi/tar.texi(,10029) @command{tar} is finished, it will rewrite the
file with the
+../tar_texi/tar.texi(,10030) now-current volume number. (This does not change
the volume number
+../tar_texi/tar.texi(,10031) written on a tape label, as per @ref{label}, it
@emph{only} affects
+../tar_texi/tar.texi(,10032) the number used in the prompt.)
+../tar_texi/tar.texi(,10033)
+../tar_texi/tar.texi(,10034) @cindex End-of-archive info script
+../tar_texi/tar.texi(,10035) @cindex Info script
+../tar_texi/tar.texi(,10036) @anchor{info-script}
+../tar_texi/tar.texi(,10037) @opindex info-script
+../tar_texi/tar.texi(,10038) @opindex new-volume-script
+../tar_texi/tar.texi(,10039) If you want more elaborate behavior than this,
you can write a special
+../tar_texi/tar.texi(,10040) @dfn{new volume script}, that will be responsible
for changing the
+../tar_texi/tar.texi(,10041) volume, and instruct @command{tar} to use it
instead of its normal
+../tar_texi/tar.texi(,10042) prompting procedure:
+../tar_texi/tar.texi(,10043)
+../tar_texi/tar.texi(,10044) @table @option
+../tar_texi/tar.texi(,10045) @item address@hidden
+../tar_texi/tar.texi(,10046) @itemx address@hidden
+../tar_texi/tar.texi(,10047) @itemx -F @var{script-name}
+../tar_texi/tar.texi(,10048) Specify the full name of the volume script to
use. The script can be
+../tar_texi/tar.texi(,10049) used to eject cassettes, or to broadcast messages
such as
+../tar_texi/tar.texi(,10050) @samp{Someone please come change my tape} when
performing unattended
+../tar_texi/tar.texi(,10051) backups.
+../tar_texi/tar.texi(,10052) @end table
+../tar_texi/tar.texi(,10053)
+../tar_texi/tar.texi(,10054) The @var{script-name} is executed without any
command line
+../tar_texi/tar.texi(,10055) arguments. It inherits @command{tar}'s shell
environment.
+../tar_texi/tar.texi(,10056) Additional data is passed to it via the following
+../tar_texi/tar.texi(,10057) environment variables:
+../tar_texi/tar.texi(,10058)
+../tar_texi/tar.texi(,10059) @table @env
+../tar_texi/tar.texi(,10060) @vrindex TAR_VERSION, info script environment
variable
+../tar_texi/tar.texi(,10061) @item TAR_VERSION
+../tar_texi/tar.texi(GNUTAR,10062) @acronym{GNU} @command{tar} version number.
+../tar_texi/tar.texi(,10063)
+../tar_texi/tar.texi(,10064) @vrindex TAR_ARCHIVE, info script environment
variable
+../tar_texi/tar.texi(,10065) @item TAR_ARCHIVE
+../tar_texi/tar.texi(,10066) The name of the archive @command{tar} is
processing.
+../tar_texi/tar.texi(,10067)
+../tar_texi/tar.texi(,10068) @vrindex TAR_VOLUME, info script environment
variable
+../tar_texi/tar.texi(,10069) @item TAR_VOLUME
+../tar_texi/tar.texi(,10070) Ordinal number of the volume @command{tar} is
about to start.
+../tar_texi/tar.texi(,10071)
+../tar_texi/tar.texi(,10072) @vrindex TAR_SUBCOMMAND, info script environment
variable
+../tar_texi/tar.texi(,10073) @item TAR_SUBCOMMAND
+../tar_texi/tar.texi(,10074) Short option describing the operation
@command{tar} is executing
+../tar_texi/tar.texi(,10075) @xref{Operations}, for a complete list of
subcommand options.
+../tar_texi/tar.texi(,10076)
+../tar_texi/tar.texi(,10077) @vrindex TAR_FORMAT, info script environment
variable
+../tar_texi/tar.texi(,10078) @item TAR_FORMAT
+../tar_texi/tar.texi(,10079) Format of the archive being processed.
@xref{Formats}, for a complete
+../tar_texi/tar.texi(,10080) list of archive format names.
+../tar_texi/tar.texi(,10081) @end table
+../tar_texi/tar.texi(,10082)
+../tar_texi/tar.texi(,10083) The volume script can instruct @command{tar} to
use new archive name,
+../tar_texi/tar.texi(,10084) by writing in to file descriptor 3 (see below for
an example).
+../tar_texi/tar.texi(,10085)
+../tar_texi/tar.texi(,10086) If the info script fails, @command{tar} exits;
otherwise, it begins
+../tar_texi/tar.texi(,10087) writing the next volume.
+../tar_texi/tar.texi(,10088)
+../tar_texi/tar.texi(,10089) If you want @command{tar} to cycle through a
series of files or tape
+../tar_texi/tar.texi(,10090) drives, there are three approaches to choose
from. First of all, you
+../tar_texi/tar.texi(,10091) can give @command{tar} multiple @option{--file}
options. In this case
+../tar_texi/tar.texi(,10092) the specified files will be used, in sequence, as
the successive
+../tar_texi/tar.texi(,10093) volumes of the archive. Only when the first one
in the sequence needs
+../tar_texi/tar.texi(,10094) to be used again will @command{tar} prompt for a
tape change (or run
+../tar_texi/tar.texi(,10095) the info script). For example, suppose someone
has two tape drives on
+../tar_texi/tar.texi(,10096) a system named @file{/dev/tape0} and
@file{/dev/tape1}. For having
+../tar_texi/tar.texi(GNUTAR,10097) @acronym{GNU} @command{tar} to switch to
the second drive when it needs to write the
+../tar_texi/tar.texi(,10098) second tape, and then back to the first tape,
etc., just do either of:
+../tar_texi/tar.texi(,10099)
+../tar_texi/tar.texi(,10100) @smallexample
+../tar_texi/tar.texi(,10101) $ @kbd{tar --create --multi-volume
--file=/dev/tape0 --file=/dev/tape1 @var{files}}
+../tar_texi/tar.texi(,10102) $ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
+../tar_texi/tar.texi(,10103) @end smallexample
+../tar_texi/tar.texi(,10104)
+../tar_texi/tar.texi(,10105) The second method is to use the @samp{n} response
to the tape-change
+../tar_texi/tar.texi(,10106) prompt.
+../tar_texi/tar.texi(,10107)
+../tar_texi/tar.texi(,10108) Finally, the most flexible approach is to use a
volume script, that
+../tar_texi/tar.texi(,10109) writes new archive name to the file descriptor
#3. For example, the
+../tar_texi/tar.texi(,10110) following volume script will create a series of
archive files, named
+../tar_texi/tar.texi(,10111) @address@hidden@var{vol}}, where @var{archive} is
the name of the
+../tar_texi/tar.texi(,10112) archive being created (as given by
@option{--file} option) and
+../tar_texi/tar.texi(,10113) @var{vol} is the ordinal number of the archive
being created:
+../tar_texi/tar.texi(,10114)
+../tar_texi/tar.texi(,10115) @smallexample
+../tar_texi/tar.texi(,10116) @group
+../tar_texi/tar.texi(,10117) #! /bin/sh
+../tar_texi/tar.texi(,10118) echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+../tar_texi/tar.texi(,10119)
+../tar_texi/tar.texi(,10120) name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+../tar_texi/tar.texi(,10121) case $TAR_SUBCOMMAND in
+../tar_texi/tar.texi(,10122) -c) ;;
+../tar_texi/tar.texi(,10123) -d|-x|-t) test -r address@hidden:address@hidden
|| exit 1
+../tar_texi/tar.texi(,10124) ;;
+../tar_texi/tar.texi(,10125) *) exit 1
+../tar_texi/tar.texi(,10126) esac
+../tar_texi/tar.texi(,10127)
+../tar_texi/tar.texi(,10128) echo address@hidden:address@hidden >&3
+../tar_texi/tar.texi(,10129) @end group
+../tar_texi/tar.texi(,10130) @end smallexample
+../tar_texi/tar.texi(,10131)
+../tar_texi/tar.texi(,10132) The same script cant be used while listing,
comparing or extracting
+../tar_texi/tar.texi(,10133) from the created archive. For example:
+../tar_texi/tar.texi(,10134)
+../tar_texi/tar.texi(,10135) @smallexample
+../tar_texi/tar.texi(,10136) @group
+../tar_texi/tar.texi(,10137) # @r{Create a multi-volume archive:}
+../tar_texi/tar.texi(,10138) $ @kbd{tar -c -L1024 -f archive.tar -F new-volume
.}
+../tar_texi/tar.texi(,10139) # @r{Extract from the created archive:}
+../tar_texi/tar.texi(,10140) $ @kbd{tar -x -f archive.tar -F new-volume .}
+../tar_texi/tar.texi(,10141) @end group
+../tar_texi/tar.texi(,10142) @end smallexample
+../tar_texi/tar.texi(,10143)
+../tar_texi/tar.texi(,10144) @noindent
+../tar_texi/tar.texi(,10145) Notice, that the first command had to use
@option{-L} option, since
+../tar_texi/tar.texi(GNUTAR,10146) otherwise @acronym{GNU} @command{tar} will
end up writing everything to file
+../tar_texi/tar.texi(,10147) @file{archive.tar}.
+../tar_texi/tar.texi(,10148)
+../tar_texi/tar.texi(,10149) You can read each individual volume of a
multi-volume archive as if it
+../tar_texi/tar.texi(,10150) were an archive by itself. For example, to list
the contents of one
+../tar_texi/tar.texi(,10151) volume, use @option{--list}, without
@option{--multi-volume} specified.
+../tar_texi/tar.texi(,10152) To extract an archive member from one volume
(assuming it is described
+../tar_texi/tar.texi(,10153) that volume), use @option{--extract}, again
without
+../tar_texi/tar.texi(,10154) @option{--multi-volume}.
+../tar_texi/tar.texi(,10155)
+../tar_texi/tar.texi(,10156) If an archive member is split across volumes
(i.e. its entry begins on
+../tar_texi/tar.texi(,10157) one volume of the media and ends on another), you
need to specify
+../tar_texi/tar.texi(,10158) @option{--multi-volume} to extract it
successfully. In this case, you
+../tar_texi/tar.texi(,10159) should load the volume where the archive member
starts, and use
+../tar_texi/tar.texi(,10160) @samp{tar --extract address@hidden will prompt
for later
+../tar_texi/tar.texi(,10161) volumes as it needs them. @xref{extracting
archives}, for more
+../tar_texi/tar.texi(,10162) information about extracting archives.
+../tar_texi/tar.texi(,10163)
+../tar_texi/tar.texi(,10164) Multi-volume archives can be modified like any
other archive. To add
+../tar_texi/tar.texi(,10165) files to a multi-volume archive, you need to only
mount the last
+../tar_texi/tar.texi(,10166) volume of the archive media (and new volumes, if
needed). For all
+../tar_texi/tar.texi(,10167) other operations, you need to use the entire
archive.
+../tar_texi/tar.texi(,10168)
+../tar_texi/tar.texi(,10169) If a multi-volume archive was labeled using
+../tar_texi/tar.texi(,10170) @address@hidden (@pxref{label}) when it was
+../tar_texi/tar.texi(,10171) created, @command{tar} will not automatically
label volumes which are
+../tar_texi/tar.texi(,10172) added later. To label subsequent volumes, specify
+../tar_texi/tar.texi(,10173) @address@hidden again in conjunction with the
+../tar_texi/tar.texi(,10174) @option{--append}, @option{--update} or
@option{--concatenate} operation.
+../tar_texi/tar.texi(,10175)
+../tar_texi/tar.texi(,10176) Notice that multi-volume support is a GNU
extension and the archives
+../tar_texi/tar.texi(GNUTAR,10177) created in this mode should be read only
using @acronym{GNU} @command{tar}. If you
+../tar_texi/tar.texi(,10178) absolutely have to process such archives using a
third-party @command{tar}
+../tar_texi/tar.texi(,10179) implementation, read @ref{Split Recovery}.
+../tar_texi/tar.texi(,10180)
+../tar_texi/tar.texi(,10181) @node Tape Files
+../tar_texi/tar.texi(,10182) @subsection Tape Files
+../tar_texi/tar.texi(UNREVISED,10183) @quotation
+../tar_texi/tar.texi(UNREVISED,10183) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,10183) @end quotation
+../tar_texi/tar.texi(UNREVISED,10183)
+../tar_texi/tar.texi(,10184)
+../tar_texi/tar.texi(,10185) To give the archive a name which will be recorded
in it, use the
+../tar_texi/tar.texi(,10186) @address@hidden (@option{-V @var{volume-label}})
+../tar_texi/tar.texi(,10187) option. This will write a special block
identifying
+../tar_texi/tar.texi(,10188) @var{volume-label} as the name of the archive to
the front of the
+../tar_texi/tar.texi(,10189) archive which will be displayed when the archive
is listed with
+../tar_texi/tar.texi(,10190) @option{--list}. If you are creating a
multi-volume archive with
+../tar_texi/tar.texi(,10191) @option{--multi-volume} (@pxref{Using Multiple
Tapes}), then the
+../tar_texi/tar.texi(,10192) volume label will have @samp{Volume @var{nnn}}
appended to the name
+../tar_texi/tar.texi(,10193) you give, where @var{nnn} is the number of the
volume of the archive.
+../tar_texi/tar.texi(,10194) (If you use the @address@hidden) option when
+../tar_texi/tar.texi(,10195) reading an archive, it checks to make sure the
label on the tape
+../tar_texi/tar.texi(,10196) matches the one you give. @xref{label}.
+../tar_texi/tar.texi(,10197)
+../tar_texi/tar.texi(,10198) When @command{tar} writes an archive to tape, it
creates a single
+../tar_texi/tar.texi(,10199) tape file. If multiple archives are written to
the same tape, one
+../tar_texi/tar.texi(,10200) after the other, they each get written as
separate tape files. When
+../tar_texi/tar.texi(,10201) extracting, it is necessary to position the tape
at the right place
+../tar_texi/tar.texi(,10202) before running @command{tar}. To do this, use
the @command{mt} command.
+../tar_texi/tar.texi(,10203) For more information on the @command{mt} command
and on the organization
+../tar_texi/tar.texi(,10204) of tapes into a sequence of tape files, see
@ref{mt}.
+../tar_texi/tar.texi(,10205)
+../tar_texi/tar.texi(,10206) People seem to often do:
+../tar_texi/tar.texi(,10207)
+../tar_texi/tar.texi(,10208) @smallexample
+../tar_texi/tar.texi(,10209) @kbd{--label="@var{some-prefix} `date
address@hidden"}
+../tar_texi/tar.texi(,10210) @end smallexample
+../tar_texi/tar.texi(,10211)
+../tar_texi/tar.texi(,10212) or such, for pushing a common date in all volumes
or an archive set.
+../tar_texi/tar.texi(,10213)
+../tar_texi/tar.texi(,10214) @node Tarcat
+../tar_texi/tar.texi(,10215) @subsection Concatenate Volumes into a Single
Archive
+../tar_texi/tar.texi(,10216)
+../tar_texi/tar.texi(,10217) @pindex tarcat
+../tar_texi/tar.texi(GNUTAR,10218) Sometimes it is necessary to convert
existing @acronym{GNU} @command{tar} multi-volume
+../tar_texi/tar.texi(,10219) archive to a single @command{tar} archive.
Simply concatenating all
+../tar_texi/tar.texi(,10220) volumes into one will not work, since each volume
carries an additional
+../tar_texi/tar.texi(GNUTAR,10221) information at the beginning.
@acronym{GNU} @command{tar} is shipped with the shell
+../tar_texi/tar.texi(,10222) script @command{tarcat} designed for this purpose.
+../tar_texi/tar.texi(,10223)
+../tar_texi/tar.texi(,10224) The script takes a list of files comprising a
multi-volume archive
+../tar_texi/tar.texi(,10225) and creates the resulting archive at the standard
output. For example:
+../tar_texi/tar.texi(,10226)
+../tar_texi/tar.texi(,10227) @smallexample
+../tar_texi/tar.texi(,10228) @kbd{tarcat vol.1 vol.2 vol.3 | tar tf -}
+../tar_texi/tar.texi(,10229) @end smallexample
+../tar_texi/tar.texi(,10230)
+../tar_texi/tar.texi(,10231) The script implements a simple heuristics to
determine the format of
+../tar_texi/tar.texi(,10232) the first volume file and to decide how to
process the rest of the
+../tar_texi/tar.texi(,10233) files. However, it makes no attempt to verify
whether the files are
+../tar_texi/tar.texi(,10234) given in order or even if they are valid
@command{tar} archives.
+../tar_texi/tar.texi(,10235) It uses @command{dd} and does not filter its
standard error, so you
+../tar_texi/tar.texi(,10236) will usually see lots of spurious messages.
+../tar_texi/tar.texi(,10237)
+../tar_texi/tar.texi(FIXME,10238) @allow-recursion
+../tar_texi/tar.texi(FIXME,10238) @quote-arg
+../tar_texi/tar.texi(FIXME,10238)
+../tar_texi/tar.texi(,10239)
+../tar_texi/tar.texi(,10240) @node label
+../tar_texi/tar.texi(,10241) @section Including a Label in the Archive
+../tar_texi/tar.texi(,10242) @cindex Labeling an archive
+../tar_texi/tar.texi(,10243) @cindex Labels on the archive media
+../tar_texi/tar.texi(,10244) @cindex Labeling multi-volume archives
+../tar_texi/tar.texi(UNREVISED,10245) @quotation
+../tar_texi/tar.texi(UNREVISED,10245) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,10245) @end quotation
+../tar_texi/tar.texi(UNREVISED,10245)
+../tar_texi/tar.texi(,10246)
+../tar_texi/tar.texi(,10247) @opindex label
+../tar_texi/tar.texi(,10248) To avoid problems caused by misplaced paper
labels on the archive
+../tar_texi/tar.texi(,10249) media, you can include a @dfn{label} entry---an
archive member which
+../tar_texi/tar.texi(,10250) contains the name of the archive---in the archive
itself. Use the
+../tar_texi/tar.texi(,10251) @address@hidden (@option{-V @var{archive-label}})
+../tar_texi/tar.texi(,10252) option in conjunction with the @option{--create}
operation to include
+../tar_texi/tar.texi(,10253) a label entry in the archive as it is being
created.
+../tar_texi/tar.texi(,10254)
+../tar_texi/tar.texi(,10255) @table @option
+../tar_texi/tar.texi(,10256) @item address@hidden
+../tar_texi/tar.texi(,10257) @itemx -V @var{archive-label}
+../tar_texi/tar.texi(,10258) Includes an @dfn{archive-label} at the beginning
of the archive when
+../tar_texi/tar.texi(,10259) the archive is being created, when used in
conjunction with the
+../tar_texi/tar.texi(,10260) @option{--create} operation. Checks to make sure
the archive label
+../tar_texi/tar.texi(,10261) matches the one specified (when used in
conjunction with any other
+../tar_texi/tar.texi(,10262) operation.
+../tar_texi/tar.texi(,10263) @end table
+../tar_texi/tar.texi(,10264)
+../tar_texi/tar.texi(,10265) If you create an archive using both
+../tar_texi/tar.texi(,10266) @address@hidden (@option{-V @var{archive-label}})
+../tar_texi/tar.texi(,10267) and @option{--multi-volume} (@option{-M}), each
volume of the archive
+../tar_texi/tar.texi(,10268) will have an archive label of the form
@address@hidden
+../tar_texi/tar.texi(,10269) Volume @var{n}}, where @var{n} is 1 for the first
volume, 2 for the
+../tar_texi/tar.texi(,10270) next, and so on. @xref{Using Multiple Tapes}, for
information on
+../tar_texi/tar.texi(,10271) creating multiple volume archives.
+../tar_texi/tar.texi(,10272)
+../tar_texi/tar.texi(,10273) @cindex Volume label, listing
+../tar_texi/tar.texi(,10274) @cindex Listing volume label
+../tar_texi/tar.texi(,10275) The volume label will be displayed by
@option{--list} along with
+../tar_texi/tar.texi(,10276) the file contents. If verbose display is
requested, it will also be
+../tar_texi/tar.texi(,10277) explicitely marked as in the example below:
+../tar_texi/tar.texi(,10278)
+../tar_texi/tar.texi(,10279) @smallexample
+../tar_texi/tar.texi(,10280) @group
+../tar_texi/tar.texi(,10281) $ @kbd{tar --verbose --list --file=iamanarchive}
+../tar_texi/tar.texi(,10282) V--------- 0 0 0 1992-03-07 12:01
iamalabel--Volume Header--
+../tar_texi/tar.texi(,10283) -rw-r--r-- ringo user 40 1990-05-21 13:30
iamafilename
+../tar_texi/tar.texi(,10284) @end group
+../tar_texi/tar.texi(,10285) @end smallexample
+../tar_texi/tar.texi(,10286)
+../tar_texi/tar.texi(,10287) @opindex test-label
+../tar_texi/tar.texi(,10288) @anchor{--test-label option}
+../tar_texi/tar.texi(,10289) However, @option{--list} option will cause
listing entire
+../tar_texi/tar.texi(,10290) contents of the archive, which may be undesirable
(for example, if the
+../tar_texi/tar.texi(,10291) archive is stored on a tape). You can request
checking only the volume
+../tar_texi/tar.texi(,10292) by specifying @option{--test-label} option. This
option reads only the
+../tar_texi/tar.texi(,10293) first block of an archive, so it can be used with
slow storage
+../tar_texi/tar.texi(,10294) devices. For example:
+../tar_texi/tar.texi(,10295)
+../tar_texi/tar.texi(,10296) @smallexample
+../tar_texi/tar.texi(,10297) @group
+../tar_texi/tar.texi(,10298) $ @kbd{tar --test-label --file=iamanarchive}
+../tar_texi/tar.texi(,10299) iamalabel
+../tar_texi/tar.texi(,10300) @end group
+../tar_texi/tar.texi(,10301) @end smallexample
+../tar_texi/tar.texi(,10302)
+../tar_texi/tar.texi(,10303) If @option{--test-label} is used with a single
command line
+../tar_texi/tar.texi(,10304) argument, @command{tar} compares the volume label
with the
+../tar_texi/tar.texi(,10305) argument. It exits with code 0 if the two
strings match, and with code
+../tar_texi/tar.texi(,10306) 2 otherwise. In this case no output is
displayed. For example:
+../tar_texi/tar.texi(,10307)
+../tar_texi/tar.texi(,10308) @smallexample
+../tar_texi/tar.texi(,10309) @group
+../tar_texi/tar.texi(,10310) $ @kbd{tar --test-label --file=iamanarchive
'iamalable'}
+../tar_texi/tar.texi(,10311) @result{} 0
+../tar_texi/tar.texi(,10312) $ @kbd{tar --test-label --file=iamanarchive
'iamalable' alabel}
+../tar_texi/tar.texi(,10313) @result{} 1
+../tar_texi/tar.texi(,10314) @end group
+../tar_texi/tar.texi(,10315) @end smallexample
+../tar_texi/tar.texi(,10316)
+../tar_texi/tar.texi(,10317) If you request any operation, other than
@option{--create}, along
+../tar_texi/tar.texi(,10318) with using @option{--label} option, @command{tar}
will first check if
+../tar_texi/tar.texi(,10319) the archive label matches the one specified and
will refuse to proceed
+../tar_texi/tar.texi(,10320) if it does not. Use this as a safety precaution
to avoid accidentally
+../tar_texi/tar.texi(,10321) overwriting existing archives. For example, if
you wish to add files
+../tar_texi/tar.texi(,10322) to @file{archive}, presumably labelled with
string @samp{My volume},
+../tar_texi/tar.texi(,10323) you will get:
+../tar_texi/tar.texi(,10324)
+../tar_texi/tar.texi(,10325) @smallexample
+../tar_texi/tar.texi(,10326) @group
+../tar_texi/tar.texi(,10327) $ @kbd{tar -rf archive --label 'My volume' .}
+../tar_texi/tar.texi(,10328) tar: Archive not labeled to match `My volume'
+../tar_texi/tar.texi(,10329) @end group
+../tar_texi/tar.texi(,10330) @end smallexample
+../tar_texi/tar.texi(,10331)
+../tar_texi/tar.texi(,10332) @noindent
+../tar_texi/tar.texi(,10333) in case its label does not match. This will work
even if
+../tar_texi/tar.texi(,10334) @file{archive} is not labelled at all.
+../tar_texi/tar.texi(,10335)
+../tar_texi/tar.texi(,10336) Similarly, @command{tar} will refuse to list or
extract the
+../tar_texi/tar.texi(,10337) archive if its label doesn't match the
@var{archive-label}
+../tar_texi/tar.texi(,10338) specified. In those cases, @var{archive-label}
argument is interpreted
+../tar_texi/tar.texi(,10339) as a globbing-style pattern which must match the
actual magnetic
+../tar_texi/tar.texi(,10340) volume label. @xref{exclude}, for a precise
description of how match
+../tar_texi/tar.texi(,10341) is address@hidden versions of @command{tar} used
full
+../tar_texi/tar.texi(,10342) regular expression matching, or before that, only
exact string
+../tar_texi/tar.texi(,10343) matching, instead of wildcard matchers. We
decided for the sake of
+../tar_texi/tar.texi(,10344) simplicity to use a uniform matching device
through
+../tar_texi/tar.texi(,10345) @command{tar}.}. If the switch
@option{--multi-volume} (@option{-M}) is being used,
+../tar_texi/tar.texi(,10346) the volume label matcher will also suffix
@var{archive-label} by
+../tar_texi/tar.texi(,10347) @address@hidden Volume [1-9]*}} if the initial
match fails, before giving
+../tar_texi/tar.texi(,10348) up. Since the volume numbering is automatically
added in labels at
+../tar_texi/tar.texi(,10349) creation time, it sounded logical to equally help
the user taking care
+../tar_texi/tar.texi(,10350) of it when the archive is being read.
+../tar_texi/tar.texi(,10351)
+../tar_texi/tar.texi(,10352) The @option{--label} was once called
@option{--volume}, but is not
+../tar_texi/tar.texi(,10353) available under that name anymore.
+../tar_texi/tar.texi(,10354)
+../tar_texi/tar.texi(,10355) You can also use @option{--label} to get a
common information on
+../tar_texi/tar.texi(,10356) all tapes of a series. For having this
information different in each
+../tar_texi/tar.texi(,10357) series created through a single script used on a
regular basis, just
+../tar_texi/tar.texi(,10358) manage to get some date string as part of the
label. For example:
+../tar_texi/tar.texi(,10359)
+../tar_texi/tar.texi(,10360) @smallexample
+../tar_texi/tar.texi(,10361) @group
+../tar_texi/tar.texi(,10362) $ @kbd{tar cfMV /dev/tape "Daily backup for `date
+%Y-%m-%d`"}
+../tar_texi/tar.texi(,10363) $ @kbd{tar --create --file=/dev/tape
--multi-volume \
+../tar_texi/tar.texi(,10364) --volume="Daily backup for `date +%Y-%m-%d`"}
+../tar_texi/tar.texi(,10365) @end group
+../tar_texi/tar.texi(,10366) @end smallexample
+../tar_texi/tar.texi(,10367)
+../tar_texi/tar.texi(,10368) Also note that each label has its own date and
time, which corresponds
+../tar_texi/tar.texi(GNUTAR,10369) to when @acronym{GNU} @command{tar}
initially attempted to write it,
+../tar_texi/tar.texi(,10370) often soon after the operator launches
@command{tar} or types the
+../tar_texi/tar.texi(,10371) carriage return telling that the next tape is
ready. Comparing date
+../tar_texi/tar.texi(,10372) labels does give an idea of tape throughput only
if the delays for
+../tar_texi/tar.texi(,10373) rewinding tapes and the operator switching them
were negligible, which
+../tar_texi/tar.texi(,10374) is usually not the case.
+../tar_texi/tar.texi(,10375)
+../tar_texi/tar.texi(,10376) @node verify
+../tar_texi/tar.texi(,10377) @section Verifying Data as It is Stored
+../tar_texi/tar.texi(,10378) @cindex Verifying a write operation
+../tar_texi/tar.texi(,10379) @cindex Double-checking a write operation
+../tar_texi/tar.texi(,10380)
+../tar_texi/tar.texi(,10381) @table @option
+../tar_texi/tar.texi(,10382) @item -W
+../tar_texi/tar.texi(,10383) @itemx --verify
+../tar_texi/tar.texi(,10384) @opindex verify, short description
+../tar_texi/tar.texi(,10385) Attempt to verify the archive after writing.
+../tar_texi/tar.texi(,10386) @end table
+../tar_texi/tar.texi(,10387)
+../tar_texi/tar.texi(,10388) This option causes @command{tar} to verify the
archive after writing it.
+../tar_texi/tar.texi(,10389) Each volume is checked after it is written, and
any discrepancies
+../tar_texi/tar.texi(,10390) are recorded on the standard error output.
+../tar_texi/tar.texi(,10391)
+../tar_texi/tar.texi(,10392) Verification requires that the archive be on a
back-space-able medium.
+../tar_texi/tar.texi(,10393) This means pipes, some cartridge tape drives, and
some other devices
+../tar_texi/tar.texi(,10394) cannot be verified.
+../tar_texi/tar.texi(,10395)
+../tar_texi/tar.texi(,10396) You can insure the accuracy of an archive by
comparing files in the
+../tar_texi/tar.texi(,10397) system with archive members. @command{tar} can
compare an archive to the
+../tar_texi/tar.texi(,10398) file system as the archive is being written, to
verify a write
+../tar_texi/tar.texi(,10399) operation, or can compare a previously written
archive, to insure that
+../tar_texi/tar.texi(,10400) it is up to date.
+../tar_texi/tar.texi(,10401)
+../tar_texi/tar.texi(xopindex,10402) @opindex address@hidden, using with
@option{--create}}
+../tar_texi/tar.texi(xopindex,10403) @opindex address@hidden, using with
@option{--verify}}
+../tar_texi/tar.texi(,10404) To check for discrepancies in an archive
immediately after it is
+../tar_texi/tar.texi(,10405) written, use the @option{--verify} (@option{-W})
option in conjunction with
+../tar_texi/tar.texi(,10406) the @option{--create} operation. When this
option is
+../tar_texi/tar.texi(,10407) specified, @command{tar} checks archive members
against their counterparts
+../tar_texi/tar.texi(,10408) in the file system, and reports discrepancies on
the standard error.
+../tar_texi/tar.texi(,10409)
+../tar_texi/tar.texi(,10410) To verify an archive, you must be able to read it
from before the end
+../tar_texi/tar.texi(,10411) of the last written entry. This option is useful
for detecting data
+../tar_texi/tar.texi(,10412) errors on some tapes. Archives written to pipes,
some cartridge tape
+../tar_texi/tar.texi(,10413) drives, and some other devices cannot be verified.
+../tar_texi/tar.texi(,10414)
+../tar_texi/tar.texi(,10415) One can explicitly compare an already made
archive with the file
+../tar_texi/tar.texi(,10416) system by using the @option{--compare}
(@option{--diff}, @option{-d})
+../tar_texi/tar.texi(,10417) option, instead of using the more automatic
@option{--verify} option.
+../tar_texi/tar.texi(,10418) @xref{compare}.
+../tar_texi/tar.texi(,10419)
+../tar_texi/tar.texi(,10420) Note that these two options have a slightly
different intent. The
+../tar_texi/tar.texi(,10421) @option{--compare} option checks how identical
are the logical contents of some
+../tar_texi/tar.texi(,10422) archive with what is on your disks, while the
@option{--verify} option is
+../tar_texi/tar.texi(,10423) really for checking if the physical contents
agree and if the recording
+../tar_texi/tar.texi(,10424) media itself is of dependable quality. So, for
the @option{--verify}
+../tar_texi/tar.texi(,10425) operation, @command{tar} tries to defeat all
in-memory cache pertaining to
+../tar_texi/tar.texi(,10426) the archive, while it lets the speed optimization
undisturbed for the
+../tar_texi/tar.texi(,10427) @option{--compare} option. If you nevertheless
use @option{--compare} for
+../tar_texi/tar.texi(,10428) media verification, you may have to defeat the
in-memory cache yourself,
+../tar_texi/tar.texi(,10429) maybe by opening and reclosing the door latch of
your recording unit,
+../tar_texi/tar.texi(,10430) forcing some doubt in your operating system about
the fact this is really
+../tar_texi/tar.texi(,10431) the same volume as the one just written or read.
+../tar_texi/tar.texi(,10432)
+../tar_texi/tar.texi(,10433) The @option{--verify} option would not be
necessary if drivers were indeed
+../tar_texi/tar.texi(,10434) able to detect dependably all write failures.
This sometimes require many
+../tar_texi/tar.texi(,10435) magnetic heads, some able to read after the
writes occurred. One would
+../tar_texi/tar.texi(,10436) not say that drivers unable to detect all cases
are necessarily flawed,
+../tar_texi/tar.texi(,10437) as long as programming is concerned.
+../tar_texi/tar.texi(,10438)
+../tar_texi/tar.texi(,10439) The @option{--verify} (@option{-W}) option will
not work in
+../tar_texi/tar.texi(,10440) conjunction with the @option{--multi-volume}
(@option{-M}) option or
+../tar_texi/tar.texi(,10441) the @option{--append} (@option{-r}),
@option{--update} (@option{-u})
+../tar_texi/tar.texi(,10442) and @option{--delete} operations.
@xref{Operations}, for more
+../tar_texi/tar.texi(,10443) information on these operations.
+../tar_texi/tar.texi(,10444)
+../tar_texi/tar.texi(,10445) Also, since @command{tar} normally strips leading
@samp{/} from file
+../tar_texi/tar.texi(,10446) names (@pxref{absolute}), a command like
@samp{tar --verify -cf
+../tar_texi/tar.texi(,10447) /tmp/foo.tar /etc} will work as desired only if
the working directory is
+../tar_texi/tar.texi(,10448) @file{/}, as @command{tar} uses the archive's
relative member names
+../tar_texi/tar.texi(,10449) (e.g., @file{etc/motd}) when verifying the
archive.
+../tar_texi/tar.texi(,10450)
+../tar_texi/tar.texi(,10451) @node Write Protection
+../tar_texi/tar.texi(,10452) @section Write Protection
+../tar_texi/tar.texi(,10453)
+../tar_texi/tar.texi(,10454) Almost all tapes and diskettes, and in a few rare
cases, even disks can
+../tar_texi/tar.texi(,10455) be @dfn{write protected}, to protect data on them
from being changed.
+../tar_texi/tar.texi(,10456) Once an archive is written, you should write
protect the media to prevent
+../tar_texi/tar.texi(,10457) the archive from being accidentally overwritten
or deleted. (This will
+../tar_texi/tar.texi(,10458) protect the archive from being changed with a
tape or floppy drive---it
+../tar_texi/tar.texi(,10459) will not protect it from magnet fields or other
physical hazards).
+../tar_texi/tar.texi(,10460)
+../tar_texi/tar.texi(,10461) The write protection device itself is usually an
integral part of the
+../tar_texi/tar.texi(,10462) physical media, and can be a two position (write
enabled/write
+../tar_texi/tar.texi(,10463) disabled) switch, a notch which can be popped out
or covered, a ring
+../tar_texi/tar.texi(,10464) which can be removed from the center of a tape
reel, or some other
+../tar_texi/tar.texi(,10465) changeable feature.
+../tar_texi/tar.texi(,10466)
+../tar_texi/tar.texi(,10467) @node Changes
+../tar_texi/tar.texi(,10468) @appendix Changes
+../tar_texi/tar.texi(,10469)
+../tar_texi/tar.texi(,10470) This appendix lists some important user-visible
changes between
+../tar_texi/tar.texi(GNUTAR,10471) version @acronym{GNU} @command{tar} 1.15.92
and previous versions. An up-to-date
+../tar_texi/tar.texi(,10472) version of this document is available at
+../tar_texi/tar.texi(,10473)
@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the
+../tar_texi/tar.texi(GNUTAR,10474) @acronym{GNU} @command{tar} documentation
page}.
+../tar_texi/tar.texi(,10475)
+../tar_texi/tar.texi(,10476) @table @asis
+../tar_texi/tar.texi(,10477) @item Use of globbing patterns when listing and
extracting.
+../tar_texi/tar.texi(,10478)
+../tar_texi/tar.texi(,10479) Previous versions of GNU tar assumed shell-style
globbing when
+../tar_texi/tar.texi(,10480) extracting from or listing an archive. For
example:
+../tar_texi/tar.texi(,10481)
+../tar_texi/tar.texi(,10482) @smallexample
+../tar_texi/tar.texi(,10483) $ @kbd{tar xf foo.tar '*.c'}
+../tar_texi/tar.texi(,10484) @end smallexample
+../tar_texi/tar.texi(,10485)
+../tar_texi/tar.texi(,10486) would extract all files whose names end in
@samp{.c}. This behavior
+../tar_texi/tar.texi(,10487) was not documented and was incompatible with
traditional tar
+../tar_texi/tar.texi(,10488) implementations. Therefore, starting from
version 1.15.91, GNU tar
+../tar_texi/tar.texi(,10489) no longer uses globbing by default. For example,
the above invocation
+../tar_texi/tar.texi(,10490) is now interpreted as a request to extract from
the archive the file
+../tar_texi/tar.texi(,10491) named @file{*.c}.
+../tar_texi/tar.texi(,10492)
+../tar_texi/tar.texi(,10493) To facilitate transition to the new behavior for
those users who got
+../tar_texi/tar.texi(,10494) used to the previous incorrect one, @command{tar}
will print a warning
+../tar_texi/tar.texi(,10495) if it finds out that a requested member was not
found in the archive
+../tar_texi/tar.texi(,10496) and its name looks like a globbing pattern. For
example:
+../tar_texi/tar.texi(,10497)
+../tar_texi/tar.texi(,10498) @smallexample
+../tar_texi/tar.texi(,10499) $ @kbd{tar xf foo.tar '*.c'}
+../tar_texi/tar.texi(,10500) tar: Pattern matching characters used in file
names. Please,
+../tar_texi/tar.texi(,10501) tar: use --wildcards to enable pattern matching,
or --no-wildcards to
+../tar_texi/tar.texi(,10502) tar: suppress this warning.
+../tar_texi/tar.texi(,10503) tar: *.c: Not found in archive
+../tar_texi/tar.texi(,10504) tar: Error exit delayed from previous errors
+../tar_texi/tar.texi(,10505) @end smallexample
+../tar_texi/tar.texi(,10506)
+../tar_texi/tar.texi(,10507) To treat member names as globbing patterns, use
--wildcards option.
+../tar_texi/tar.texi(,10508) If you want to tar to mimic the behavior of
versions prior to 1.15.91,
+../tar_texi/tar.texi(,10509) add this option to your @env{TAR_OPTIONS}
variable.
+../tar_texi/tar.texi(,10510)
+../tar_texi/tar.texi(,10511) @xref{wildcards}, for the detailed discussion of
the use of globbing
+../tar_texi/tar.texi(GNUTAR,10512) patterns by @acronym{GNU} @command{tar}.
+../tar_texi/tar.texi(,10513)
+../tar_texi/tar.texi(,10514) @item Use of short option @option{-o}.
+../tar_texi/tar.texi(,10515)
+../tar_texi/tar.texi(GNUTAR,10516) Earlier versions of @acronym{GNU}
@command{tar} understood @option{-o} command line
+../tar_texi/tar.texi(,10517) option as a synonym for @option{--old-archive}.
+../tar_texi/tar.texi(,10518)
+../tar_texi/tar.texi(GNUTAR,10519) @acronym{GNU} @command{tar} starting from
version 1.13.90 understands this option as
+../tar_texi/tar.texi(,10520) a synonym for @option{--no-same-owner}. This is
compatible with
+../tar_texi/tar.texi(,10521) UNIX98 @command{tar} implementations.
+../tar_texi/tar.texi(,10522)
+../tar_texi/tar.texi(,10523) However, to facilitate transition, @option{-o}
option retains its
+../tar_texi/tar.texi(,10524) old semantics when it is used with one of
archive-creation commands.
+../tar_texi/tar.texi(,10525) Users are encouraged to use
@option{--format=oldgnu} instead.
+../tar_texi/tar.texi(,10526)
+../tar_texi/tar.texi(,10527) It is especially important, since versions of
@acronym{GNU} Automake
+../tar_texi/tar.texi(,10528) up to and including 1.8.4 invoke tar with this
option to produce
+../tar_texi/tar.texi(,10529) distribution tarballs. @xref{Formats,v7}, for
the detailed discussion
+../tar_texi/tar.texi(,10530) of this issue and its implications.
+../tar_texi/tar.texi(,10531)
+../tar_texi/tar.texi(FIXME,10534) @allow-recursion
+../tar_texi/tar.texi(FIXME,10534) @quote-arg
+../tar_texi/tar.texi(FIXME,10534) .
+../tar_texi/tar.texi(,10535) @xref{Options, tar-v7, Changing Automake's
Behavior,
+../tar_texi/tar.texi(,10536) automake, GNU Automake}, for a description on how
to use various
+../tar_texi/tar.texi(,10537) archive formats with @command{automake}.
+../tar_texi/tar.texi(,10538)
+../tar_texi/tar.texi(GNUTAR,10539) Future versions of @acronym{GNU}
@command{tar} will understand @option{-o} only as a
+../tar_texi/tar.texi(,10540) synonym for @option{--no-same-owner}.
+../tar_texi/tar.texi(,10541)
+../tar_texi/tar.texi(,10542) @item Use of short option @option{-l}
+../tar_texi/tar.texi(,10543)
+../tar_texi/tar.texi(GNUTAR,10544) Earlier versions of @acronym{GNU}
@command{tar} understood @option{-l} option as a
+../tar_texi/tar.texi(,10545) synonym for @option{--one-file-system}. Since
such usage contradicted
+../tar_texi/tar.texi(,10546) to UNIX98 specification and harmed compatibility
with other
+../tar_texi/tar.texi(,10547) implementation, it was declared deprecated in
version 1.14. However,
+../tar_texi/tar.texi(,10548) to facilitate transition to its new semantics, it
was supported by
+../tar_texi/tar.texi(,10549) versions 1.15 and 1.15.90. The present use of
@option{-l} as a short
+../tar_texi/tar.texi(,10550) variant of @option{--check-links} was introduced
in version 1.15.91.
+../tar_texi/tar.texi(,10551)
+../tar_texi/tar.texi(,10552) @item Use of options @option{--portability} and
@option{--old-archive}
+../tar_texi/tar.texi(,10553)
+../tar_texi/tar.texi(,10554) These options are deprecated. Please use
@option{--format=v7} instead.
+../tar_texi/tar.texi(,10555)
+../tar_texi/tar.texi(,10556) @item Use of option @option{--posix}
+../tar_texi/tar.texi(,10557)
+../tar_texi/tar.texi(,10558) This option is deprecated. Please use
@option{--format=posix} instead.
+../tar_texi/tar.texi(,10559) @end table
+../tar_texi/tar.texi(,10560)
+../tar_texi/tar.texi(,10561) @node Configuring Help Summary
+../tar_texi/tar.texi(,10562) @appendix Configuring Help Summary
+../tar_texi/tar.texi(,10563)
+../tar_texi/tar.texi(,10564) Running @kbd{tar --help} displays the short
@command{tar} option
+../tar_texi/tar.texi(,10565) summary (@pxref{help}). This summary is organised
by @dfn{groups} of
+../tar_texi/tar.texi(,10566) semantically close options. The options within
each group are printed
+../tar_texi/tar.texi(,10567) in the following order: a short option,
eventually followed by a list
+../tar_texi/tar.texi(,10568) of corresponding long option names, followed by a
short description of
+../tar_texi/tar.texi(,10569) the option. For example, here is an excerpt from
the actual @kbd{tar
+../tar_texi/tar.texi(,10570) --help} output:
+../tar_texi/tar.texi(,10571)
+../tar_texi/tar.texi(,10572) @verbatim
+../tar_texi/tar.texi(,10573) Main operation mode:
+../tar_texi/tar.texi(,10574)
+../tar_texi/tar.texi(,10575) -A, --catenate, --concatenate append tar
files to an archive
+../tar_texi/tar.texi(,10576) -c, --create create a new archive
+../tar_texi/tar.texi(,10577) -d, --diff, --compare find differences
between archive and
+../tar_texi/tar.texi(,10578) file system
+../tar_texi/tar.texi(,10579) --delete delete from the
archive
+../tar_texi/tar.texi(,10580) @end verbatim
+../tar_texi/tar.texi(,10581)
+../tar_texi/tar.texi(,10582) @vrindex ARGP_HELP_FMT, environment variable
+../tar_texi/tar.texi(,10583) The exact visual representation of the help
output is configurable via
+../tar_texi/tar.texi(,10584) @env{ARGP_HELP_FMT} environment variable. The
value of this variable
+../tar_texi/tar.texi(,10585) is a comma-separated list of @dfn{format
variable} assignments. There
+../tar_texi/tar.texi(,10586) are two kinds of format variables. An @dfn{offset
variable} keeps the
+../tar_texi/tar.texi(,10587) offset of some part of help output text from the
leftmost column on
+../tar_texi/tar.texi(,10588) the screen. A @dfn{boolean} variable is a flag
that toggles some
+../tar_texi/tar.texi(,10589) output feature on or off. Depending on the type
of the corresponding
+../tar_texi/tar.texi(,10590) variable, there are two kinds of assignments:
+../tar_texi/tar.texi(,10591)
+../tar_texi/tar.texi(,10592) @table @asis
+../tar_texi/tar.texi(,10593) @item Offset assignment
+../tar_texi/tar.texi(,10594)
+../tar_texi/tar.texi(,10595) The assignment to an offset variable has the
following syntax:
+../tar_texi/tar.texi(,10596)
+../tar_texi/tar.texi(,10597) @smallexample
+../tar_texi/tar.texi(,10598) @address@hidden
+../tar_texi/tar.texi(,10599) @end smallexample
+../tar_texi/tar.texi(,10600)
+../tar_texi/tar.texi(,10601) @noindent
+../tar_texi/tar.texi(,10602) where @var{variable} is the variable name, and
@var{value} is a
+../tar_texi/tar.texi(,10603) numeric value to be assigned to the variable.
+../tar_texi/tar.texi(,10604)
+../tar_texi/tar.texi(,10605) @item Boolean assignment
+../tar_texi/tar.texi(,10606)
+../tar_texi/tar.texi(,10607) To assign @code{true} value to a variable, simply
put this variable name. To
+../tar_texi/tar.texi(,10608) assign @code{false} value, prefix the variable
name with @samp{no-}. For
+../tar_texi/tar.texi(,10609) example:
+../tar_texi/tar.texi(,10610)
+../tar_texi/tar.texi(,10611) @smallexample
+../tar_texi/tar.texi(,10612) @group
+../tar_texi/tar.texi(,10613) # Assign @code{true} value:
+../tar_texi/tar.texi(,10614) dup-args
+../tar_texi/tar.texi(,10615) # Assign @code{false} value:
+../tar_texi/tar.texi(,10616) no-dup-args
+../tar_texi/tar.texi(,10617) @end group
+../tar_texi/tar.texi(,10618) @end smallexample
+../tar_texi/tar.texi(,10619) @end table
+../tar_texi/tar.texi(,10620)
+../tar_texi/tar.texi(,10621) Following variables are declared:
+../tar_texi/tar.texi(,10622)
+../tar_texi/tar.texi(,10623) @deftypevr {Help Output} boolean dup-args
+../tar_texi/tar.texi(,10624) If true, arguments for an option are shown with
both short and long
+../tar_texi/tar.texi(,10625) options, even when a given option has both forms,
for example:
+../tar_texi/tar.texi(,10626)
+../tar_texi/tar.texi(,10627) @smallexample
+../tar_texi/tar.texi(,10628) -f ARCHIVE, --file=ARCHIVE use archive file or
device ARCHIVE
+../tar_texi/tar.texi(,10629) @end smallexample
+../tar_texi/tar.texi(,10630)
+../tar_texi/tar.texi(,10631) If false, then if an option has both short and
long forms, the
+../tar_texi/tar.texi(,10632) argument is only shown with the long one, for
example:
+../tar_texi/tar.texi(,10633)
+../tar_texi/tar.texi(,10634) @smallexample
+../tar_texi/tar.texi(,10635) -f, --file=ARCHIVE use archive file or
device ARCHIVE
+../tar_texi/tar.texi(,10636) @end smallexample
+../tar_texi/tar.texi(,10637)
+../tar_texi/tar.texi(,10638) @noindent
+../tar_texi/tar.texi(,10639) and a message indicating that the argument is
applicable to both
+../tar_texi/tar.texi(,10640) forms is printed below the options. This message
can be disabled
+../tar_texi/tar.texi(,10641) using @code{dup-args-note} (see below).
+../tar_texi/tar.texi(,10642)
+../tar_texi/tar.texi(,10643) The default is false.
+../tar_texi/tar.texi(,10644) @end deftypevr
+../tar_texi/tar.texi(,10645)
+../tar_texi/tar.texi(,10646) @deftypevr {Help Output} boolean dup-args-note
+../tar_texi/tar.texi(,10647) If this variable is true, which is the default,
the following notice
+../tar_texi/tar.texi(,10648) is displayed at the end of the help output:
+../tar_texi/tar.texi(,10649)
+../tar_texi/tar.texi(,10650) @quotation
+../tar_texi/tar.texi(,10651) Mandatory or optional arguments to long options
are also mandatory or
+../tar_texi/tar.texi(,10652) optional for any corresponding short options.
+../tar_texi/tar.texi(,10653) @end quotation
+../tar_texi/tar.texi(,10654)
+../tar_texi/tar.texi(,10655) Setting @code{no-dup-args-note} inhibits this
message. Normally, only one of
+../tar_texi/tar.texi(,10656) variables @code{dup-args} or @code{dup-args-note}
should be set.
+../tar_texi/tar.texi(,10657) @end deftypevr
+../tar_texi/tar.texi(,10658)
+../tar_texi/tar.texi(,10659) @deftypevr {Help Output} offset short-opt-col
+../tar_texi/tar.texi(,10660) Column in which short options start. Default is 2.
+../tar_texi/tar.texi(,10661)
+../tar_texi/tar.texi(,10662) @smallexample
+../tar_texi/tar.texi(,10663) @group
+../tar_texi/tar.texi(,10664) $ @kbd{tar --help|grep ARCHIVE}
+../tar_texi/tar.texi(,10665) -f, --file=ARCHIVE use archive file or device
ARCHIVE
+../tar_texi/tar.texi(,10666) $ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar
--help|grep ARCHIVE}
+../tar_texi/tar.texi(,10667) -f, --file=ARCHIVE use archive file or
device ARCHIVE
+../tar_texi/tar.texi(,10668) @end group
+../tar_texi/tar.texi(,10669) @end smallexample
+../tar_texi/tar.texi(,10670) @end deftypevr
+../tar_texi/tar.texi(,10671)
+../tar_texi/tar.texi(,10672) @deftypevr {Help Output} offset long-opt-col
+../tar_texi/tar.texi(,10673) Column in which long options start. Default is 6.
For example:
+../tar_texi/tar.texi(,10674)
+../tar_texi/tar.texi(,10675) @smallexample
+../tar_texi/tar.texi(,10676) @group
+../tar_texi/tar.texi(,10677) $ @kbd{tar --help|grep ARCHIVE}
+../tar_texi/tar.texi(,10678) -f, --file=ARCHIVE use archive file or device
ARCHIVE
+../tar_texi/tar.texi(,10679) $ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar
--help|grep ARCHIVE}
+../tar_texi/tar.texi(,10680) -f, --file=ARCHIVE use archive file
or device ARCHIVE
+../tar_texi/tar.texi(,10681) @end group
+../tar_texi/tar.texi(,10682) @end smallexample
+../tar_texi/tar.texi(,10683) @end deftypevr
+../tar_texi/tar.texi(,10684)
+../tar_texi/tar.texi(,10685) @deftypevr {Help Output} offset doc-opt-col
+../tar_texi/tar.texi(,10686) Column in which @dfn{doc options} start. A doc
option isn't actually
+../tar_texi/tar.texi(,10687) an option, but rather an arbitrary piece of
documentation that is
+../tar_texi/tar.texi(,10688) displayed in much the same manner as the options.
For example, in
+../tar_texi/tar.texi(,10689) the description of @option{--format} option:
+../tar_texi/tar.texi(,10690)
+../tar_texi/tar.texi(,10691) @smallexample
+../tar_texi/tar.texi(,10692) @group
+../tar_texi/tar.texi(,10693) -H, --format=FORMAT create archive of
the given format.
+../tar_texi/tar.texi(,10694)
+../tar_texi/tar.texi(,10695) FORMAT is one of the following:
+../tar_texi/tar.texi(,10696)
+../tar_texi/tar.texi(,10697) gnu GNU tar 1.13.x format
+../tar_texi/tar.texi(,10698) oldgnu GNU format as per
tar <= 1.12
+../tar_texi/tar.texi(,10699) pax POSIX 1003.1-2001
(pax) format
+../tar_texi/tar.texi(,10700) posix same as pax
+../tar_texi/tar.texi(,10701) ustar POSIX 1003.1-1988
(ustar) format
+../tar_texi/tar.texi(,10702) v7 old V7 tar format
+../tar_texi/tar.texi(,10703) @end group
+../tar_texi/tar.texi(,10704) @end smallexample
+../tar_texi/tar.texi(,10705)
+../tar_texi/tar.texi(,10706) @noindent
+../tar_texi/tar.texi(,10707) the format names are doc options. Thus, if you set
+../tar_texi/tar.texi(,10708) @kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part
of the help output
+../tar_texi/tar.texi(,10709) will look as follows:
+../tar_texi/tar.texi(,10710)
+../tar_texi/tar.texi(,10711) @smallexample
+../tar_texi/tar.texi(,10712) @group
+../tar_texi/tar.texi(,10713) -H, --format=FORMAT create archive of
the given format.
+../tar_texi/tar.texi(,10714)
+../tar_texi/tar.texi(,10715) FORMAT is one of the following:
+../tar_texi/tar.texi(,10716)
+../tar_texi/tar.texi(,10717) gnu GNU tar 1.13.x
format
+../tar_texi/tar.texi(,10718) oldgnu GNU format as
per tar <= 1.12
+../tar_texi/tar.texi(,10719) pax POSIX
1003.1-2001 (pax) format
+../tar_texi/tar.texi(,10720) posix same as pax
+../tar_texi/tar.texi(,10721) ustar POSIX
1003.1-1988 (ustar) format
+../tar_texi/tar.texi(,10722) v7 old V7 tar format
+../tar_texi/tar.texi(,10723) @end group
+../tar_texi/tar.texi(,10724) @end smallexample
+../tar_texi/tar.texi(,10725) @end deftypevr
+../tar_texi/tar.texi(,10726)
+../tar_texi/tar.texi(,10727) @deftypevr {Help Output} offset opt-doc-col
+../tar_texi/tar.texi(,10728) Column in which option description starts.
Default is 29.
+../tar_texi/tar.texi(,10729)
+../tar_texi/tar.texi(,10730) @smallexample
+../tar_texi/tar.texi(,10731) @group
+../tar_texi/tar.texi(,10732) $ @kbd{tar --help|grep ARCHIVE}
+../tar_texi/tar.texi(,10733) -f, --file=ARCHIVE use archive file or
device ARCHIVE
+../tar_texi/tar.texi(,10734) $ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar
--help|grep ARCHIVE}
+../tar_texi/tar.texi(,10735) -f, --file=ARCHIVE use archive file or device
ARCHIVE
+../tar_texi/tar.texi(,10736) $ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar
--help|grep ARCHIVE}
+../tar_texi/tar.texi(,10737) -f, --file=ARCHIVE
+../tar_texi/tar.texi(,10738) use archive file or device ARCHIVE
+../tar_texi/tar.texi(,10739) @end group
+../tar_texi/tar.texi(,10740) @end smallexample
+../tar_texi/tar.texi(,10741)
+../tar_texi/tar.texi(,10742) @noindent
+../tar_texi/tar.texi(,10743) Notice, that the description starts on a separate
line if
+../tar_texi/tar.texi(,10744) @code{opt-doc-col} value is too small.
+../tar_texi/tar.texi(,10745) @end deftypevr
+../tar_texi/tar.texi(,10746)
+../tar_texi/tar.texi(,10747) @deftypevr {Help Output} offset header-col
+../tar_texi/tar.texi(,10748) Column in which @dfn{group headers} are printed.
A group header is a
+../tar_texi/tar.texi(,10749) descriptive text preceding an option group. For
example, in the
+../tar_texi/tar.texi(,10750) following text:
+../tar_texi/tar.texi(,10751)
+../tar_texi/tar.texi(,10752) @verbatim
+../tar_texi/tar.texi(,10753) Main operation mode:
+../tar_texi/tar.texi(,10754)
+../tar_texi/tar.texi(,10755) -A, --catenate, --concatenate append tar
files to
+../tar_texi/tar.texi(,10756) an archive
+../tar_texi/tar.texi(,10757) -c, --create create a new archive
+../tar_texi/tar.texi(,10758) @end verbatim
+../tar_texi/tar.texi(,10759) @noindent
+../tar_texi/tar.texi(,10760) @samp{Main operation mode:} is the group header.
+../tar_texi/tar.texi(,10761)
+../tar_texi/tar.texi(,10762) The default value is 1.
+../tar_texi/tar.texi(,10763) @end deftypevr
+../tar_texi/tar.texi(,10764)
+../tar_texi/tar.texi(,10765) @deftypevr {Help Output} offset usage-indent
+../tar_texi/tar.texi(,10766) Indentation of wrapped usage lines. Affects
@option{--usage}
+../tar_texi/tar.texi(,10767) output. Default is 12.
+../tar_texi/tar.texi(,10768) @end deftypevr
+../tar_texi/tar.texi(,10769)
+../tar_texi/tar.texi(,10770) @deftypevr {Help Output} offset rmargin
+../tar_texi/tar.texi(,10771) Right margin of the text output. Used for
wrapping.
+../tar_texi/tar.texi(,10772) @end deftypevr
+../tar_texi/tar.texi(,10773)
+../tar_texi/tar.texi(,10774) @node Tar Internals
+../tar_texi/tar.texi(,10775) @appendix Tar Internals
+../tar_texi/intern.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/intern.texi(,2) @c Copyright (C) 2006 Free Software Foundation,
Inc.
+../tar_texi/intern.texi(,3) @c This file is distributed under GFDL 1.1 or any
later version
+../tar_texi/intern.texi(,4) @c published by the Free Software Foundation.
+../tar_texi/intern.texi(,5)
+../tar_texi/intern.texi(,6) @menu
+../tar_texi/intern.texi(,7) * Standard:: Basic Tar Format
+../tar_texi/intern.texi(,8) * Extensions:: @acronym{GNU} Extensions to
the Archive Format
+../tar_texi/intern.texi(,9) * Sparse Formats:: Storing Sparse Files
+../tar_texi/intern.texi(,10) * Snapshot Files::
+../tar_texi/intern.texi(,11) * Dumpdir::
+../tar_texi/intern.texi(,12) @end menu
+../tar_texi/intern.texi(,13)
+../tar_texi/intern.texi(,14) @node Standard
+../tar_texi/intern.texi(,15) @unnumberedsec Basic Tar Format
+../tar_texi/intern.texi(UNREVISED,16) @quotation
+../tar_texi/intern.texi(UNREVISED,16) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/intern.texi(UNREVISED,16) @end quotation
+../tar_texi/intern.texi(UNREVISED,16)
+../tar_texi/intern.texi(,17)
+../tar_texi/intern.texi(,18) While an archive may contain many files, the
archive itself is a
+../tar_texi/intern.texi(,19) single ordinary file. Like any other file, an
archive file can be
+../tar_texi/intern.texi(,20) written to a storage device such as a tape or
disk, sent through a
+../tar_texi/intern.texi(,21) pipe or over a network, saved on the active file
system, or even
+../tar_texi/intern.texi(,22) stored in another archive. An archive file is
not easy to read or
+../tar_texi/intern.texi(,23) manipulate without using the @command{tar}
utility or Tar mode in
+../tar_texi/intern.texi(,24) @acronym{GNU} Emacs.
+../tar_texi/intern.texi(,25)
+../tar_texi/intern.texi(,26) Physically, an archive consists of a series of
file entries terminated
+../tar_texi/intern.texi(,27) by an end-of-archive entry, which consists of two
512 blocks of zero
+../tar_texi/intern.texi(,28) bytes. A file
+../tar_texi/intern.texi(,29) entry usually describes one of the files in the
archive (an
+../tar_texi/intern.texi(,30) @dfn{archive member}), and consists of a file
header and the contents
+../tar_texi/intern.texi(,31) of the file. File headers contain file names and
statistics, checksum
+../tar_texi/intern.texi(,32) information which @command{tar} uses to detect
file corruption, and
+../tar_texi/intern.texi(,33) information about file types.
+../tar_texi/intern.texi(,34)
+../tar_texi/intern.texi(,35) Archives are permitted to have more than one
member with the same
+../tar_texi/intern.texi(,36) member name. One way this situation can occur is
if more than one
+../tar_texi/intern.texi(,37) version of a file has been stored in the archive.
For information
+../tar_texi/intern.texi(,38) about adding new versions of a file to an
archive, see @ref{update}.
+../tar_texi/intern.texi(FIXME-xref,40) @quote-arg
+../tar_texi/intern.texi(FIXME-xref,40)
+../tar_texi/intern.texi(,41)
+../tar_texi/intern.texi(,42) In addition to entries describing archive
members, an archive may
+../tar_texi/intern.texi(,43) contain entries which @command{tar} itself uses
to store information.
+../tar_texi/intern.texi(,44) @xref{label}, for an example of such an archive
entry.
+../tar_texi/intern.texi(,45)
+../tar_texi/intern.texi(,46) A @command{tar} archive file contains a series of
blocks. Each block
+../tar_texi/intern.texi(,47) contains @code{BLOCKSIZE} bytes. Although this
format may be thought
+../tar_texi/intern.texi(,48) of as being on magnetic tape, other media are
often used.
+../tar_texi/intern.texi(,49)
+../tar_texi/intern.texi(,50) Each file archived is represented by a header
block which describes
+../tar_texi/intern.texi(,51) the file, followed by zero or more blocks which
give the contents
+../tar_texi/intern.texi(,52) of the file. At the end of the archive file
there are two 512-byte blocks
+../tar_texi/intern.texi(,53) filled with binary zeros as an end-of-file
marker. A reasonable system
+../tar_texi/intern.texi(,54) should write such end-of-file marker at the end
of an archive, but
+../tar_texi/intern.texi(,55) must not assume that such a block exists when
reading an archive. In
+../tar_texi/intern.texi(GNUTAR,56) particular @acronym{GNU} @command{tar}
always issues a warning if it does not encounter it.
+../tar_texi/intern.texi(,57)
+../tar_texi/intern.texi(,58) The blocks may be @dfn{blocked} for physical I/O
operations.
+../tar_texi/intern.texi(,59) Each record of @var{n} blocks (where @var{n} is
set by the
+../tar_texi/intern.texi(,60) @address@hidden (@option{-b @var{512-size}})
option to @command{tar}) is written with a single
+../tar_texi/intern.texi(,61) @address@hidden ()}} operation. On magnetic
tapes, the result of
+../tar_texi/intern.texi(,62) such a write is a single record. When writing an
archive,
+../tar_texi/intern.texi(,63) the last record of blocks should be written at
the full size, with
+../tar_texi/intern.texi(,64) blocks after the zero block containing all zeros.
When reading
+../tar_texi/intern.texi(,65) an archive, a reasonable system should properly
handle an archive
+../tar_texi/intern.texi(,66) whose last record is shorter than the rest, or
which contains garbage
+../tar_texi/intern.texi(,67) records after a zero block.
+../tar_texi/intern.texi(,68)
+../tar_texi/intern.texi(GNUTAR,69) The header block is defined in C as
follows. In the @acronym{GNU} @command{tar}
+../tar_texi/intern.texi(,70) distribution, this is part of file
@file{src/tar.h}:
+../tar_texi/intern.texi(,71)
+../tar_texi/intern.texi(,72) @smallexample
+../tar_texi/header.texi(,1) @comment GNU tar Archive Format description.
+../tar_texi/header.texi(,2) @comment
+../tar_texi/header.texi(,3) @comment Copyright (C) 1988, 1989, 1991, 1992,
1993, 1994, 1995, 1996, 1997,
+../tar_texi/header.texi(,4) @comment 2000, 2001, 2003, 2004, 2005, 2006 Free
Software Foundation, Inc.
+../tar_texi/header.texi(,5) @comment
+../tar_texi/header.texi(,6) @comment This program is free software; you can
redistribute it and/or modify it
+../tar_texi/header.texi(,7) @comment under the terms of the GNU General
Public License as published by the
+../tar_texi/header.texi(,8) @comment Free Software Foundation; either
version 2, or (at your option) any later
+../tar_texi/header.texi(,9) @comment version.
+../tar_texi/header.texi(,10) @comment
+../tar_texi/header.texi(,11) @comment This program is distributed in the
hope that it will be useful, but
+../tar_texi/header.texi(,12) @comment WITHOUT ANY WARRANTY; without even the
implied warranty of
+../tar_texi/header.texi(,13) @comment MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General
+../tar_texi/header.texi(,14) @comment Public License for more details.
+../tar_texi/header.texi(,15) @comment
+../tar_texi/header.texi(,16) @comment You should have received a copy of the
GNU General Public License along
+../tar_texi/header.texi(,17) @comment with this program; if not, write to
the Free Software Foundation, Inc.,
+../tar_texi/header.texi(,18) @comment 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
+../tar_texi/header.texi(,19)
+../tar_texi/header.texi(,20) /address@hidden tar Header Block, from POSIX
1003.1-1990. }*/
+../tar_texi/header.texi(,21)
+../tar_texi/header.texi(,22) /address@hidden POSIX header. }*/
+../tar_texi/header.texi(,23)
+../tar_texi/header.texi(,24) struct posix_header
+../tar_texi/header.texi(,25) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,26) char name[100]; /address@hidden
0 }*/
+../tar_texi/header.texi(,27) char mode[8]; /address@hidden
100 }*/
+../tar_texi/header.texi(,28) char uid[8]; /address@hidden
108 }*/
+../tar_texi/header.texi(,29) char gid[8]; /address@hidden
116 }*/
+../tar_texi/header.texi(,30) char size[12]; /address@hidden
124 }*/
+../tar_texi/header.texi(,31) char mtime[12]; /address@hidden
136 }*/
+../tar_texi/header.texi(,32) char chksum[8]; /address@hidden
148 }*/
+../tar_texi/header.texi(,33) char typeflag; /address@hidden
156 }*/
+../tar_texi/header.texi(,34) char linkname[100]; /address@hidden
157 }*/
+../tar_texi/header.texi(,35) char magic[6]; /address@hidden
257 }*/
+../tar_texi/header.texi(,36) char version[2]; /address@hidden
263 }*/
+../tar_texi/header.texi(,37) char uname[32]; /address@hidden
265 }*/
+../tar_texi/header.texi(,38) char gname[32]; /address@hidden
297 }*/
+../tar_texi/header.texi(,39) char devmajor[8]; /address@hidden
329 }*/
+../tar_texi/header.texi(,40) char devminor[8]; /address@hidden
337 }*/
+../tar_texi/header.texi(,41) char prefix[155]; /address@hidden
345 }*/
+../tar_texi/header.texi(,42) /address@hidden
500 }*/
+../tar_texi/header.texi(,43) @};
+../tar_texi/header.texi(,44)
+../tar_texi/header.texi(,45) #define TMAGIC "ustar" /address@hidden
ustar and a null }*/
+../tar_texi/header.texi(,46) #define TMAGLEN 6
+../tar_texi/header.texi(,47) #define TVERSION "00" /address@hidden
00 and no null }*/
+../tar_texi/header.texi(,48) #define TVERSLEN 2
+../tar_texi/header.texi(,49)
+../tar_texi/header.texi(,50) /address@hidden Values used in typeflag field.
}*/
+../tar_texi/header.texi(,51) #define REGTYPE '0' /address@hidden
regular file }*/
+../tar_texi/header.texi(,52) #define AREGTYPE '\0' /address@hidden
regular file }*/
+../tar_texi/header.texi(,53) #define LNKTYPE '1' /address@hidden
link }*/
+../tar_texi/header.texi(,54) #define SYMTYPE '2' /address@hidden
reserved }*/
+../tar_texi/header.texi(,55) #define CHRTYPE '3' /address@hidden
character special }*/
+../tar_texi/header.texi(,56) #define BLKTYPE '4' /address@hidden
block special }*/
+../tar_texi/header.texi(,57) #define DIRTYPE '5' /address@hidden
directory }*/
+../tar_texi/header.texi(,58) #define FIFOTYPE '6' /address@hidden
FIFO special }*/
+../tar_texi/header.texi(,59) #define CONTTYPE '7' /address@hidden
reserved }*/
+../tar_texi/header.texi(,60)
+../tar_texi/header.texi(,61) #define XHDTYPE 'x' /address@hidden
Extended header referring to the
+../tar_texi/header.texi(,62) next file in
the archive }*/
+../tar_texi/header.texi(,63) #define XGLTYPE 'g' /address@hidden
Global extended header }*/
+../tar_texi/header.texi(,64)
+../tar_texi/header.texi(,65) /address@hidden Bits used in the mode field,
values in octal. }*/
+../tar_texi/header.texi(,66) #define TSUID 04000 /address@hidden
set UID on execution }*/
+../tar_texi/header.texi(,67) #define TSGID 02000 /address@hidden
set GID on execution }*/
+../tar_texi/header.texi(,68) #define TSVTX 01000 /address@hidden
reserved }*/
+../tar_texi/header.texi(,69) /address@hidden
file permissions }*/
+../tar_texi/header.texi(,70) #define TUREAD 00400 /address@hidden
read by owner }*/
+../tar_texi/header.texi(,71) #define TUWRITE 00200 /address@hidden
write by owner }*/
+../tar_texi/header.texi(,72) #define TUEXEC 00100 /address@hidden
execute/search by owner }*/
+../tar_texi/header.texi(,73) #define TGREAD 00040 /address@hidden
read by group }*/
+../tar_texi/header.texi(,74) #define TGWRITE 00020 /address@hidden
write by group }*/
+../tar_texi/header.texi(,75) #define TGEXEC 00010 /address@hidden
execute/search by group }*/
+../tar_texi/header.texi(,76) #define TOREAD 00004 /address@hidden
read by other }*/
+../tar_texi/header.texi(,77) #define TOWRITE 00002 /address@hidden
write by other }*/
+../tar_texi/header.texi(,78) #define TOEXEC 00001 /address@hidden
execute/search by other }*/
+../tar_texi/header.texi(,79)
+../tar_texi/header.texi(,80) /address@hidden tar Header Block, GNU extensions.
}*/
+../tar_texi/header.texi(,81)
+../tar_texi/header.texi(,82) /address@hidden In GNU tar, SYMTYPE is for to
symbolic links, and CONTTYPE is for
+../tar_texi/header.texi(,83) contiguous files, so maybe disobeying the
`reserved' comment in POSIX
+../tar_texi/header.texi(,84) header description. I suspect these were
meant to be used this way, and
+../tar_texi/header.texi(,85) should not have really been `reserved' in the
published standards. }*/
+../tar_texi/header.texi(,86)
+../tar_texi/header.texi(,87) /address@hidden *BEWARE* *BEWARE* *BEWARE* that
the following information is still
+../tar_texi/header.texi(,88) boiling, and may change. Even if the OLDGNU
format description should be
+../tar_texi/header.texi(,89) accurate, the so-called GNU format is not yet
fully decided. It is
+../tar_texi/header.texi(,90) surely meant to use only extensions allowed by
POSIX, but the sketch
+../tar_texi/header.texi(,91) below repeats some ugliness from the OLDGNU
format, which should rather
+../tar_texi/header.texi(,92) go away. Sparse files should be saved in such
a way that they do *not*
+../tar_texi/header.texi(,93) require two passes at archive creation time.
Huge files get some POSIX
+../tar_texi/header.texi(,94) fields to overflow, alternate solutions have
to be sought for this. }*/
+../tar_texi/header.texi(,95)
+../tar_texi/header.texi(,96) /address@hidden Descriptor for a single file
hole. }*/
+../tar_texi/header.texi(,97)
+../tar_texi/header.texi(,98) struct sparse
+../tar_texi/header.texi(,99) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,100) char offset[12]; /address@hidden
0 }*/
+../tar_texi/header.texi(,101) char numbytes[12]; /address@hidden
12 }*/
+../tar_texi/header.texi(,102) /address@hidden
24 }*/
+../tar_texi/header.texi(,103) @};
+../tar_texi/header.texi(,104)
+../tar_texi/header.texi(,105) /address@hidden Sparse files are not supported
in POSIX ustar format. For sparse files
+../tar_texi/header.texi(,106) with a POSIX header, a GNU extra header is
provided which holds overall
+../tar_texi/header.texi(,107) sparse information and a few sparse
descriptors. When an old GNU header
+../tar_texi/header.texi(,108) replaces both the POSIX header and the GNU
extra header, it holds some
+../tar_texi/header.texi(,109) sparse descriptors too. Whether POSIX or
not, if more sparse descriptors
+../tar_texi/header.texi(,110) are still needed, they are put into as many
successive sparse headers as
+../tar_texi/header.texi(,111) necessary. The following constants tell how
many sparse descriptors fit
+../tar_texi/header.texi(,112) in each kind of header able to hold them. }*/
+../tar_texi/header.texi(,113)
+../tar_texi/header.texi(,114) #define SPARSES_IN_EXTRA_HEADER 16
+../tar_texi/header.texi(,115) #define SPARSES_IN_OLDGNU_HEADER 4
+../tar_texi/header.texi(,116) #define SPARSES_IN_SPARSE_HEADER 21
+../tar_texi/header.texi(,117)
+../tar_texi/header.texi(,118) /address@hidden Extension header for sparse
files, used immediately after the GNU extra
+../tar_texi/header.texi(,119) header, and used only if all sparse
information cannot fit into that
+../tar_texi/header.texi(,120) extra header. There might even be many such
extension headers, one after
+../tar_texi/header.texi(,121) the other, until all sparse information has
been recorded. }*/
+../tar_texi/header.texi(,122)
+../tar_texi/header.texi(,123) struct sparse_header
+../tar_texi/header.texi(,124) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,125) struct sparse sp[SPARSES_IN_SPARSE_HEADER];
+../tar_texi/header.texi(,126) /address@hidden
0 }*/
+../tar_texi/header.texi(,127) char isextended; /address@hidden
504 }*/
+../tar_texi/header.texi(,128) /address@hidden
505 }*/
+../tar_texi/header.texi(,129) @};
+../tar_texi/header.texi(,130)
+../tar_texi/header.texi(,131) /address@hidden The old GNU format header
conflicts with POSIX format in such a way that
+../tar_texi/header.texi(,132) POSIX archives may fool old GNU tar's, and
POSIX tar's might well be
+../tar_texi/header.texi(,133) fooled by old GNU tar archives. An old GNU
format header uses the space
+../tar_texi/header.texi(,134) used by the prefix field in a POSIX header,
and cumulates information
+../tar_texi/header.texi(,135) normally found in a GNU extra header. With
an old GNU tar header, we
+../tar_texi/header.texi(,136) never see any POSIX header nor GNU extra
header. Supplementary sparse
+../tar_texi/header.texi(,137) headers are allowed, however. }*/
+../tar_texi/header.texi(,138)
+../tar_texi/header.texi(,139) struct oldgnu_header
+../tar_texi/header.texi(,140) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,141) char unused_pad1[345]; /address@hidden
0 }*/
+../tar_texi/header.texi(,142) char atime[12]; /address@hidden
345 Incr. archive: atime of the file }*/
+../tar_texi/header.texi(,143) char ctime[12]; /address@hidden
357 Incr. archive: ctime of the file }*/
+../tar_texi/header.texi(,144) char offset[12]; /address@hidden
369 Multivolume archive: the offset of
+../tar_texi/header.texi(,145) the start of
this volume }*/
+../tar_texi/header.texi(,146) char longnames[4]; /address@hidden
381 Not used }*/
+../tar_texi/header.texi(,147) char unused_pad2; /address@hidden
385 }*/
+../tar_texi/header.texi(,148) struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
+../tar_texi/header.texi(,149) /address@hidden
386 }*/
+../tar_texi/header.texi(,150) char isextended; /address@hidden
482 Sparse file: Extension sparse header
+../tar_texi/header.texi(,151) follows }*/
+../tar_texi/header.texi(,152) char realsize[12]; /address@hidden
483 Sparse file: Real size}*/
+../tar_texi/header.texi(,153) /address@hidden
495 }*/
+../tar_texi/header.texi(,154) @};
+../tar_texi/header.texi(,155)
+../tar_texi/header.texi(,156) /address@hidden OLDGNU_MAGIC uses both magic and
version fields, which are contiguous.
+../tar_texi/header.texi(,157) Found in an archive, it indicates an old GNU
header format, which will be
+../tar_texi/header.texi(,158) hopefully become obsolescent. With
OLDGNU_MAGIC, uname and gname are
+../tar_texi/header.texi(,159) valid, though the header is not truly POSIX
conforming. }*/
+../tar_texi/header.texi(,160) #define OLDGNU_MAGIC "ustar " /address@hidden
7 chars and a null }*/
+../tar_texi/header.texi(,161)
+../tar_texi/header.texi(,162) /address@hidden The standards committee allows
only capital A through capital Z for
+../tar_texi/header.texi(,163) user-defined expansion. Other letters in use
include:
+../tar_texi/header.texi(,164)
+../tar_texi/header.texi(,165) 'A' Solaris Access Control List
+../tar_texi/header.texi(,166) 'E' Solaris Extended Attribute File
+../tar_texi/header.texi(,167) 'I' Inode only, as in 'star'
+../tar_texi/header.texi(,168) 'X' POSIX 1003.1-2001 eXtended (VU version)
}*/
+../tar_texi/header.texi(,169)
+../tar_texi/header.texi(,170) /address@hidden This is a dir entry that
contains the names of files that were in the
+../tar_texi/header.texi(,171) dir at the time the dump was made. }*/
+../tar_texi/header.texi(,172) #define GNUTYPE_DUMPDIR 'D'
+../tar_texi/header.texi(,173)
+../tar_texi/header.texi(,174) /address@hidden Identifies the *next* file on
the tape as having a long linkname. }*/
+../tar_texi/header.texi(,175) #define GNUTYPE_LONGLINK 'K'
+../tar_texi/header.texi(,176)
+../tar_texi/header.texi(,177) /address@hidden Identifies the *next* file on
the tape as having a long name. }*/
+../tar_texi/header.texi(,178) #define GNUTYPE_LONGNAME 'L'
+../tar_texi/header.texi(,179)
+../tar_texi/header.texi(,180) /address@hidden This is the continuation of a
file that began on another volume. }*/
+../tar_texi/header.texi(,181) #define GNUTYPE_MULTIVOL 'M'
+../tar_texi/header.texi(,182)
+../tar_texi/header.texi(,183) /address@hidden For storing filenames that do
not fit into the main header. }*/
+../tar_texi/header.texi(,184) #define GNUTYPE_NAMES 'N'
+../tar_texi/header.texi(,185)
+../tar_texi/header.texi(,186) /address@hidden This is for sparse files. }*/
+../tar_texi/header.texi(,187) #define GNUTYPE_SPARSE 'S'
+../tar_texi/header.texi(,188)
+../tar_texi/header.texi(,189) /address@hidden This file is a tape/volume
header. Ignore it on extraction. }*/
+../tar_texi/header.texi(,190) #define GNUTYPE_VOLHDR 'V'
+../tar_texi/header.texi(,191)
+../tar_texi/header.texi(,192) /address@hidden Solaris extended header }*/
+../tar_texi/header.texi(,193) #define SOLARIS_XHDTYPE 'X'
+../tar_texi/header.texi(,194)
+../tar_texi/header.texi(,195) /address@hidden J@"org Schilling star header }*/
+../tar_texi/header.texi(,196)
+../tar_texi/header.texi(,197) struct star_header
+../tar_texi/header.texi(,198) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,199) char name[100]; /address@hidden
0 }*/
+../tar_texi/header.texi(,200) char mode[8]; /address@hidden
100 }*/
+../tar_texi/header.texi(,201) char uid[8]; /address@hidden
108 }*/
+../tar_texi/header.texi(,202) char gid[8]; /address@hidden
116 }*/
+../tar_texi/header.texi(,203) char size[12]; /address@hidden
124 }*/
+../tar_texi/header.texi(,204) char mtime[12]; /address@hidden
136 }*/
+../tar_texi/header.texi(,205) char chksum[8]; /address@hidden
148 }*/
+../tar_texi/header.texi(,206) char typeflag; /address@hidden
156 }*/
+../tar_texi/header.texi(,207) char linkname[100]; /address@hidden
157 }*/
+../tar_texi/header.texi(,208) char magic[6]; /address@hidden
257 }*/
+../tar_texi/header.texi(,209) char version[2]; /address@hidden
263 }*/
+../tar_texi/header.texi(,210) char uname[32]; /address@hidden
265 }*/
+../tar_texi/header.texi(,211) char gname[32]; /address@hidden
297 }*/
+../tar_texi/header.texi(,212) char devmajor[8]; /address@hidden
329 }*/
+../tar_texi/header.texi(,213) char devminor[8]; /address@hidden
337 }*/
+../tar_texi/header.texi(,214) char prefix[131]; /address@hidden
345 }*/
+../tar_texi/header.texi(,215) char atime[12]; /address@hidden
476 }*/
+../tar_texi/header.texi(,216) char ctime[12]; /address@hidden
488 }*/
+../tar_texi/header.texi(,217) /address@hidden
500 }*/
+../tar_texi/header.texi(,218) @};
+../tar_texi/header.texi(,219)
+../tar_texi/header.texi(,220) #define SPARSES_IN_STAR_HEADER 4
+../tar_texi/header.texi(,221) #define SPARSES_IN_STAR_EXT_HEADER 21
+../tar_texi/header.texi(,222)
+../tar_texi/header.texi(,223) struct star_in_header
+../tar_texi/header.texi(,224) @{
+../tar_texi/header.texi(,225) char fill[345]; /address@hidden 0
Everything that is before t_prefix }*/
+../tar_texi/header.texi(,226) char prefix[1]; /address@hidden 345
t_name prefix }*/
+../tar_texi/header.texi(,227) char fill2; /address@hidden 346 }*/
+../tar_texi/header.texi(,228) char fill3[8]; /address@hidden 347 }*/
+../tar_texi/header.texi(,229) char isextended; /address@hidden 355 }*/
+../tar_texi/header.texi(,230) struct sparse sp[SPARSES_IN_STAR_HEADER];
/address@hidden 356 }*/
+../tar_texi/header.texi(,231) char realsize[12]; /address@hidden 452
Actual size of the file }*/
+../tar_texi/header.texi(,232) char offset[12]; /address@hidden 464
Offset of multivolume contents }*/
+../tar_texi/header.texi(,233) char atime[12]; /address@hidden 476 }*/
+../tar_texi/header.texi(,234) char ctime[12]; /address@hidden 488 }*/
+../tar_texi/header.texi(,235) char mfill[8]; /address@hidden 500 }*/
+../tar_texi/header.texi(,236) char xmagic[4]; /address@hidden 508
"tar" }*/
+../tar_texi/header.texi(,237) @};
+../tar_texi/header.texi(,238)
+../tar_texi/header.texi(,239) struct star_ext_header
+../tar_texi/header.texi(,240) @{
+../tar_texi/header.texi(,241) struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
+../tar_texi/header.texi(,242) char isextended;
+../tar_texi/header.texi(,243) @};
+../tar_texi/header.texi(,244)
+../tar_texi/intern.texi(,74) @end smallexample
+../tar_texi/intern.texi(,75)
+../tar_texi/intern.texi(,76) All characters in header blocks are represented
by using 8-bit
+../tar_texi/intern.texi(,77) characters in the local variant of ASCII. Each
field within the
+../tar_texi/intern.texi(,78) structure is contiguous; that is, there is no
padding used within
+../tar_texi/intern.texi(,79) the structure. Each character on the archive
medium is stored
+../tar_texi/intern.texi(,80) contiguously.
+../tar_texi/intern.texi(,81)
+../tar_texi/intern.texi(,82) Bytes representing the contents of files (after
the header block
+../tar_texi/intern.texi(,83) of each file) are not translated in any way and
are not constrained
+../tar_texi/intern.texi(,84) to represent characters in any character set.
The @command{tar} format
+../tar_texi/intern.texi(,85) does not distinguish text files from binary
files, and no translation
+../tar_texi/intern.texi(,86) of file contents is performed.
+../tar_texi/intern.texi(,87)
+../tar_texi/intern.texi(,88) The @code{name}, @code{linkname}, @code{magic},
@code{uname}, and
+../tar_texi/intern.texi(,89) @code{gname} are null-terminated character
strings. All other fields
+../tar_texi/intern.texi(,90) are zero-filled octal numbers in ASCII. Each
numeric field of width
+../tar_texi/intern.texi(,91) @var{w} contains @var{w} minus 1 digits, and a
null.
+../tar_texi/intern.texi(,92)
+../tar_texi/intern.texi(,93) The @code{name} field is the file name of the
file, with directory names
+../tar_texi/intern.texi(,94) (if any) preceding the file name, separated by
slashes.
+../tar_texi/intern.texi(,95)
+../tar_texi/intern.texi(FIXME,96) @allow-recursion
+../tar_texi/intern.texi(FIXME,96) @quote-arg
+../tar_texi/intern.texi(FIXME,96)
+../tar_texi/intern.texi(,97)
+../tar_texi/intern.texi(,98) The @code{mode} field provides nine bits
specifying file permissions
+../tar_texi/intern.texi(,99) and three bits to specify the Set UID, Set GID,
and Save Text
+../tar_texi/intern.texi(,100) (@dfn{sticky}) modes. Values for these bits are
defined above.
+../tar_texi/intern.texi(,101) When special permissions are required to create
a file with a given
+../tar_texi/intern.texi(,102) mode, and the user restoring files from the
archive does not hold such
+../tar_texi/intern.texi(,103) permissions, the mode bit(s) specifying those
special permissions
+../tar_texi/intern.texi(,104) are ignored. Modes which are not supported by
the operating system
+../tar_texi/intern.texi(,105) restoring files from the archive will be
ignored. Unsupported modes
+../tar_texi/intern.texi(,106) should be faked up when creating or updating an
archive; e.g., the
+../tar_texi/intern.texi(,107) group permission could be copied from the
@emph{other} permission.
+../tar_texi/intern.texi(,108)
+../tar_texi/intern.texi(,109) The @code{uid} and @code{gid} fields are the
numeric user and group
+../tar_texi/intern.texi(,110) ID of the file owners, respectively. If the
operating system does
+../tar_texi/intern.texi(,111) not support numeric user or group IDs, these
fields should be ignored.
+../tar_texi/intern.texi(,112)
+../tar_texi/intern.texi(,113) The @code{size} field is the size of the file in
bytes; linked files
+../tar_texi/intern.texi(FIXME-xref,115) are archived with this field specified
as zero. @quote-arg
+../tar_texi/intern.texi(FIXME-xref,115)
+../tar_texi/intern.texi(,116)
+../tar_texi/intern.texi(,117) The @code{mtime} field is the data modification
time of the file at
+../tar_texi/intern.texi(,118) the time it was archived. It is the ASCII
representation of the octal
+../tar_texi/intern.texi(,119) value of the last time the file's contents were
modified, represented
+../tar_texi/intern.texi(,120) as an integer number of
+../tar_texi/intern.texi(,121) seconds since January 1, 1970, 00:00 Coordinated
Universal Time.
+../tar_texi/intern.texi(,122)
+../tar_texi/intern.texi(,123) The @code{chksum} field is the ASCII
representation of the octal value
+../tar_texi/intern.texi(,124) of the simple sum of all bytes in the header
block. Each 8-bit
+../tar_texi/intern.texi(,125) byte in the header is added to an unsigned
integer, initialized to
+../tar_texi/intern.texi(,126) zero, the precision of which shall be no less
than seventeen bits.
+../tar_texi/intern.texi(,127) When calculating the checksum, the @code{chksum}
field is treated as
+../tar_texi/intern.texi(,128) if it were all blanks.
+../tar_texi/intern.texi(,129)
+../tar_texi/intern.texi(,130) The @code{typeflag} field specifies the type of
file archived. If a
+../tar_texi/intern.texi(,131) particular implementation does not recognize or
permit the specified
+../tar_texi/intern.texi(,132) type, the file will be extracted as if it were a
regular file. As this
+../tar_texi/intern.texi(,133) action occurs, @command{tar} issues a warning to
the standard error.
+../tar_texi/intern.texi(,134)
+../tar_texi/intern.texi(,135) The @code{atime} and @code{ctime} fields are
used in making incremental
+../tar_texi/intern.texi(,136) backups; they store, respectively, the
particular file's access and
+../tar_texi/intern.texi(,137) status change times.
+../tar_texi/intern.texi(,138)
+../tar_texi/intern.texi(,139) The @code{offset} is used by the
@option{--multi-volume} (@option{-M}) option, when
+../tar_texi/intern.texi(,140) making a multi-volume archive. The offset is
number of bytes into
+../tar_texi/intern.texi(,141) the file that we need to restart at to continue
the file on the next
+../tar_texi/intern.texi(,142) tape, i.e., where we store the location that a
continued file is
+../tar_texi/intern.texi(,143) continued at.
+../tar_texi/intern.texi(,144)
+../tar_texi/intern.texi(,145) The following fields were added to deal with
sparse files. A file
+../tar_texi/intern.texi(,146) is @dfn{sparse} if it takes in unallocated
blocks which end up being
+../tar_texi/intern.texi(,147) represented as zeros, i.e., no useful data. A
test to see if a file
+../tar_texi/intern.texi(,148) is sparse is to look at the number blocks
allocated for it versus the
+../tar_texi/intern.texi(,149) number of characters in the file; if there are
fewer blocks allocated
+../tar_texi/intern.texi(,150) for the file than would normally be allocated
for a file of that
+../tar_texi/intern.texi(,151) size, then the file is sparse. This is the
method @command{tar} uses to
+../tar_texi/intern.texi(,152) detect a sparse file, and once such a file is
detected, it is treated
+../tar_texi/intern.texi(,153) differently from non-sparse files.
+../tar_texi/intern.texi(,154)
+../tar_texi/intern.texi(,155) Sparse files are often @code{dbm} files, or
other database-type files
+../tar_texi/intern.texi(,156) which have data at some points and emptiness in
the greater part of
+../tar_texi/intern.texi(,157) the file. Such files can appear to be very
large when an @samp{ls
+../tar_texi/intern.texi(,158) -l} is done on them, when in truth, there may be
a very small amount
+../tar_texi/intern.texi(,159) of important data contained in the file. It is
thus undesirable
+../tar_texi/intern.texi(,160) to have @command{tar} think that it must back up
this entire file, as
+../tar_texi/intern.texi(,161) great quantities of room are wasted on empty
blocks, which can lead
+../tar_texi/intern.texi(,162) to running out of room on a tape far earlier
than is necessary.
+../tar_texi/intern.texi(,163) Thus, sparse files are dealt with so that these
empty blocks are
+../tar_texi/intern.texi(,164) not written to the tape. Instead, what is
written to the tape is a
+../tar_texi/intern.texi(,165) description, of sorts, of the sparse file: where
the holes are, how
+../tar_texi/intern.texi(,166) big the holes are, and how much data is found at
the end of the hole.
+../tar_texi/intern.texi(,167) This way, the file takes up potentially far less
room on the tape,
+../tar_texi/intern.texi(,168) and when the file is extracted later on, it will
look exactly the way
+../tar_texi/intern.texi(,169) it looked beforehand. The following is a
description of the fields
+../tar_texi/intern.texi(,170) used to handle a sparse file:
+../tar_texi/intern.texi(,171)
+../tar_texi/intern.texi(,172) The @code{sp} is an array of @code{struct
sparse}. Each @code{struct
+../tar_texi/intern.texi(,173) sparse} contains two 12-character strings which
represent an offset
+../tar_texi/intern.texi(,174) into the file and a number of bytes to be
written at that offset.
+../tar_texi/intern.texi(,175) The offset is absolute, and not relative to the
offset in preceding
+../tar_texi/intern.texi(,176) array element.
+../tar_texi/intern.texi(,177)
+../tar_texi/intern.texi(,178) The header can hold four of these @code{struct
sparse} at the moment;
+../tar_texi/intern.texi(,179) if more are needed, they are not stored in the
header.
+../tar_texi/intern.texi(,180)
+../tar_texi/intern.texi(,181) The @code{isextended} flag is set when an
@code{extended_header}
+../tar_texi/intern.texi(,182) is needed to deal with a file. Note that this
means that this flag
+../tar_texi/intern.texi(,183) can only be set when dealing with a sparse file,
and it is only set
+../tar_texi/intern.texi(,184) in the event that the description of the file
will not fit in the
+../tar_texi/intern.texi(,185) allotted room for sparse structures in the
header. In other words,
+../tar_texi/intern.texi(,186) an extended_header is needed.
+../tar_texi/intern.texi(,187)
+../tar_texi/intern.texi(,188) The @code{extended_header} structure is used for
sparse files which
+../tar_texi/intern.texi(,189) need more sparse structures than can fit in the
header. The header can
+../tar_texi/intern.texi(,190) fit 4 such structures; if more are needed, the
flag @code{isextended}
+../tar_texi/intern.texi(,191) gets set and the next block is an
@code{extended_header}.
+../tar_texi/intern.texi(,192)
+../tar_texi/intern.texi(,193) Each @code{extended_header} structure contains
an array of 21
+../tar_texi/intern.texi(,194) sparse structures, along with a similar
@code{isextended} flag
+../tar_texi/intern.texi(,195) that the header had. There can be an
indeterminate number of such
+../tar_texi/intern.texi(,196) @code{extended_header}s to describe a sparse
file.
+../tar_texi/intern.texi(,197)
+../tar_texi/intern.texi(,198) @table @asis
+../tar_texi/intern.texi(,199)
+../tar_texi/intern.texi(,200) @item @code{REGTYPE}
+../tar_texi/intern.texi(,201) @itemx @code{AREGTYPE}
+../tar_texi/intern.texi(,202) These flags represent a regular file. In order
to be compatible
+../tar_texi/intern.texi(,203) with older versions of @command{tar}, a
@code{typeflag} value of
+../tar_texi/intern.texi(,204) @code{AREGTYPE} should be silently recognized as
a regular file.
+../tar_texi/intern.texi(,205) New archives should be created using
@code{REGTYPE}. Also, for
+../tar_texi/intern.texi(,206) backward compatibility, @command{tar} treats a
regular file whose name
+../tar_texi/intern.texi(,207) ends with a slash as a directory.
+../tar_texi/intern.texi(,208)
+../tar_texi/intern.texi(,209) @item @code{LNKTYPE}
+../tar_texi/intern.texi(,210) This flag represents a file linked to another
file, of any type,
+../tar_texi/intern.texi(,211) previously archived. Such files are identified
in Unix by each
+../tar_texi/intern.texi(,212) file having the same device and inode number.
The linked-to name is
+../tar_texi/intern.texi(,213) specified in the @code{linkname} field with a
trailing null.
+../tar_texi/intern.texi(,214)
+../tar_texi/intern.texi(,215) @item @code{SYMTYPE}
+../tar_texi/intern.texi(,216) This represents a symbolic link to another file.
The linked-to name
+../tar_texi/intern.texi(,217) is specified in the @code{linkname} field with a
trailing null.
+../tar_texi/intern.texi(,218)
+../tar_texi/intern.texi(,219) @item @code{CHRTYPE}
+../tar_texi/intern.texi(,220) @itemx @code{BLKTYPE}
+../tar_texi/intern.texi(,221) These represent character special files and
block special files
+../tar_texi/intern.texi(,222) respectively. In this case the @code{devmajor}
and @code{devminor}
+../tar_texi/intern.texi(,223) fields will contain the major and minor device
numbers respectively.
+../tar_texi/intern.texi(,224) Operating systems may map the device
specifications to their own
+../tar_texi/intern.texi(,225) local specification, or may ignore the entry.
+../tar_texi/intern.texi(,226)
+../tar_texi/intern.texi(,227) @item @code{DIRTYPE}
+../tar_texi/intern.texi(,228) This flag specifies a directory or
sub-directory. The directory
+../tar_texi/intern.texi(,229) name in the @code{name} field should end with a
slash. On systems where
+../tar_texi/intern.texi(,230) disk allocation is performed on a directory
basis, the @code{size} field
+../tar_texi/intern.texi(,231) will contain the maximum number of bytes (which
may be rounded to
+../tar_texi/intern.texi(,232) the nearest disk block allocation unit) which
the directory may
+../tar_texi/intern.texi(,233) hold. A @code{size} field of zero indicates no
such limiting. Systems
+../tar_texi/intern.texi(,234) which do not support limiting in this manner
should ignore the
+../tar_texi/intern.texi(,235) @code{size} field.
+../tar_texi/intern.texi(,236)
+../tar_texi/intern.texi(,237) @item @code{FIFOTYPE}
+../tar_texi/intern.texi(,238) This specifies a FIFO special file. Note that
the archiving of a
+../tar_texi/intern.texi(,239) FIFO file archives the existence of this file
and not its contents.
+../tar_texi/intern.texi(,240)
+../tar_texi/intern.texi(,241) @item @code{CONTTYPE}
+../tar_texi/intern.texi(,242) This specifies a contiguous file, which is the
same as a normal
+../tar_texi/intern.texi(,243) file except that, in operating systems which
support it, all its
+../tar_texi/intern.texi(,244) space is allocated contiguously on the disk.
Operating systems
+../tar_texi/intern.texi(,245) which do not allow contiguous allocation should
silently treat this
+../tar_texi/intern.texi(,246) type as a normal file.
+../tar_texi/intern.texi(,247)
+../tar_texi/intern.texi(,248) @item @code{A} @dots{} @code{Z}
+../tar_texi/intern.texi(,249) These are reserved for custom implementations.
Some of these are
+../tar_texi/intern.texi(,250) used in the @acronym{GNU} modified format, as
described below.
+../tar_texi/intern.texi(,251)
+../tar_texi/intern.texi(,252) @end table
+../tar_texi/intern.texi(,253)
+../tar_texi/intern.texi(,254) Other values are reserved for specification in
future revisions of
+../tar_texi/intern.texi(,255) the P1003 standard, and should not be used by
any @command{tar} program.
+../tar_texi/intern.texi(,256)
+../tar_texi/intern.texi(,257) The @code{magic} field indicates that this
archive was output in
+../tar_texi/intern.texi(,258) the P1003 archive format. If this field
contains @code{TMAGIC},
+../tar_texi/intern.texi(,259) the @code{uname} and @code{gname} fields will
contain the ASCII
+../tar_texi/intern.texi(,260) representation of the owner and group of the
file respectively.
+../tar_texi/intern.texi(,261) If found, the user and group IDs are used rather
than the values in
+../tar_texi/intern.texi(,262) the @code{uid} and @code{gid} fields.
+../tar_texi/intern.texi(,263)
+../tar_texi/intern.texi(,264) For references, see ISO/IEC 9945-1:1990 or IEEE
Std 1003.1-1990, pages
+../tar_texi/intern.texi(,265) 169-173 (section 10.1) for
@cite{Archive/Interchange File Format}; and
+../tar_texi/intern.texi(,266) IEEE Std 1003.2-1992, pages 380-388 (section
4.48) and pages 936-940
+../tar_texi/intern.texi(,267) (section E.4.48) for @cite{pax - Portable
archive interchange}.
+../tar_texi/intern.texi(,268)
+../tar_texi/intern.texi(,269) @node Extensions
+../tar_texi/intern.texi(,270) @unnumberedsec @acronym{GNU} Extensions to the
Archive Format
+../tar_texi/intern.texi(UNREVISED,271) @quotation
+../tar_texi/intern.texi(UNREVISED,271) @emph{(This message will disappear,
once this node revised.)}
+../tar_texi/intern.texi(UNREVISED,271) @end quotation
+../tar_texi/intern.texi(UNREVISED,271)
+../tar_texi/intern.texi(,272)
+../tar_texi/intern.texi(,273) The @acronym{GNU} format uses additional file
types to describe new types of
+../tar_texi/intern.texi(,274) files in an archive. These are listed below.
+../tar_texi/intern.texi(,275)
+../tar_texi/intern.texi(,276) @table @code
+../tar_texi/intern.texi(,277) @item GNUTYPE_DUMPDIR
+../tar_texi/intern.texi(,278) @itemx 'D'
+../tar_texi/intern.texi(,279) This represents a directory and a list of files
created by the
+../tar_texi/intern.texi(,280) @option{--incremental} (@option{-G}) option.
The @code{size} field gives the total
+../tar_texi/intern.texi(,281) size of the associated list of files. Each file
name is preceded by
+../tar_texi/intern.texi(,282) either a @samp{Y} (the file should be in this
archive) or an @samp{N}.
+../tar_texi/intern.texi(,283) (The file is a directory, or is not stored in
the archive.) Each file
+../tar_texi/intern.texi(,284) name is terminated by a null. There is an
additional null after the
+../tar_texi/intern.texi(,285) last file name.
+../tar_texi/intern.texi(,286)
+../tar_texi/intern.texi(,287) @item GNUTYPE_MULTIVOL
+../tar_texi/intern.texi(,288) @itemx 'M'
+../tar_texi/intern.texi(,289) This represents a file continued from another
volume of a multi-volume
+../tar_texi/intern.texi(,290) archive created with the @option{--multi-volume}
(@option{-M}) option. The original
+../tar_texi/intern.texi(,291) type of the file is not given here. The
@code{size} field gives the
+../tar_texi/intern.texi(,292) maximum size of this piece of the file (assuming
the volume does
+../tar_texi/intern.texi(,293) not end before the file is written out). The
@code{offset} field
+../tar_texi/intern.texi(,294) gives the offset from the beginning of the file
where this part of
+../tar_texi/intern.texi(,295) the file begins. Thus @code{size} plus
@code{offset} should equal
+../tar_texi/intern.texi(,296) the original size of the file.
+../tar_texi/intern.texi(,297)
+../tar_texi/intern.texi(,298) @item GNUTYPE_SPARSE
+../tar_texi/intern.texi(,299) @itemx 'S'
+../tar_texi/intern.texi(,300) This flag indicates that we are dealing with a
sparse file. Note
+../tar_texi/intern.texi(,301) that archiving a sparse file requires special
operations to find
+../tar_texi/intern.texi(,302) holes in the file, which mark the positions of
these holes, along
+../tar_texi/intern.texi(,303) with the number of bytes of data to be found
after the hole.
+../tar_texi/intern.texi(,304)
+../tar_texi/intern.texi(,305) @item GNUTYPE_VOLHDR
+../tar_texi/intern.texi(,306) @itemx 'V'
+../tar_texi/intern.texi(,307) This file type is used to mark the volume header
that was given with
+../tar_texi/intern.texi(,308) the @address@hidden (@option{-V
@var{archive-label}}) option when the archive was created. The @code{name}
+../tar_texi/intern.texi(,309) field contains the @code{name} given after the
@address@hidden (@option{-V @var{archive-label}}) option.
+../tar_texi/intern.texi(,310) The @code{size} field is zero. Only the first
file in each volume
+../tar_texi/intern.texi(,311) of an archive should have this type.
+../tar_texi/intern.texi(,312)
+../tar_texi/intern.texi(,313) @end table
+../tar_texi/intern.texi(,314)
+../tar_texi/intern.texi(,315) You may have trouble reading a @acronym{GNU}
format archive on a
+../tar_texi/intern.texi(,316) address@hidden system if the options
@option{--incremental} (@option{-G}),
+../tar_texi/intern.texi(,317) @option{--multi-volume} (@option{-M}),
@option{--sparse} (@option{-S}), or @address@hidden (@option{-V
@var{archive-label}}) were
+../tar_texi/intern.texi(,318) used when writing the archive. In general, if
@command{tar} does not
+../tar_texi/intern.texi(,319) use the @acronym{GNU}-added fields of the
header, other versions of
+../tar_texi/intern.texi(,320) @command{tar} should be able to read the
archive. Otherwise, the
+../tar_texi/intern.texi(,321) @command{tar} program will give an error, the
most likely one being a
+../tar_texi/intern.texi(,322) checksum error.
+../tar_texi/intern.texi(,323)
+../tar_texi/intern.texi(,324) @node Sparse Formats
+../tar_texi/intern.texi(,325) @unnumberedsec Storing Sparse Files
+../tar_texi/sparse.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/sparse.texi(,2) @c Copyright (C) 2006 Free Software Foundation,
Inc.
+../tar_texi/sparse.texi(,3) @c This file is distributed under GFDL 1.1 or any
later version
+../tar_texi/sparse.texi(,4) @c published by the Free Software Foundation.
+../tar_texi/sparse.texi(,5)
+../tar_texi/sparse.texi(,6) @cindex sparse formats
+../tar_texi/sparse.texi(,7) @cindex sparse versions
+../tar_texi/sparse.texi(,8) The notion of sparse file, and the ways of
handling it from the point
+../tar_texi/sparse.texi(GNUTAR,9) of view of @acronym{GNU} @command{tar} user
have been described in detail in
+../tar_texi/sparse.texi(GNUTAR,10) @ref{sparse}. This chapter describes the
internal format @acronym{GNU} @command{tar}
+../tar_texi/sparse.texi(,11) uses to store such files.
+../tar_texi/sparse.texi(,12)
+../tar_texi/sparse.texi(GNUTAR,13) The support for sparse files in
@acronym{GNU} @command{tar} has a long history. The
+../tar_texi/sparse.texi(,14) earliest version featuring this support that I
was able to find was 1.09,
+../tar_texi/sparse.texi(,15) released in November, 1990. The format
introduced back then is called
+../tar_texi/sparse.texi(,16) @dfn{old GNU} sparse format and in spite of the
fact that its design
+../tar_texi/sparse.texi(GNUTAR,17) contained many flaws, it was the only
format @acronym{GNU} @command{tar} supported
+../tar_texi/sparse.texi(,18) until version 1.14 (May, 2004), which introduced
initial support for
+../tar_texi/sparse.texi(,19) sparse archives in @acronym{PAX} archives
(@pxref{posix}). This
+../tar_texi/sparse.texi(,20) format was not free from design flows, either and
it was subsequently
+../tar_texi/sparse.texi(,21) improved in versions 1.15.2 (November, 2005) and
1.15.92 (June,
+../tar_texi/sparse.texi(,22) 2006).
+../tar_texi/sparse.texi(,23)
+../tar_texi/sparse.texi(GNUTAR,24) In addition to GNU sparse format,
@acronym{GNU} @command{tar} is able to read and
+../tar_texi/sparse.texi(,25) extract sparse files archived by @command{star}.
+../tar_texi/sparse.texi(,26)
+../tar_texi/sparse.texi(,27) The following subsections describe each format in
detail.
+../tar_texi/sparse.texi(,28)
+../tar_texi/sparse.texi(,29) @menu
+../tar_texi/sparse.texi(,30) * Old GNU Format::
+../tar_texi/sparse.texi(,31) * PAX 0:: PAX Format, Versions 0.0
and 0.1
+../tar_texi/sparse.texi(,32) * PAX 1:: PAX Format, Version 1.0
+../tar_texi/sparse.texi(,33) @end menu
+../tar_texi/sparse.texi(,34)
+../tar_texi/sparse.texi(,35) @node Old GNU Format
+../tar_texi/sparse.texi(,36) @appendixsubsec Old GNU Format
+../tar_texi/sparse.texi(,37)
+../tar_texi/sparse.texi(,38) @cindex sparse formats, Old GNU
+../tar_texi/sparse.texi(,39) @cindex Old GNU sparse format
+../tar_texi/sparse.texi(,40) The format introduced some time around 1990 (v.
1.09). It was
+../tar_texi/sparse.texi(,41) designed on top of standard @code{ustar} headers
in such an
+../tar_texi/sparse.texi(,42) unfortunate way that some of its fields overwrote
fields required by
+../tar_texi/sparse.texi(,43) POSIX.
+../tar_texi/sparse.texi(,44)
+../tar_texi/sparse.texi(,45) An old GNU sparse header is designated by type
@samp{S}
+../tar_texi/sparse.texi(,46) (@code{GNUTYPE_SPARSE}) and has the following
layout:
+../tar_texi/sparse.texi(,47)
+../tar_texi/sparse.texi(,48) @multitable @columnfractions 0.10 0.10 0.20 0.20
0.40
+../tar_texi/sparse.texi(,49) @headitem Offset @tab Size @tab Name @tab Data
type @tab Contents
+../tar_texi/sparse.texi(,50) @item 0 @tab 345 @tab @tab N/A
@tab Not used.
+../tar_texi/sparse.texi(,51) @item 345 @tab 12 @tab atime @tab
Number @tab @code{atime} of the file.
+../tar_texi/sparse.texi(,52) @item 357 @tab 12 @tab ctime @tab
Number @tab @code{ctime} of the file .
+../tar_texi/sparse.texi(,53) @item 369 @tab 12 @tab offset @tab
Number @tab For
+../tar_texi/sparse.texi(,54) multivolume archives: the offset of the start of
this volume.
+../tar_texi/sparse.texi(,55) @item 381 @tab 4 @tab @tab N/A
@tab Not used.
+../tar_texi/sparse.texi(,56) @item 385 @tab 1 @tab @tab N/A
@tab Not used.
+../tar_texi/sparse.texi(,57) @item 386 @tab 96 @tab sp @tab
@code{sparse_header} @tab (4 entries) File map.
+../tar_texi/sparse.texi(,58) @item 482 @tab 1 @tab isextended @tab
Bool @tab @code{1} if an
+../tar_texi/sparse.texi(,59) extension sparse header follows, @code{0}
otherwise.
+../tar_texi/sparse.texi(,60) @item 483 @tab 12 @tab realsize @tab
Number @tab Real size of the file.
+../tar_texi/sparse.texi(,61) @end multitable
+../tar_texi/sparse.texi(,62)
+../tar_texi/sparse.texi(,63) Each of @code{sparse_header} object at offset 386
describes a single
+../tar_texi/sparse.texi(,64) data chunk. It has the following structure:
+../tar_texi/sparse.texi(,65)
+../tar_texi/sparse.texi(,66) @multitable @columnfractions 0.10 0.10 0.20 0.60
+../tar_texi/sparse.texi(,67) @headitem Offset @tab Size @tab Data type @tab
Contents
+../tar_texi/sparse.texi(,68) @item 0 @tab 12 @tab Number @tab
Offset of the
+../tar_texi/sparse.texi(,69) beginning of the chunk.
+../tar_texi/sparse.texi(,70) @item 12 @tab 12 @tab Number @tab
Size of the chunk.
+../tar_texi/sparse.texi(,71) @end multitable
+../tar_texi/sparse.texi(,72)
+../tar_texi/sparse.texi(,73) If the member contains more than four chunks, the
@code{isextended}
+../tar_texi/sparse.texi(,74) field of the header has the value @code{1} and
the main header is
+../tar_texi/sparse.texi(,75) followed by one or more @dfn{extension headers}.
Each such header has
+../tar_texi/sparse.texi(,76) the following structure:
+../tar_texi/sparse.texi(,77)
+../tar_texi/sparse.texi(,78) @multitable @columnfractions 0.10 0.10 0.20 0.20
0.40
+../tar_texi/sparse.texi(,79) @headitem Offset @tab Size @tab Name @tab Data
type @tab Contents
+../tar_texi/sparse.texi(,80) @item 0 @tab 21 @tab sp @tab
@code{sparse_header} @tab
+../tar_texi/sparse.texi(,81) (21 entires) File map.
+../tar_texi/sparse.texi(,82) @item 504 @tab 1 @tab isextended @tab
Bool @tab @code{1} if an
+../tar_texi/sparse.texi(,83) extension sparse header follows, or @code{0}
otherwise.
+../tar_texi/sparse.texi(,84) @end multitable
+../tar_texi/sparse.texi(,85)
+../tar_texi/sparse.texi(,86) A header with @code{isextended=0} ends the map.
+../tar_texi/sparse.texi(,87)
+../tar_texi/sparse.texi(,88) @node PAX 0
+../tar_texi/sparse.texi(,89) @appendixsubsec PAX Format, Versions 0.0 and 0.1
+../tar_texi/sparse.texi(,90)
+../tar_texi/sparse.texi(,91) @cindex sparse formats, v.0.0
+../tar_texi/sparse.texi(,92) There are two formats available in this branch.
The version @code{0.0}
+../tar_texi/sparse.texi(,93) is the initial version of sparse format used by
@command{tar}
+../tar_texi/sparse.texi(,94) versions 1.14--1.15.1. The sparse file map is
kept in extended
+../tar_texi/sparse.texi(,95) (@code{x}) PAX header variables:
+../tar_texi/sparse.texi(,96)
+../tar_texi/sparse.texi(,97) @table @code
+../tar_texi/sparse.texi(,98) @vrindex GNU.sparse.size, extended header variable
+../tar_texi/sparse.texi(,99) @item GNU.sparse.size
+../tar_texi/sparse.texi(,100) Real size of the stored file
+../tar_texi/sparse.texi(,101)
+../tar_texi/sparse.texi(,102) @item GNU.sparse.numblocks
+../tar_texi/sparse.texi(,103) @vrindex GNU.sparse.numblocks, extended header
variable
+../tar_texi/sparse.texi(,104) Number of blocks in the sparse map
+../tar_texi/sparse.texi(,105)
+../tar_texi/sparse.texi(,106) @item GNU.sparse.offset
+../tar_texi/sparse.texi(,107) @vrindex GNU.sparse.offset, extended header
variable
+../tar_texi/sparse.texi(,108) Offset of the data block
+../tar_texi/sparse.texi(,109)
+../tar_texi/sparse.texi(,110) @item GNU.sparse.numbytes
+../tar_texi/sparse.texi(,111) @vrindex GNU.sparse.numbytes, extended header
variable
+../tar_texi/sparse.texi(,112) Size of the data block
+../tar_texi/sparse.texi(,113) @end table
+../tar_texi/sparse.texi(,114)
+../tar_texi/sparse.texi(,115) The latter two variables repeat for each data
block, so the overall
+../tar_texi/sparse.texi(,116) structure is like this:
+../tar_texi/sparse.texi(,117)
+../tar_texi/sparse.texi(,118) @smallexample
+../tar_texi/sparse.texi(,119) @group
+../tar_texi/sparse.texi(,120) address@hidden
+../tar_texi/sparse.texi(,121) address@hidden
+../tar_texi/sparse.texi(,122) repeat @var{numblocks} times
+../tar_texi/sparse.texi(,123) address@hidden
+../tar_texi/sparse.texi(,124) address@hidden
+../tar_texi/sparse.texi(,125) end repeat
+../tar_texi/sparse.texi(,126) @end group
+../tar_texi/sparse.texi(,127) @end smallexample
+../tar_texi/sparse.texi(,128)
+../tar_texi/sparse.texi(,129) This format presented the following two problems:
+../tar_texi/sparse.texi(,130)
+../tar_texi/sparse.texi(,131) @enumerate 1
+../tar_texi/sparse.texi(,132) @item
+../tar_texi/sparse.texi(,133) Whereas the POSIX specification allows a
variable to appear multiple
+../tar_texi/sparse.texi(,134) times in a header, it requires that only the
last occurrence be
+../tar_texi/sparse.texi(,135) meaningful. Thus, multiple ocurrences of
@code{GNU.sparse.offset} and
+../tar_texi/sparse.texi(,136) @code{GNU.sparse.numbytes} are conficting with
the POSIX specs.
+../tar_texi/sparse.texi(,137)
+../tar_texi/sparse.texi(,138) @item
+../tar_texi/sparse.texi(,139) Attempting to extract such archives using a
third-party @command{tar}s
+../tar_texi/sparse.texi(,140) results in extraction of sparse files in
@emph{compressed form}. If
+../tar_texi/sparse.texi(,141) the @command{tar} implementation in question
does not support POSIX
+../tar_texi/sparse.texi(,142) format, it will also extract a file containing
extension header
+../tar_texi/sparse.texi(,143) attributes. This file can be used to expand the
file to its original
+../tar_texi/sparse.texi(,144) state. However, posix-aware @command{tar}s will
usually ignore the
+../tar_texi/sparse.texi(,145) unknown variables, which makes restoring the
file more
+../tar_texi/sparse.texi(,146) difficult. @xref{extracting sparse v.0.x,
Extraction of sparse
+../tar_texi/sparse.texi(,147) members in v.0.0 format}, for the detailed
description of how to
+../tar_texi/sparse.texi(,148) restore such members using non-GNU
@command{tar}s.
+../tar_texi/sparse.texi(,149) @end enumerate
+../tar_texi/sparse.texi(,150)
+../tar_texi/sparse.texi(,151) @cindex sparse formats, v.0.1
+../tar_texi/sparse.texi(GNUTAR,152) @acronym{GNU} @command{tar} 1.15.2
introduced sparse format version @code{0.1}, which
+../tar_texi/sparse.texi(,153) attempted to solve these problems. As its
predecessor, this format
+../tar_texi/sparse.texi(,154) stores sparse map in the extended POSIX header.
It retains
+../tar_texi/sparse.texi(,155) @code{GNU.sparse.size} and
@code{GNU.sparse.numblocks} variables, but
+../tar_texi/sparse.texi(,156) instead of
@code{GNU.sparse.offset}/@code{GNU.sparse.numbytes} pairs
+../tar_texi/sparse.texi(,157) it uses a single variable:
+../tar_texi/sparse.texi(,158)
+../tar_texi/sparse.texi(,159) @table @code
+../tar_texi/sparse.texi(,160) @item GNU.sparse.map
+../tar_texi/sparse.texi(,161) @vrindex GNU.sparse.map, extended header variable
+../tar_texi/sparse.texi(,162) Map of non-null data chunks. It is a string
consisting of
+../tar_texi/sparse.texi(,163) comma-separated values
"@var{offset},@var{size}[,@var{offset-1},@var{size-1}...]"
+../tar_texi/sparse.texi(,164) @end table
+../tar_texi/sparse.texi(,165)
+../tar_texi/sparse.texi(,166) To address the 2nd problem, the @code{name}
field in @code{ustar}
+../tar_texi/sparse.texi(,167) is replaced with a special name, constructed
using the following pattern:
+../tar_texi/sparse.texi(,168)
+../tar_texi/sparse.texi(,169) @smallexample
+../tar_texi/sparse.texi(,170) %d/GNUSparseFile.%p/%f
+../tar_texi/sparse.texi(,171) @end smallexample
+../tar_texi/sparse.texi(,172)
+../tar_texi/sparse.texi(,173) @vrindex GNU.sparse.name, extended header
variable
+../tar_texi/sparse.texi(,174) The real name of the sparse file is stored in
the variable
+../tar_texi/sparse.texi(,175) @code{GNU.sparse.name}. Thus, those
@command{tar} implementations
+../tar_texi/sparse.texi(,176) that are not aware of GNU extensions will at
least extract the files
+../tar_texi/sparse.texi(,177) into separate directories, giving the user a
possibility to expand it
+../tar_texi/sparse.texi(,178) afterwards. @xref{extracting sparse v.0.x,
Extraction of sparse
+../tar_texi/sparse.texi(,179) members in v.0.1 format}, for the detailed
description of how to
+../tar_texi/sparse.texi(,180) restore such members using non-GNU
@command{tar}s.
+../tar_texi/sparse.texi(,181)
+../tar_texi/sparse.texi(,182) The resulting @code{GNU.sparse.map} string can
be @emph{very} long.
+../tar_texi/sparse.texi(,183) Although POSIX does not impose any limit on the
length of a @code{x}
+../tar_texi/sparse.texi(,184) header variable, this possibly can confuse some
tars.
+../tar_texi/sparse.texi(,185)
+../tar_texi/sparse.texi(,186) @node PAX 1
+../tar_texi/sparse.texi(,187) @appendixsubsec PAX Format, Version 1.0
+../tar_texi/sparse.texi(,188)
+../tar_texi/sparse.texi(,189) @cindex sparse formats, v.1.0
+../tar_texi/sparse.texi(GNUTAR,190) The version @code{1.0} of sparse format
was introduced with @acronym{GNU} @command{tar}
+../tar_texi/sparse.texi(,191) 1.15.92. Its main objective was to make the
resulting file
+../tar_texi/sparse.texi(,192) extractable with little effort even by non-posix
aware @command{tar}
+../tar_texi/sparse.texi(,193) implementations. Starting from this version,
the extended header
+../tar_texi/sparse.texi(,194) preceding a sparse member always contains the
following variables that
+../tar_texi/sparse.texi(,195) identify the format being used:
+../tar_texi/sparse.texi(,196)
+../tar_texi/sparse.texi(,197) @table @code
+../tar_texi/sparse.texi(,198) @item GNU.sparse.major
+../tar_texi/sparse.texi(,199) @vrindex GNU.sparse.major, extended header
variable
+../tar_texi/sparse.texi(,200) Major version
+../tar_texi/sparse.texi(,201)
+../tar_texi/sparse.texi(,202) @item GNU.sparse.minor
+../tar_texi/sparse.texi(,203) @vrindex GNU.sparse.minor, extended header
variable
+../tar_texi/sparse.texi(,204) Minor version
+../tar_texi/sparse.texi(,205) @end table
+../tar_texi/sparse.texi(,206)
+../tar_texi/sparse.texi(,207) The @code{name} field in @code{ustar} header
contains a special name,
+../tar_texi/sparse.texi(,208) constructed using the following pattern:
+../tar_texi/sparse.texi(,209)
+../tar_texi/sparse.texi(,210) @smallexample
+../tar_texi/sparse.texi(,211) %d/GNUSparseFile.%p/%f
+../tar_texi/sparse.texi(,212) @end smallexample
+../tar_texi/sparse.texi(,213)
+../tar_texi/sparse.texi(,214) @vrindex GNU.sparse.name, extended header
variable, in v.1.0
+../tar_texi/sparse.texi(,215) @vrindex GNU.sparse.realsize, extended header
variable
+../tar_texi/sparse.texi(,216) The real name of the sparse file is stored in
the variable
+../tar_texi/sparse.texi(,217) @code{GNU.sparse.name}. The real size of the
file is stored in the
+../tar_texi/sparse.texi(,218) variable @code{GNU.sparse.realsize}.
+../tar_texi/sparse.texi(,219)
+../tar_texi/sparse.texi(,220) The sparse map itself is stored in the file data
block, preceding the actual
+../tar_texi/sparse.texi(,221) file data. It consists of a series of octal
numbers of arbitrary length, delimited
+../tar_texi/sparse.texi(,222) by newlines. The map is padded with nulls to the
nearest block boundary.
+../tar_texi/sparse.texi(,223)
+../tar_texi/sparse.texi(,224) The first number gives the number of entries in
the map. Following are map entries,
+../tar_texi/sparse.texi(,225) each one consisting of two numbers giving the
offset and size of the
+../tar_texi/sparse.texi(,226) data block it describes.
+../tar_texi/sparse.texi(,227)
+../tar_texi/sparse.texi(,228) The format is designed in such a way that
non-posix aware tars and tars not
+../tar_texi/sparse.texi(,229) supporting @code{GNU.sparse.*} keywords will
extract each sparse file
+../tar_texi/sparse.texi(,230) in its condensed form with the file map
prepended and will place it
+../tar_texi/sparse.texi(,231) into a separate directory. Then, using a simple
program it would be
+../tar_texi/sparse.texi(GNUTAR,232) possible to expand the file to its
original form even without @acronym{GNU} @command{tar}.
+../tar_texi/sparse.texi(,233) @xref{Sparse Recovery}, for the detailed
information on how to extract
+../tar_texi/sparse.texi(GNUTAR,234) sparse members without @acronym{GNU}
@command{tar}.
+../tar_texi/sparse.texi(,235)
+../tar_texi/intern.texi(,327)
+../tar_texi/intern.texi(,328) @node Snapshot Files
+../tar_texi/intern.texi(,329) @unnumberedsec Format of the Incremental
Snapshot Files
+../tar_texi/snapshot.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/snapshot.texi(,2) @c Copyright (C) 2005 Free Software Foundation,
Inc.
+../tar_texi/snapshot.texi(,3) @c Written by Sergey Poznyakoff
+../tar_texi/snapshot.texi(,4) @c This file is distributed under GFDL 1.1 or
any later version
+../tar_texi/snapshot.texi(,5) @c published by the Free Software Foundation.
+../tar_texi/snapshot.texi(,6)
+../tar_texi/snapshot.texi(,7) A @dfn{snapshot file} (or @dfn{directory
file}) is created during
+../tar_texi/snapshot.texi(,8) incremental backups (@pxref{Incremental Dumps}).
It
+../tar_texi/snapshot.texi(,9) contains the status of the filesystem at the
time of the dump and is
+../tar_texi/snapshot.texi(,10) used to determine which files were modified
since the last backup.
+../tar_texi/snapshot.texi(,11)
+../tar_texi/snapshot.texi(GNUTAR,12) @acronym{GNU} @command{tar} version
1.15.92 supports two snapshot file
+../tar_texi/snapshot.texi(,13) formats. The first format, called @dfn{format
0}, is the one used by
+../tar_texi/snapshot.texi(GNUTAR,14) @acronym{GNU} @command{tar} versions up
to 1.15.1. The second format, called @dfn{format
+../tar_texi/snapshot.texi(,15) 1} is an extended version of this format, that
contains more metadata
+../tar_texi/snapshot.texi(,16) and allows for further extensions.
+../tar_texi/snapshot.texi(,17)
+../tar_texi/snapshot.texi(,18) @samp{Format 0} snapshot file begins with a
line containing a
+../tar_texi/snapshot.texi(,19) decimal number that represents the UNIX
timestamp of the beginning of
+../tar_texi/snapshot.texi(,20) the last archivation. This line is followed by
directory metadata
+../tar_texi/snapshot.texi(,21) descriptions, one per line. Each description
has the following format:
+../tar_texi/snapshot.texi(,22)
+../tar_texi/snapshot.texi(,23) @smallexample
+../tar_texi/snapshot.texi(,24) address@hidden@var{dev} @var{inode} @var{name}
+../tar_texi/snapshot.texi(,25) @end smallexample
+../tar_texi/snapshot.texi(,26)
+../tar_texi/snapshot.texi(,27) @noindent
+../tar_texi/snapshot.texi(,28) where optional @var{nfs} is a single plus
character (@samp{+}) if this
+../tar_texi/snapshot.texi(,29) directory is located on an NFS-mounted
partition, @var{dev} and
+../tar_texi/snapshot.texi(,30) @var{inode} are the device and inode numbers of
the directory, and
+../tar_texi/snapshot.texi(,31) @var{name} is the directory name.
+../tar_texi/snapshot.texi(,32)
+../tar_texi/snapshot.texi(,33) @samp{Format 1} snapshot file begins with a
line specifying the
+../tar_texi/snapshot.texi(,34) format of the file. This line has the following
structure:
+../tar_texi/snapshot.texi(,35)
+../tar_texi/snapshot.texi(,36) @smallexample
+../tar_texi/snapshot.texi(,37) @samp{GNU address@hidden@address@hidden
+../tar_texi/snapshot.texi(,38) @end smallexample
+../tar_texi/snapshot.texi(,39)
+../tar_texi/snapshot.texi(,40) @noindent
+../tar_texi/snapshot.texi(GNUTAR,41) where @var{tar-version} is the version of
@acronym{GNU} @command{tar} implementation
+../tar_texi/snapshot.texi(,42) that created this snapshot, and
@var{incr-format-version} is the
+../tar_texi/snapshot.texi(,43) version number of the snapshot format (in this
case @samp{1}).
+../tar_texi/snapshot.texi(,44)
+../tar_texi/snapshot.texi(,45) The following line contains two decimal
numbers, representing the
+../tar_texi/snapshot.texi(,46) time of the last backup. First number is the
number of seconds, the
+../tar_texi/snapshot.texi(,47) second one is the number of nanoseconds, since
the beginning of the
+../tar_texi/snapshot.texi(,48) epoch.
+../tar_texi/snapshot.texi(,49)
+../tar_texi/snapshot.texi(,50) Following lines contain directory metadate,
one line per
+../tar_texi/snapshot.texi(,51) directory. The line format is:
+../tar_texi/snapshot.texi(,52)
+../tar_texi/snapshot.texi(,53) @smallexample
+../tar_texi/snapshot.texi(,54) address@hidden@var{mtime-sec} @var{mtime-nsec}
@var{dev} @var{inode} @var{name}
+../tar_texi/snapshot.texi(,55) @end smallexample
+../tar_texi/snapshot.texi(,56)
+../tar_texi/snapshot.texi(,57) @noindent
+../tar_texi/snapshot.texi(,58) where @var{mtime-sec} and @var{mtime-nsec}
represent the last
+../tar_texi/snapshot.texi(,59) modification time of this directory with
nanosecond precision;
+../tar_texi/snapshot.texi(,60) @var{nfs}, @var{dev}, @var{inode} and
@var{name} have the same meaning
+../tar_texi/snapshot.texi(,61) as with @samp{format 0}.
+../tar_texi/snapshot.texi(,62)
+../tar_texi/snapshot.texi(,63)
+../tar_texi/snapshot.texi(,64) @c End of snapshot.texi
+../tar_texi/snapshot.texi(,65)
+../tar_texi/snapshot.texi(,66)
+../tar_texi/intern.texi(,331)
+../tar_texi/intern.texi(,332) @node Dumpdir
+../tar_texi/intern.texi(,333) @unnumberedsec Dumpdir
+../tar_texi/dumpdir.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/dumpdir.texi(,2) @c Copyright (C) 2006 Free Software Foundation,
Inc.
+../tar_texi/dumpdir.texi(,3) @c Written by Sergey Poznyakoff
+../tar_texi/dumpdir.texi(,4) @c This file is distributed under GFDL 1.1 or any
later version
+../tar_texi/dumpdir.texi(,5) @c published by the Free Software Foundation.
+../tar_texi/dumpdir.texi(,6)
+../tar_texi/dumpdir.texi(,7) Incremental archives keep information about
contents of each
+../tar_texi/dumpdir.texi(,8) dumped directory in special data blocks called
@dfn{dumpdirs}.
+../tar_texi/dumpdir.texi(,9)
+../tar_texi/dumpdir.texi(,10) Dumpdir is a sequence of entries of the
following form:
+../tar_texi/dumpdir.texi(,11)
+../tar_texi/dumpdir.texi(,12) @smallexample
+../tar_texi/dumpdir.texi(,13) @var{C} @var{filename} \0
+../tar_texi/dumpdir.texi(,14) @end smallexample
+../tar_texi/dumpdir.texi(,15)
+../tar_texi/dumpdir.texi(,16) @noindent
+../tar_texi/dumpdir.texi(,17) where @var{C} is one of the @dfn{control codes}
described below,
+../tar_texi/dumpdir.texi(,18) @var{filename} is the name of the file @var{C}
operates upon, and
+../tar_texi/dumpdir.texi(,19) @samp{\0} represents a nul character (ASCII 0).
The white space
+../tar_texi/dumpdir.texi(,20) characters were added for readability, real
dumpdirs do not contain
+../tar_texi/dumpdir.texi(,21) them.
+../tar_texi/dumpdir.texi(,22)
+../tar_texi/dumpdir.texi(,23) Each dumpdir ends with a single nul character.
+../tar_texi/dumpdir.texi(,24)
+../tar_texi/dumpdir.texi(,25) The following table describes control codes
and their meanings:
+../tar_texi/dumpdir.texi(,26)
+../tar_texi/dumpdir.texi(,27) @table @samp
+../tar_texi/dumpdir.texi(,28) @item Y
+../tar_texi/dumpdir.texi(,29) @var{filename} is contained in the archive.
+../tar_texi/dumpdir.texi(,30)
+../tar_texi/dumpdir.texi(,31) @item N
+../tar_texi/dumpdir.texi(,32) @var{filename} was present in the directory at
the time the archive
+../tar_texi/dumpdir.texi(,33) was made, yet it was not dumped to the archive,
because it had not
+../tar_texi/dumpdir.texi(,34) changed since the last backup.
+../tar_texi/dumpdir.texi(,35)
+../tar_texi/dumpdir.texi(,36) @item D
+../tar_texi/dumpdir.texi(,37) @var{filename} is a directory.
+../tar_texi/dumpdir.texi(,38)
+../tar_texi/dumpdir.texi(,39) @item R
+../tar_texi/dumpdir.texi(,40) This code requests renaming of the
@var{filename} to the name
+../tar_texi/dumpdir.texi(,41) specified with the following @samp{T} command.
+../tar_texi/dumpdir.texi(,42)
+../tar_texi/dumpdir.texi(,43) @item T
+../tar_texi/dumpdir.texi(,44) Specify target file name for @samp{R} command
(see below).
+../tar_texi/dumpdir.texi(,45)
+../tar_texi/dumpdir.texi(,46) @item X
+../tar_texi/dumpdir.texi(,47) Specify @dfn{temporary directory} name for a
rename operation (see below).
+../tar_texi/dumpdir.texi(,48) @end table
+../tar_texi/dumpdir.texi(,49)
+../tar_texi/dumpdir.texi(,50) Codes @samp{Y}, @samp{N} and @samp{D} require
@var{filename} argument
+../tar_texi/dumpdir.texi(,51) to be a relative file name to the directory this
dumpdir describes,
+../tar_texi/dumpdir.texi(,52) whereas codes @samp{R}, @samp{T} and @samp{X}
require their argument
+../tar_texi/dumpdir.texi(,53) to be an absolute file name.
+../tar_texi/dumpdir.texi(,54)
+../tar_texi/dumpdir.texi(,55) The three codes @samp{R}, @samp{T} and @samp{X}
specify a
+../tar_texi/dumpdir.texi(,56) @dfn{renaming operation}. In the simplest case
it is:
+../tar_texi/dumpdir.texi(,57)
+../tar_texi/dumpdir.texi(,58) @smallexample
+../tar_texi/dumpdir.texi(,59) address@hidden@file{dest}\0
+../tar_texi/dumpdir.texi(,60) @end smallexample
+../tar_texi/dumpdir.texi(,61)
+../tar_texi/dumpdir.texi(,62) @noindent
+../tar_texi/dumpdir.texi(,63) which means ``rename file @file{source} to file
@file{dest}''.
+../tar_texi/dumpdir.texi(,64)
+../tar_texi/dumpdir.texi(,65) However, there are cases that require using a
@dfn{temporary
+../tar_texi/dumpdir.texi(,66) directory}. For example, consider the following
scenario:
+../tar_texi/dumpdir.texi(,67)
+../tar_texi/dumpdir.texi(,68) @enumerate 1
+../tar_texi/dumpdir.texi(,69) @item
+../tar_texi/dumpdir.texi(,70) Previous run dumped a directory @file{foo} which
contained the
+../tar_texi/dumpdir.texi(,71) following three directories:
+../tar_texi/dumpdir.texi(,72)
+../tar_texi/dumpdir.texi(,73) @smallexample
+../tar_texi/dumpdir.texi(,74) a
+../tar_texi/dumpdir.texi(,75) b
+../tar_texi/dumpdir.texi(,76) c
+../tar_texi/dumpdir.texi(,77) @end smallexample
+../tar_texi/dumpdir.texi(,78)
+../tar_texi/dumpdir.texi(,79) @item
+../tar_texi/dumpdir.texi(,80) They were renamed @emph{cyclically}, so that:
+../tar_texi/dumpdir.texi(,81)
+../tar_texi/dumpdir.texi(,82) @example
+../tar_texi/dumpdir.texi(,83) @file{a} became @file{b}
+../tar_texi/dumpdir.texi(,84) @file{b} became @file{c}
+../tar_texi/dumpdir.texi(,85) @file{c} became @file{a}
+../tar_texi/dumpdir.texi(,86) @end example
+../tar_texi/dumpdir.texi(,87)
+../tar_texi/dumpdir.texi(,88) @item
+../tar_texi/dumpdir.texi(,89) New incremental dump was made.
+../tar_texi/dumpdir.texi(,90) @end enumerate
+../tar_texi/dumpdir.texi(,91)
+../tar_texi/dumpdir.texi(,92) This case cannot be handled by three
successive renames, since
+../tar_texi/dumpdir.texi(,93) renaming @file{a} to @file{b} will destroy
existing directory.
+../tar_texi/dumpdir.texi(GNUTAR,94) To handle such case a temporary directory
is required. @acronym{GNU} @command{tar}
+../tar_texi/dumpdir.texi(,95) will create the following dumpdir (newlines have
been added for
+../tar_texi/dumpdir.texi(,96) readability):
+../tar_texi/dumpdir.texi(,97)
+../tar_texi/dumpdir.texi(,98) @smallexample
+../tar_texi/dumpdir.texi(,99) @group
+../tar_texi/dumpdir.texi(,100) Xfoo\0
+../tar_texi/dumpdir.texi(,101) Rfoo/a\0T\0
+../tar_texi/dumpdir.texi(,102) Rfoo/b\0Tfoo/c\0
+../tar_texi/dumpdir.texi(,103) Rfoo/c\0Tfoo/a\0
+../tar_texi/dumpdir.texi(,104) R\0Tfoo/a\0
+../tar_texi/dumpdir.texi(,105) @end group
+../tar_texi/dumpdir.texi(,106) @end smallexample
+../tar_texi/dumpdir.texi(,107)
+../tar_texi/dumpdir.texi(,108) The first command, @samp{Xfoo\0}, instructs
the extractor to create a
+../tar_texi/dumpdir.texi(,109) temporary directory in the directory
@file{foo}. Second command,
+../tar_texi/dumpdir.texi(,110) @samp{Rfoo/aT\0}, says ``rename file
@file{foo/a} to the temporary
+../tar_texi/dumpdir.texi(,111) directory that has just been created'' (empty
file name after a
+../tar_texi/dumpdir.texi(,112) command means use temporary directory). Third
and fourth commands
+../tar_texi/dumpdir.texi(,113) work as usual, and, finally, the last command,
@samp{R\0Tfoo/a\0}
+../tar_texi/dumpdir.texi(,114) tells tar to rename the temporary directory to
@file{foo/a}.
+../tar_texi/dumpdir.texi(,115)
+../tar_texi/dumpdir.texi(,116) The exact placement of a dumpdir in the
archive depends on the
+../tar_texi/dumpdir.texi(,117) archive format (@pxref{Formats}):
+../tar_texi/dumpdir.texi(,118)
+../tar_texi/dumpdir.texi(,119) @itemize
+../tar_texi/dumpdir.texi(,120) @item PAX archives
+../tar_texi/dumpdir.texi(,121)
+../tar_texi/dumpdir.texi(,122) In PAX archives, dumpdir is stored in the
extended header of the
+../tar_texi/dumpdir.texi(,123) corresponding directory, in variable
@code{GNU.dumpdir}.
+../tar_texi/dumpdir.texi(,124)
+../tar_texi/dumpdir.texi(,125) @item GNU and old GNU archives
+../tar_texi/dumpdir.texi(,126)
+../tar_texi/dumpdir.texi(,127) These formats implement special header type
@samp{D}, which is similar
+../tar_texi/dumpdir.texi(,128) to ustar header @samp{5} (directory), except
that it preceeds a data
+../tar_texi/dumpdir.texi(,129) block containing the dumpdir.
+../tar_texi/dumpdir.texi(,130) @end itemize
+../tar_texi/dumpdir.texi(,131)
+../tar_texi/dumpdir.texi(,132) @c End of dumpdir.texi
+../tar_texi/intern.texi(,335)
+../tar_texi/tar.texi(,10777)
+../tar_texi/tar.texi(,10778) @node Genfile
+../tar_texi/tar.texi(,10779) @appendix Genfile
+../tar_texi/genfile.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/genfile.texi(,2) @c Copyright (C) 2005, 2006 Free Software
Foundation, Inc.
+../tar_texi/genfile.texi(,3) @c Written by Sergey Poznyakoff
+../tar_texi/genfile.texi(,4) @c This file is distributed under GFDL 1.1 or any
later version
+../tar_texi/genfile.texi(,5) @c published by the Free Software Foundation.
+../tar_texi/genfile.texi(,6)
+../tar_texi/genfile.texi(,7) @cindex genfile
+../tar_texi/genfile.texi(,8) This appendix describes @command{genfile}, an
auxiliary program
+../tar_texi/genfile.texi(,9) used in the GNU tar testsuite. If you are not
interested in developing
+../tar_texi/genfile.texi(,10) GNU tar, skip this appendix.
+../tar_texi/genfile.texi(,11)
+../tar_texi/genfile.texi(,12) Initially, @command{genfile} was used to
generate data files for
+../tar_texi/genfile.texi(,13) the testsuite, hence its name. However, new
operation modes were being
+../tar_texi/genfile.texi(,14) implemented as the testsuite grew more
sophisticated, and now
+../tar_texi/genfile.texi(,15) @command{genfile} is a multi-purpose instrument.
+../tar_texi/genfile.texi(,16)
+../tar_texi/genfile.texi(,17) There are three basic operation modes:
+../tar_texi/genfile.texi(,18)
+../tar_texi/genfile.texi(,19) @table @asis
+../tar_texi/genfile.texi(,20) @item File Generation
+../tar_texi/genfile.texi(,21) This is the default mode. In this mode,
@command{genfile}
+../tar_texi/genfile.texi(,22) generates data files.
+../tar_texi/genfile.texi(,23)
+../tar_texi/genfile.texi(,24) @item File Status
+../tar_texi/genfile.texi(,25) In this mode @command{genfile} displays
status of specified files.
+../tar_texi/genfile.texi(,26)
+../tar_texi/genfile.texi(,27) @item Synchronous Execution.
+../tar_texi/genfile.texi(,28) In this mode @command{genfile} executes the
given program with
+../tar_texi/genfile.texi(,29) @option{--checkpoint} option and executes a set
of actions when
+../tar_texi/genfile.texi(,30) specified checkpoints are reached.
+../tar_texi/genfile.texi(,31) @end table
+../tar_texi/genfile.texi(,32)
+../tar_texi/genfile.texi(,33) @menu
+../tar_texi/genfile.texi(,34) * Generate Mode:: File Generation Mode.
+../tar_texi/genfile.texi(,35) * Status Mode:: File Status Mode.
+../tar_texi/genfile.texi(,36) * Exec Mode:: Synchronous Execution mode.
+../tar_texi/genfile.texi(,37) @end menu
+../tar_texi/genfile.texi(,38)
+../tar_texi/genfile.texi(,39) @node Generate Mode
+../tar_texi/genfile.texi(,40) @appendixsec Generate Mode
+../tar_texi/genfile.texi(,41)
+../tar_texi/genfile.texi(,42) @cindex Generate Mode, @command{genfile}
+../tar_texi/genfile.texi(,43) @cindex @command{genfile}, generate mode
+../tar_texi/genfile.texi(,44) @cindex @command{genfile}, create file
+../tar_texi/genfile.texi(,45) In this mode @command{genfile} creates a
data file for the test
+../tar_texi/genfile.texi(,46) suite. The size of the file is given with the
@option{--length}
+../tar_texi/genfile.texi(,47) (@option{-l}) option. By default the file
contents is written to the
+../tar_texi/genfile.texi(,48) standard output, this can be changed using
@option{--file}
+../tar_texi/genfile.texi(,49) (@option{-f}) command line option. Thus, the
following two commands
+../tar_texi/genfile.texi(,50) are equivalent:
+../tar_texi/genfile.texi(,51)
+../tar_texi/genfile.texi(,52) @smallexample
+../tar_texi/genfile.texi(,53) @group
+../tar_texi/genfile.texi(,54) genfile --length 100 > outfile
+../tar_texi/genfile.texi(,55) genfile --length 100 --file outfile
+../tar_texi/genfile.texi(,56) @end group
+../tar_texi/genfile.texi(,57) @end smallexample
+../tar_texi/genfile.texi(,58)
+../tar_texi/genfile.texi(,59) If @option{--length} is not given,
@command{genfile} will
+../tar_texi/genfile.texi(,60) generate an empty (zero-length) file.
+../tar_texi/genfile.texi(,61)
+../tar_texi/genfile.texi(,62) @cindex @command{genfile}, reading a list of
file names
+../tar_texi/genfile.texi(,63) You can instruct @command{genfile} to create
several files at one
+../tar_texi/genfile.texi(,64) go, by giving it @option{--files-from}
(@option{-T}) option followed
+../tar_texi/genfile.texi(,65) by a name of file containing a list of file
names. Using dash
+../tar_texi/genfile.texi(,66) (@samp{-}) instead of the file name causes
@command{genfile} to read
+../tar_texi/genfile.texi(,67) file list from the standard input. For example:
+../tar_texi/genfile.texi(,68)
+../tar_texi/genfile.texi(,69) @smallexample
+../tar_texi/genfile.texi(,70) @group
+../tar_texi/genfile.texi(,71) # Read file names from file @file{file.list}
+../tar_texi/genfile.texi(,72) genfile --files-from file.list
+../tar_texi/genfile.texi(,73) # Read file names from standard input
+../tar_texi/genfile.texi(,74) genfile --files-from -
+../tar_texi/genfile.texi(,75) @end group
+../tar_texi/genfile.texi(,76) @end smallexample
+../tar_texi/genfile.texi(,77)
+../tar_texi/genfile.texi(,78) @cindex File lists separated by NUL characters
+../tar_texi/genfile.texi(,79) The list file is supposed to contain one
file name per line. To
+../tar_texi/genfile.texi(,80) use file lists separated by ASCII NUL character,
use @option{--null}
+../tar_texi/genfile.texi(,81) (@option{-0}) command line option:
+../tar_texi/genfile.texi(,82)
+../tar_texi/genfile.texi(,83) @smallexample
+../tar_texi/genfile.texi(,84) genfile --null --files-from file.list
+../tar_texi/genfile.texi(,85) @end smallexample
+../tar_texi/genfile.texi(,86)
+../tar_texi/genfile.texi(,87) @cindex pattern, @command{genfile}
+../tar_texi/genfile.texi(,88) The default data pattern for filling the
generated file consists
+../tar_texi/genfile.texi(,89) of first 256 letters of ASCII code, repeated
enough times to fill the
+../tar_texi/genfile.texi(,90) entire file. This behavior can be changed with
@option{--pattern}
+../tar_texi/genfile.texi(,91) option. This option takes a mandatory argument,
specifying pattern
+../tar_texi/genfile.texi(,92) name to use. Currently two patterns are
implemented:
+../tar_texi/genfile.texi(,93)
+../tar_texi/genfile.texi(,94) @table @option
+../tar_texi/genfile.texi(,95) @item --pattern=default
+../tar_texi/genfile.texi(,96) The default pattern as described above.
+../tar_texi/genfile.texi(,97)
+../tar_texi/genfile.texi(,98) @item --pattern=zero
+../tar_texi/genfile.texi(,99) Fills the file with zeroes.
+../tar_texi/genfile.texi(,100) @end table
+../tar_texi/genfile.texi(,101)
+../tar_texi/genfile.texi(,102) If no file name was given, the program
exits with the code
+../tar_texi/genfile.texi(,103) @code{0}. Otherwise, it exits with @code{0}
only if it was able to
+../tar_texi/genfile.texi(,104) create a file of the specified length.
+../tar_texi/genfile.texi(,105)
+../tar_texi/genfile.texi(,106) @cindex Sparse files, creating using
@command{genfile}
+../tar_texi/genfile.texi(,107) @cindex @command{genfile}, creating sparse files
+../tar_texi/genfile.texi(,108) Special option @option{--sparse}
(@option{-s}) instructs
+../tar_texi/genfile.texi(,109) @command{genfile} to create a sparse file.
Sparse files consist of
+../tar_texi/genfile.texi(,110) @dfn{data fragments}, separated by @dfn{holes}
or blocks of zeros. On
+../tar_texi/genfile.texi(,111) many operating systems, actual disk storage is
not allocated for
+../tar_texi/genfile.texi(,112) holes, but they are counted in the length of
the file. To create a
+../tar_texi/genfile.texi(,113) sparse file, @command{genfile} should know
where to put data fragments,
+../tar_texi/genfile.texi(,114) and what data to use to fill them. So, when
@option{--sparse} is given
+../tar_texi/genfile.texi(,115) the rest of the command line specifies a
so-called @dfn{file map}.
+../tar_texi/genfile.texi(,116)
+../tar_texi/genfile.texi(,117) The file map consists of any number of
@dfn{fragment
+../tar_texi/genfile.texi(,118) descriptors}. Each descriptor is composed of
two values: a number,
+../tar_texi/genfile.texi(,119) specifying fragment offset from the end of the
previous fragment or,
+../tar_texi/genfile.texi(,120) for the very first fragment, from the beginning
of the file, and
+../tar_texi/genfile.texi(,121) @dfn{contents string}, i.e. a string of
characters, specifying the
+../tar_texi/genfile.texi(,122) pattern to fill the fragment with. File offset
can be suffixed with
+../tar_texi/genfile.texi(,123) the following quantifiers:
+../tar_texi/genfile.texi(,124)
+../tar_texi/genfile.texi(,125) @table @samp
+../tar_texi/genfile.texi(,126) @item k
+../tar_texi/genfile.texi(,127) @itemx K
+../tar_texi/genfile.texi(,128) The number is expressed in kilobytes.
+../tar_texi/genfile.texi(,129) @item m
+../tar_texi/genfile.texi(,130) @itemx M
+../tar_texi/genfile.texi(,131) The number is expressed in megabytes.
+../tar_texi/genfile.texi(,132) @item g
+../tar_texi/genfile.texi(,133) @itemx G
+../tar_texi/genfile.texi(,134) The number is expressed in gigabytes.
+../tar_texi/genfile.texi(,135) @end table
+../tar_texi/genfile.texi(,136)
+../tar_texi/genfile.texi(,137) For each letter in contents string
@command{genfile} will generate
+../tar_texi/genfile.texi(,138) a @dfn{block} of data, filled with this letter
and will write it to
+../tar_texi/genfile.texi(,139) the fragment. The size of block is given by
@option{--block-size}
+../tar_texi/genfile.texi(,140) option. It defaults to 512. Thus, if the string
consists of @var{n}
+../tar_texi/genfile.texi(,141) characters, the resulting file fragment will
contain
+../tar_texi/genfile.texi(,142) @address@hidden@var{block-size}} of data.
+../tar_texi/genfile.texi(,143)
+../tar_texi/genfile.texi(,144) Last fragment descriptor can have only file
offset part. In this
+../tar_texi/genfile.texi(,145) case @command{genfile} will create a hole at
the end of the file up to
+../tar_texi/genfile.texi(,146) the given offset.
+../tar_texi/genfile.texi(,147)
+../tar_texi/genfile.texi(,148) For example, consider the following
invocation:
+../tar_texi/genfile.texi(,149)
+../tar_texi/genfile.texi(,150) @smallexample
+../tar_texi/genfile.texi(,151) genfile --sparse --file sparsefile 0 ABCD 1M
EFGHI 2000K
+../tar_texi/genfile.texi(,152) @end smallexample
+../tar_texi/genfile.texi(,153)
+../tar_texi/genfile.texi(,154) @noindent
+../tar_texi/genfile.texi(,155) It will create 3101184-bytes long file of the
following structure:
+../tar_texi/genfile.texi(,156)
+../tar_texi/genfile.texi(,157) @multitable @columnfractions .35 .20 .45
+../tar_texi/genfile.texi(,158) @item Offset @tab Length @tab Contents
+../tar_texi/genfile.texi(,159) @item 0 @tab 4*512=2048 @tab Four
512-byte blocks, filled with
+../tar_texi/genfile.texi(,160) letters @samp{A}, @samp{B}, @samp{C} and
@samp{D}.
+../tar_texi/genfile.texi(,161) @item 2048 @tab 1046528 @tab Zero bytes
+../tar_texi/genfile.texi(,162) @item 1050624 @tab 5*512=2560 @tab Five
blocks, filled with letters
+../tar_texi/genfile.texi(,163) @samp{E}, @samp{F}, @samp{G}, @samp{H},
@samp{I}.
+../tar_texi/genfile.texi(,164) @item 1053184 @tab 2048000 @tab Zero bytes
+../tar_texi/genfile.texi(,165) @end multitable
+../tar_texi/genfile.texi(,166)
+../tar_texi/genfile.texi(,167) The exit code of @command{genfile --status}
command is @code{0}
+../tar_texi/genfile.texi(,168) only if created file is actually sparse.
+../tar_texi/genfile.texi(,169)
+../tar_texi/genfile.texi(,170) @node Status Mode
+../tar_texi/genfile.texi(,171) @appendixsec Status Mode
+../tar_texi/genfile.texi(,172)
+../tar_texi/genfile.texi(,173) In status mode, @command{genfile} prints
file system status for
+../tar_texi/genfile.texi(,174) each file specified in the command line. This
mode is toggled by
+../tar_texi/genfile.texi(,175) @option{--stat} (@option{-S}) command line
option. An optional argument to this
+../tar_texi/genfile.texi(,176) option specifies output @dfn{format}: a
comma-separated list of
+../tar_texi/genfile.texi(,177) @code{struct stat} fields to be displayed. This
list can contain
+../tar_texi/genfile.texi(FIXME,179) following identifiers @allow-recursion
+../tar_texi/genfile.texi(FIXME,179) @quote-arg
+../tar_texi/genfile.texi(FIXME,179) :
+../tar_texi/genfile.texi(,180)
+../tar_texi/genfile.texi(,181) @table @asis
+../tar_texi/genfile.texi(,182) @item name
+../tar_texi/genfile.texi(,183) The file name.
+../tar_texi/genfile.texi(,184)
+../tar_texi/genfile.texi(,185) @item dev
+../tar_texi/genfile.texi(,186) @itemx st_dev
+../tar_texi/genfile.texi(,187) Device number in decimal.
+../tar_texi/genfile.texi(,188)
+../tar_texi/genfile.texi(,189) @item ino
+../tar_texi/genfile.texi(,190) @itemx st_ino
+../tar_texi/genfile.texi(,191) Inode number.
+../tar_texi/genfile.texi(,192)
+../tar_texi/genfile.texi(,193) @item address@hidden
+../tar_texi/genfile.texi(,194) @itemx address@hidden
+../tar_texi/genfile.texi(,195) File mode in octal. Optional @var{number}
specifies octal mask to
+../tar_texi/genfile.texi(,196) be applied to the mode before outputting. For
example, @code{--stat
+../tar_texi/genfile.texi(,197) mode.777} will preserve lower nine bits of it.
Notice, that you can
+../tar_texi/genfile.texi(,198) use any punctuation caracter in place of
@samp{.}.
+../tar_texi/genfile.texi(,199)
+../tar_texi/genfile.texi(,200) @item nlink
+../tar_texi/genfile.texi(,201) @itemx st_nlink
+../tar_texi/genfile.texi(,202) Number of hard links.
+../tar_texi/genfile.texi(,203)
+../tar_texi/genfile.texi(,204) @item uid
+../tar_texi/genfile.texi(,205) @itemx st_uid
+../tar_texi/genfile.texi(,206) User ID of owner.
+../tar_texi/genfile.texi(,207)
+../tar_texi/genfile.texi(,208) @item gid
+../tar_texi/genfile.texi(,209) @itemx st_gid
+../tar_texi/genfile.texi(,210) Group ID of owner.
+../tar_texi/genfile.texi(,211)
+../tar_texi/genfile.texi(,212) @item size
+../tar_texi/genfile.texi(,213) @itemx st_size
+../tar_texi/genfile.texi(,214) File size in decimal.
+../tar_texi/genfile.texi(,215)
+../tar_texi/genfile.texi(,216) @item blksize
+../tar_texi/genfile.texi(,217) @itemx st_blksize
+../tar_texi/genfile.texi(,218) The size in bytes of each file block.
+../tar_texi/genfile.texi(,219)
+../tar_texi/genfile.texi(,220) @item blocks
+../tar_texi/genfile.texi(,221) @itemx st_blocks
+../tar_texi/genfile.texi(,222) Number of blocks allocated.
+../tar_texi/genfile.texi(,223)
+../tar_texi/genfile.texi(,224) @item atime
+../tar_texi/genfile.texi(,225) @itemx st_atime
+../tar_texi/genfile.texi(,226) Time of last access.
+../tar_texi/genfile.texi(,227)
+../tar_texi/genfile.texi(,228) @item mtime
+../tar_texi/genfile.texi(,229) @itemx st_mtime
+../tar_texi/genfile.texi(,230) Time of last modification
+../tar_texi/genfile.texi(,231)
+../tar_texi/genfile.texi(,232) @item ctime
+../tar_texi/genfile.texi(,233) @itemx st_ctime
+../tar_texi/genfile.texi(,234) Time of last status change
+../tar_texi/genfile.texi(,235)
+../tar_texi/genfile.texi(,236) @item sparse
+../tar_texi/genfile.texi(,237) A boolean value indicating whether the file
is @samp{sparse}.
+../tar_texi/genfile.texi(,238) @end table
+../tar_texi/genfile.texi(,239)
+../tar_texi/genfile.texi(,240) Modification times are displayed in
@acronym{UTC} as
+../tar_texi/genfile.texi(,241) @acronym{UNIX} timestamps, unless suffixed with
@samp{H} (for
+../tar_texi/genfile.texi(,242) ``human-readable''), as in @samp{ctimeH}, in
which case usual
+../tar_texi/genfile.texi(,243) @code{tar tv} output format is used.
+../tar_texi/genfile.texi(,244)
+../tar_texi/genfile.texi(,245) The default output format is:
@samp{name,dev,ino,mode,
+../tar_texi/genfile.texi(,246)
nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}.
+../tar_texi/genfile.texi(,247)
+../tar_texi/genfile.texi(,248) For example, the following command will
display file names and
+../tar_texi/genfile.texi(,249) corresponding times of last access for each
file in the current working
+../tar_texi/genfile.texi(,250) directory:
+../tar_texi/genfile.texi(,251)
+../tar_texi/genfile.texi(,252) @smallexample
+../tar_texi/genfile.texi(,253) genfile --stat=name,atime *
+../tar_texi/genfile.texi(,254) @end smallexample
+../tar_texi/genfile.texi(,255)
+../tar_texi/genfile.texi(,256) @node Exec Mode
+../tar_texi/genfile.texi(,257) @appendixsec Exec Mode
+../tar_texi/genfile.texi(,258)
+../tar_texi/genfile.texi(,259) @cindex Exec Mode, @command{genfile}
+../tar_texi/genfile.texi(,260) This mode is designed for testing the
behavior of @code{paxutils}
+../tar_texi/genfile.texi(,261) commands when some of the files change during
archiving. It is an
+../tar_texi/genfile.texi(,262) experimental mode.
+../tar_texi/genfile.texi(,263)
+../tar_texi/genfile.texi(,264) The @samp{Exec Mode} is toggled by
@option{--run} command line
+../tar_texi/genfile.texi(,265) option (or its alias @option{-r}). The argument
to this option gives
+../tar_texi/genfile.texi(,266) the command line to be executed. The actual
command line is
+../tar_texi/genfile.texi(,267) constructed by inserting @option{--checkpoint}
option between the
+../tar_texi/genfile.texi(,268) command name and its first argument (if any).
Due to this, the
+../tar_texi/genfile.texi(,269) argument to @option{--run} may not use
traditional @command{tar}
+../tar_texi/genfile.texi(,270) option syntax, i.e. the following is wrong:
+../tar_texi/genfile.texi(,271)
+../tar_texi/genfile.texi(,272) @smallexample
+../tar_texi/genfile.texi(,273) # Wrong!
+../tar_texi/genfile.texi(,274) genfile --run 'tar cf foo bar'
+../tar_texi/genfile.texi(,275) @end smallexample
+../tar_texi/genfile.texi(,276)
+../tar_texi/genfile.texi(,277) @noindent
+../tar_texi/genfile.texi(,278)
+../tar_texi/genfile.texi(,279) Use the following syntax instead:
+../tar_texi/genfile.texi(,280)
+../tar_texi/genfile.texi(,281) @smallexample
+../tar_texi/genfile.texi(,282) genfile --run 'tar -cf foo bar'
+../tar_texi/genfile.texi(,283) @end smallexample
+../tar_texi/genfile.texi(,284)
+../tar_texi/genfile.texi(,285) The rest of command line after
@option{--run} or its equivalent
+../tar_texi/genfile.texi(,286) specifies checkpoint values and actions to be
executed upon reaching
+../tar_texi/genfile.texi(,287) them. Checkpoint values are introduced with
@option{--checkpoint}
+../tar_texi/genfile.texi(,288) command line option. Argument to this option is
the number of
+../tar_texi/genfile.texi(,289) checkpoint in decimal.
+../tar_texi/genfile.texi(,290)
+../tar_texi/genfile.texi(,291) Any number of @dfn{actions} may be
specified after a
+../tar_texi/genfile.texi(,292) checkpoint. Available actions are
+../tar_texi/genfile.texi(,293)
+../tar_texi/genfile.texi(,294) @table @option
+../tar_texi/genfile.texi(,295) @item --cut @var{file}
+../tar_texi/genfile.texi(,296) @itemx --truncate @var{file}
+../tar_texi/genfile.texi(,297) Truncate @var{file} to the size specified
by previous
+../tar_texi/genfile.texi(,298) @option{--length} option (or 0, if it is not
given).
+../tar_texi/genfile.texi(,299)
+../tar_texi/genfile.texi(,300) @item --append @var{file}
+../tar_texi/genfile.texi(,301) Append data to @var{file}. The size of data
and its pattern are
+../tar_texi/genfile.texi(,302) given by previous @option{--length} and
@option{pattern} options.
+../tar_texi/genfile.texi(,303)
+../tar_texi/genfile.texi(,304) @item --touch @var{file}
+../tar_texi/genfile.texi(,305) Update the access and modification times of
@var{file}. These
+../tar_texi/genfile.texi(,306) timestamps are changed to the current time,
unless @option{--date}
+../tar_texi/genfile.texi(,307) option was given, in which case they are
changed to the specified
+../tar_texi/genfile.texi(,308) time. Argument to @option{--date} option is a
date specification in
+../tar_texi/genfile.texi(,309) an almost arbitrary format (@pxref{Date input
formats}).
+../tar_texi/genfile.texi(,310)
+../tar_texi/genfile.texi(,311) @item --exec @var{command}
+../tar_texi/genfile.texi(,312) Execute given shell command.
+../tar_texi/genfile.texi(,313)
+../tar_texi/genfile.texi(,314) @end table
+../tar_texi/genfile.texi(,315)
+../tar_texi/genfile.texi(,316) Option @option{--verbose} instructs
@command{genfile} to print on
+../tar_texi/genfile.texi(,317) standard output notifications about checkpoints
being executed and to
+../tar_texi/genfile.texi(,318) verbosely describe exit status of the command.
+../tar_texi/genfile.texi(,319)
+../tar_texi/genfile.texi(,320) While the command is being executed its
standard output remains
+../tar_texi/genfile.texi(,321) connected to descriptor 1. All messages it
prints to file descriptor
+../tar_texi/genfile.texi(,322) 2, except checkpoint notifications, are
forwarded to standard
+../tar_texi/genfile.texi(,323) error.
+../tar_texi/genfile.texi(,324)
+../tar_texi/genfile.texi(,325) @command{Genfile} exits with the exit
status of the executed command.
+../tar_texi/tar.texi(,10781)
+../tar_texi/tar.texi(,10782) @node Free Software Needs Free Documentation
+../tar_texi/tar.texi(,10783) @appendix Free Software Needs Free Documentation
+../tar_texi/freemanuals.texi(,1) @cindex free documentation
+../tar_texi/freemanuals.texi(,2)
+../tar_texi/freemanuals.texi(,3) The biggest deficiency in the free software
community today is not in
+../tar_texi/freemanuals.texi(,4) the software---it is the lack of good free
documentation that we can
+../tar_texi/freemanuals.texi(,5) include with the free software. Many of our
most important
+../tar_texi/freemanuals.texi(,6) programs do not come with free reference
manuals and free introductory
+../tar_texi/freemanuals.texi(,7) texts. Documentation is an essential part of
any software package;
+../tar_texi/freemanuals.texi(,8) when an important free software package does
not come with a free
+../tar_texi/freemanuals.texi(,9) manual and a free tutorial, that is a major
gap. We have many such
+../tar_texi/freemanuals.texi(,10) gaps today.
+../tar_texi/freemanuals.texi(,11)
+../tar_texi/freemanuals.texi(,12) Consider Perl, for instance. The tutorial
manuals that people
+../tar_texi/freemanuals.texi(,13) normally use are non-free. How did this
come about? Because the
+../tar_texi/freemanuals.texi(,14) authors of those manuals published them with
restrictive terms---no
+../tar_texi/freemanuals.texi(,15) copying, no modification, source files not
available---which exclude
+../tar_texi/freemanuals.texi(,16) them from the free software world.
+../tar_texi/freemanuals.texi(,17)
+../tar_texi/freemanuals.texi(,18) That wasn't the first time this sort of
thing happened, and it was far
+../tar_texi/freemanuals.texi(,19) from the last. Many times we have heard a
GNU user eagerly describe a
+../tar_texi/freemanuals.texi(,20) manual that he is writing, his intended
contribution to the community,
+../tar_texi/freemanuals.texi(,21) only to learn that he had ruined everything
by signing a publication
+../tar_texi/freemanuals.texi(,22) contract to make it non-free.
+../tar_texi/freemanuals.texi(,23)
+../tar_texi/freemanuals.texi(,24) Free documentation, like free software, is a
matter of freedom, not
+../tar_texi/freemanuals.texi(,25) price. The problem with the non-free manual
is not that publishers
+../tar_texi/freemanuals.texi(,26) charge a price for printed copies---that in
itself is fine. (The Free
+../tar_texi/freemanuals.texi(,27) Software Foundation sells printed copies of
manuals, too.) The
+../tar_texi/freemanuals.texi(,28) problem is the restrictions on the use of
the manual. Free manuals
+../tar_texi/freemanuals.texi(,29) are available in source code form, and give
you permission to copy and
+../tar_texi/freemanuals.texi(,30) modify. Non-free manuals do not allow this.
+../tar_texi/freemanuals.texi(,31)
+../tar_texi/freemanuals.texi(,32) The criteria of freedom for a free manual
are roughly the same as for
+../tar_texi/freemanuals.texi(,33) free software. Redistribution (including
the normal kinds of
+../tar_texi/freemanuals.texi(,34) commercial redistribution) must be
permitted, so that the manual can
+../tar_texi/freemanuals.texi(,35) accompany every copy of the program, both
on-line and on paper.
+../tar_texi/freemanuals.texi(,36)
+../tar_texi/freemanuals.texi(,37) Permission for modification of the technical
content is crucial too.
+../tar_texi/freemanuals.texi(,38) When people modify the software, adding or
changing features, if they
+../tar_texi/freemanuals.texi(,39) are conscientious they will change the
manual too---so they can
+../tar_texi/freemanuals.texi(,40) provide accurate and clear documentation for
the modified program. A
+../tar_texi/freemanuals.texi(,41) manual that leaves you no choice but to
write a new manual to document
+../tar_texi/freemanuals.texi(,42) a changed version of the program is not
really available to our
+../tar_texi/freemanuals.texi(,43) community.
+../tar_texi/freemanuals.texi(,44)
+../tar_texi/freemanuals.texi(,45) Some kinds of limits on the way modification
is handled are
+../tar_texi/freemanuals.texi(,46) acceptable. For example, requirements to
preserve the original
+../tar_texi/freemanuals.texi(,47) author's copyright notice, the distribution
terms, or the list of
+../tar_texi/freemanuals.texi(,48) authors, are ok. It is also no problem to
require modified versions
+../tar_texi/freemanuals.texi(,49) to include notice that they were modified.
Even entire sections that
+../tar_texi/freemanuals.texi(,50) may not be deleted or changed are
acceptable, as long as they deal
+../tar_texi/freemanuals.texi(,51) with nontechnical topics (like this one).
These kinds of restrictions
+../tar_texi/freemanuals.texi(,52) are acceptable because they don't obstruct
the community's normal use
+../tar_texi/freemanuals.texi(,53) of the manual.
+../tar_texi/freemanuals.texi(,54)
+../tar_texi/freemanuals.texi(,55) However, it must be possible to modify all
the @emph{technical}
+../tar_texi/freemanuals.texi(,56) content of the manual, and then distribute
the result in all the usual
+../tar_texi/freemanuals.texi(,57) media, through all the usual channels.
Otherwise, the restrictions
+../tar_texi/freemanuals.texi(,58) obstruct the use of the manual, it is not
free, and we need another
+../tar_texi/freemanuals.texi(,59) manual to replace it.
+../tar_texi/freemanuals.texi(,60)
+../tar_texi/freemanuals.texi(,61) Please spread the word about this issue.
Our community continues to
+../tar_texi/freemanuals.texi(,62) lose manuals to proprietary publishing. If
we spread the word that
+../tar_texi/freemanuals.texi(,63) free software needs free reference manuals
and free tutorials, perhaps
+../tar_texi/freemanuals.texi(,64) the next person who wants to contribute by
writing documentation will
+../tar_texi/freemanuals.texi(,65) realize, before it is too late, that only
free manuals contribute to
+../tar_texi/freemanuals.texi(,66) the free software community.
+../tar_texi/freemanuals.texi(,67)
+../tar_texi/freemanuals.texi(,68) If you are writing documentation, please
insist on publishing it under
+../tar_texi/freemanuals.texi(,69) the GNU Free Documentation License or
another free documentation
+../tar_texi/freemanuals.texi(,70) license. Remember that this decision
requires your approval---you
+../tar_texi/freemanuals.texi(,71) don't have to let the publisher decide.
Some commercial publishers
+../tar_texi/freemanuals.texi(,72) will use a free license if you insist, but
they will not propose the
+../tar_texi/freemanuals.texi(,73) option; it is up to you to raise the issue
and say firmly that this is
+../tar_texi/freemanuals.texi(,74) what you want. If the publisher you are
dealing with refuses, please
+../tar_texi/freemanuals.texi(,75) try other publishers. If you're not sure
whether a proposed license
+../tar_texi/freemanuals.texi(,76) is free, write to @email{licensing@@gnu.org}.
+../tar_texi/freemanuals.texi(,77)
+../tar_texi/freemanuals.texi(,78) You can encourage commercial publishers to
sell more free, copylefted
+../tar_texi/freemanuals.texi(,79) manuals and tutorials by buying them, and
particularly by buying
+../tar_texi/freemanuals.texi(,80) copies from the publishers that paid for
their writing or for major
+../tar_texi/freemanuals.texi(,81) improvements. Meanwhile, try to avoid
buying non-free documentation
+../tar_texi/freemanuals.texi(,82) at all. Check the distribution terms of a
manual before you buy it,
+../tar_texi/freemanuals.texi(,83) and insist that whoever seeks your business
must respect your freedom.
+../tar_texi/freemanuals.texi(,84) Check the history of the book, and try
reward the publishers that have
+../tar_texi/freemanuals.texi(,85) paid or pay the authors to work on it.
+../tar_texi/freemanuals.texi(,86)
+../tar_texi/freemanuals.texi(,87) The Free Software Foundation maintains a
list of free documentation
+../tar_texi/freemanuals.texi(,88) published by other publishers, at
+../tar_texi/freemanuals.texi(,89)
@url{http://www.fsf.org/doc/other-free-books.html}.
+../tar_texi/tar.texi(,10785)
+../tar_texi/tar.texi(,10786) @node Copying This Manual
+../tar_texi/tar.texi(,10787) @appendix Copying This Manual
+../tar_texi/tar.texi(,10788)
+../tar_texi/tar.texi(,10789) @menu
+../tar_texi/tar.texi(,10790) * GNU Free Documentation License:: License for
copying this manual
+../tar_texi/tar.texi(,10791) @end menu
+../tar_texi/tar.texi(,10792)
+../tar_texi/fdl.texi(,1)
+../tar_texi/fdl.texi(,2) @node GNU Free Documentation License
+../tar_texi/fdl.texi(,3) @appendixsec GNU Free Documentation License
+../tar_texi/fdl.texi(,4)
+../tar_texi/fdl.texi(,5) @cindex FDL, GNU Free Documentation License
+../tar_texi/fdl.texi(,6) @center Version 1.2, November 2002
+../tar_texi/fdl.texi(,7)
+../tar_texi/fdl.texi(,8) @display
+../tar_texi/fdl.texi(,9) Copyright @copyright{} 2000,2001,2002 Free Software
Foundation, Inc.
+../tar_texi/fdl.texi(,10) 51 Franklin St, Fifth Floor, Boston, MA 02110-1301,
USA
+../tar_texi/fdl.texi(,11)
+../tar_texi/fdl.texi(,12) Everyone is permitted to copy and distribute
verbatim copies
+../tar_texi/fdl.texi(,13) of this license document, but changing it is not
allowed.
+../tar_texi/fdl.texi(,14) @end display
+../tar_texi/fdl.texi(,15)
+../tar_texi/fdl.texi(,16) @enumerate 0
+../tar_texi/fdl.texi(,17) @item
+../tar_texi/fdl.texi(,18) PREAMBLE
+../tar_texi/fdl.texi(,19)
+../tar_texi/fdl.texi(,20) The purpose of this License is to make a manual,
textbook, or other
+../tar_texi/fdl.texi(,21) functional and useful document @dfn{free} in the
sense of freedom: to
+../tar_texi/fdl.texi(,22) assure everyone the effective freedom to copy and
redistribute it,
+../tar_texi/fdl.texi(,23) with or without modifying it, either commercially or
noncommercially.
+../tar_texi/fdl.texi(,24) Secondarily, this License preserves for the author
and publisher a way
+../tar_texi/fdl.texi(,25) to get credit for their work, while not being
considered responsible
+../tar_texi/fdl.texi(,26) for modifications made by others.
+../tar_texi/fdl.texi(,27)
+../tar_texi/fdl.texi(,28) This License is a kind of ``copyleft'', which means
that derivative
+../tar_texi/fdl.texi(,29) works of the document must themselves be free in the
same sense. It
+../tar_texi/fdl.texi(,30) complements the GNU General Public License, which is
a copyleft
+../tar_texi/fdl.texi(,31) license designed for free software.
+../tar_texi/fdl.texi(,32)
+../tar_texi/fdl.texi(,33) We have designed this License in order to use it for
manuals for free
+../tar_texi/fdl.texi(,34) software, because free software needs free
documentation: a free
+../tar_texi/fdl.texi(,35) program should come with manuals providing the same
freedoms that the
+../tar_texi/fdl.texi(,36) software does. But this License is not limited to
software manuals;
+../tar_texi/fdl.texi(,37) it can be used for any textual work, regardless of
subject matter or
+../tar_texi/fdl.texi(,38) whether it is published as a printed book. We
recommend this License
+../tar_texi/fdl.texi(,39) principally for works whose purpose is instruction
or reference.
+../tar_texi/fdl.texi(,40)
+../tar_texi/fdl.texi(,41) @item
+../tar_texi/fdl.texi(,42) APPLICABILITY AND DEFINITIONS
+../tar_texi/fdl.texi(,43)
+../tar_texi/fdl.texi(,44) This License applies to any manual or other work, in
any medium, that
+../tar_texi/fdl.texi(,45) contains a notice placed by the copyright holder
saying it can be
+../tar_texi/fdl.texi(,46) distributed under the terms of this License. Such a
notice grants a
+../tar_texi/fdl.texi(,47) world-wide, royalty-free license, unlimited in
duration, to use that
+../tar_texi/fdl.texi(,48) work under the conditions stated herein. The
``Document'', below,
+../tar_texi/fdl.texi(,49) refers to any such manual or work. Any member of
the public is a
+../tar_texi/fdl.texi(,50) licensee, and is addressed as ``you''. You accept
the license if you
+../tar_texi/fdl.texi(,51) copy, modify or distribute the work in a way
requiring permission
+../tar_texi/fdl.texi(,52) under copyright law.
+../tar_texi/fdl.texi(,53)
+../tar_texi/fdl.texi(,54) A ``Modified Version'' of the Document means any
work containing the
+../tar_texi/fdl.texi(,55) Document or a portion of it, either copied verbatim,
or with
+../tar_texi/fdl.texi(,56) modifications and/or translated into another
language.
+../tar_texi/fdl.texi(,57)
+../tar_texi/fdl.texi(,58) A ``Secondary Section'' is a named appendix or a
front-matter section
+../tar_texi/fdl.texi(,59) of the Document that deals exclusively with the
relationship of the
+../tar_texi/fdl.texi(,60) publishers or authors of the Document to the
Document's overall
+../tar_texi/fdl.texi(,61) subject (or to related matters) and contains nothing
that could fall
+../tar_texi/fdl.texi(,62) directly within that overall subject. (Thus, if the
Document is in
+../tar_texi/fdl.texi(,63) part a textbook of mathematics, a Secondary Section
may not explain
+../tar_texi/fdl.texi(,64) any mathematics.) The relationship could be a
matter of historical
+../tar_texi/fdl.texi(,65) connection with the subject or with related matters,
or of legal,
+../tar_texi/fdl.texi(,66) commercial, philosophical, ethical or political
position regarding
+../tar_texi/fdl.texi(,67) them.
+../tar_texi/fdl.texi(,68)
+../tar_texi/fdl.texi(,69) The ``Invariant Sections'' are certain Secondary
Sections whose titles
+../tar_texi/fdl.texi(,70) are designated, as being those of Invariant
Sections, in the notice
+../tar_texi/fdl.texi(,71) that says that the Document is released under this
License. If a
+../tar_texi/fdl.texi(,72) section does not fit the above definition of
Secondary then it is not
+../tar_texi/fdl.texi(,73) allowed to be designated as Invariant. The Document
may contain zero
+../tar_texi/fdl.texi(,74) Invariant Sections. If the Document does not
identify any Invariant
+../tar_texi/fdl.texi(,75) Sections then there are none.
+../tar_texi/fdl.texi(,76)
+../tar_texi/fdl.texi(,77) The ``Cover Texts'' are certain short passages of
text that are listed,
+../tar_texi/fdl.texi(,78) as Front-Cover Texts or Back-Cover Texts, in the
notice that says that
+../tar_texi/fdl.texi(,79) the Document is released under this License. A
Front-Cover Text may
+../tar_texi/fdl.texi(,80) be at most 5 words, and a Back-Cover Text may be at
most 25 words.
+../tar_texi/fdl.texi(,81)
+../tar_texi/fdl.texi(,82) A ``Transparent'' copy of the Document means a
machine-readable copy,
+../tar_texi/fdl.texi(,83) represented in a format whose specification is
available to the
+../tar_texi/fdl.texi(,84) general public, that is suitable for revising the
document
+../tar_texi/fdl.texi(,85) straightforwardly with generic text editors or (for
images composed of
+../tar_texi/fdl.texi(,86) pixels) generic paint programs or (for drawings)
some widely available
+../tar_texi/fdl.texi(,87) drawing editor, and that is suitable for input to
text formatters or
+../tar_texi/fdl.texi(,88) for automatic translation to a variety of formats
suitable for input
+../tar_texi/fdl.texi(,89) to text formatters. A copy made in an otherwise
Transparent file
+../tar_texi/fdl.texi(,90) format whose markup, or absence of markup, has been
arranged to thwart
+../tar_texi/fdl.texi(,91) or discourage subsequent modification by readers is
not Transparent.
+../tar_texi/fdl.texi(,92) An image format is not Transparent if used for any
substantial amount
+../tar_texi/fdl.texi(,93) of text. A copy that is not ``Transparent'' is
called ``Opaque''.
+../tar_texi/fdl.texi(,94)
+../tar_texi/fdl.texi(,95) Examples of suitable formats for Transparent copies
include plain
+../tar_texi/fdl.texi(,96) @sc{ascii} without markup, Texinfo input format,
address@hidden input
+../tar_texi/fdl.texi(,97) format, @acronym{SGML} or @acronym{XML} using a
publicly available
+../tar_texi/fdl.texi(,98) @acronym{DTD}, and standard-conforming simple
@acronym{HTML},
+../tar_texi/fdl.texi(,99) PostScript or @acronym{PDF} designed for human
modification. Examples
+../tar_texi/fdl.texi(,100) of transparent image formats include @acronym{PNG},
@acronym{XCF} and
+../tar_texi/fdl.texi(,101) @acronym{JPG}. Opaque formats include proprietary
formats that can be
+../tar_texi/fdl.texi(,102) read and edited only by proprietary word
processors, @acronym{SGML} or
+../tar_texi/fdl.texi(,103) @acronym{XML} for which the @acronym{DTD} and/or
processing tools are
+../tar_texi/fdl.texi(,104) not generally available, and the machine-generated
@acronym{HTML},
+../tar_texi/fdl.texi(,105) PostScript or @acronym{PDF} produced by some word
processors for
+../tar_texi/fdl.texi(,106) output purposes only.
+../tar_texi/fdl.texi(,107)
+../tar_texi/fdl.texi(,108) The ``Title Page'' means, for a printed book, the
title page itself,
+../tar_texi/fdl.texi(,109) plus such following pages as are needed to hold,
legibly, the material
+../tar_texi/fdl.texi(,110) this License requires to appear in the title page.
For works in
+../tar_texi/fdl.texi(,111) formats which do not have any title page as such,
``Title Page'' means
+../tar_texi/fdl.texi(,112) the text near the most prominent appearance of the
work's title,
+../tar_texi/fdl.texi(,113) preceding the beginning of the body of the text.
+../tar_texi/fdl.texi(,114)
+../tar_texi/fdl.texi(,115) A section ``Entitled XYZ'' means a named subunit of
the Document whose
+../tar_texi/fdl.texi(,116) title either is precisely XYZ or contains XYZ in
parentheses following
+../tar_texi/fdl.texi(,117) text that translates XYZ in another language.
(Here XYZ stands for a
+../tar_texi/fdl.texi(,118) specific section name mentioned below, such as
``Acknowledgements'',
+../tar_texi/fdl.texi(,119) ``Dedications'', ``Endorsements'', or ``History''.)
To ``Preserve the Title''
+../tar_texi/fdl.texi(,120) of such a section when you modify the Document
means that it remains a
+../tar_texi/fdl.texi(,121) section ``Entitled XYZ'' according to this
definition.
+../tar_texi/fdl.texi(,122)
+../tar_texi/fdl.texi(,123) The Document may include Warranty Disclaimers next
to the notice which
+../tar_texi/fdl.texi(,124) states that this License applies to the Document.
These Warranty
+../tar_texi/fdl.texi(,125) Disclaimers are considered to be included by
reference in this
+../tar_texi/fdl.texi(,126) License, but only as regards disclaiming
warranties: any other
+../tar_texi/fdl.texi(,127) implication that these Warranty Disclaimers may
have is void and has
+../tar_texi/fdl.texi(,128) no effect on the meaning of this License.
+../tar_texi/fdl.texi(,129)
+../tar_texi/fdl.texi(,130) @item
+../tar_texi/fdl.texi(,131) VERBATIM COPYING
+../tar_texi/fdl.texi(,132)
+../tar_texi/fdl.texi(,133) You may copy and distribute the Document in any
medium, either
+../tar_texi/fdl.texi(,134) commercially or noncommercially, provided that this
License, the
+../tar_texi/fdl.texi(,135) copyright notices, and the license notice saying
this License applies
+../tar_texi/fdl.texi(,136) to the Document are reproduced in all copies, and
that you add no other
+../tar_texi/fdl.texi(,137) conditions whatsoever to those of this License.
You may not use
+../tar_texi/fdl.texi(,138) technical measures to obstruct or control the
reading or further
+../tar_texi/fdl.texi(,139) copying of the copies you make or distribute.
However, you may accept
+../tar_texi/fdl.texi(,140) compensation in exchange for copies. If you
distribute a large enough
+../tar_texi/fdl.texi(,141) number of copies you must also follow the
conditions in section 3.
+../tar_texi/fdl.texi(,142)
+../tar_texi/fdl.texi(,143) You may also lend copies, under the same conditions
stated above, and
+../tar_texi/fdl.texi(,144) you may publicly display copies.
+../tar_texi/fdl.texi(,145)
+../tar_texi/fdl.texi(,146) @item
+../tar_texi/fdl.texi(,147) COPYING IN QUANTITY
+../tar_texi/fdl.texi(,148)
+../tar_texi/fdl.texi(,149) If you publish printed copies (or copies in media
that commonly have
+../tar_texi/fdl.texi(,150) printed covers) of the Document, numbering more
than 100, and the
+../tar_texi/fdl.texi(,151) Document's license notice requires Cover Texts, you
must enclose the
+../tar_texi/fdl.texi(,152) copies in covers that carry, clearly and legibly,
all these Cover
+../tar_texi/fdl.texi(,153) Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on
+../tar_texi/fdl.texi(,154) the back cover. Both covers must also clearly and
legibly identify
+../tar_texi/fdl.texi(,155) you as the publisher of these copies. The front
cover must present
+../tar_texi/fdl.texi(,156) the full title with all words of the title equally
prominent and
+../tar_texi/fdl.texi(,157) visible. You may add other material on the covers
in addition.
+../tar_texi/fdl.texi(,158) Copying with changes limited to the covers, as long
as they preserve
+../tar_texi/fdl.texi(,159) the title of the Document and satisfy these
conditions, can be treated
+../tar_texi/fdl.texi(,160) as verbatim copying in other respects.
+../tar_texi/fdl.texi(,161)
+../tar_texi/fdl.texi(,162) If the required texts for either cover are too
voluminous to fit
+../tar_texi/fdl.texi(,163) legibly, you should put the first ones listed (as
many as fit
+../tar_texi/fdl.texi(,164) reasonably) on the actual cover, and continue the
rest onto adjacent
+../tar_texi/fdl.texi(,165) pages.
+../tar_texi/fdl.texi(,166)
+../tar_texi/fdl.texi(,167) If you publish or distribute Opaque copies of the
Document numbering
+../tar_texi/fdl.texi(,168) more than 100, you must either include a
machine-readable Transparent
+../tar_texi/fdl.texi(,169) copy along with each Opaque copy, or state in or
with each Opaque copy
+../tar_texi/fdl.texi(,170) a computer-network location from which the general
network-using
+../tar_texi/fdl.texi(,171) public has access to download using public-standard
network protocols
+../tar_texi/fdl.texi(,172) a complete Transparent copy of the Document, free
of added material.
+../tar_texi/fdl.texi(,173) If you use the latter option, you must take
reasonably prudent steps,
+../tar_texi/fdl.texi(,174) when you begin distribution of Opaque copies in
quantity, to ensure
+../tar_texi/fdl.texi(,175) that this Transparent copy will remain thus
accessible at the stated
+../tar_texi/fdl.texi(,176) location until at least one year after the last
time you distribute an
+../tar_texi/fdl.texi(,177) Opaque copy (directly or through your agents or
retailers) of that
+../tar_texi/fdl.texi(,178) edition to the public.
+../tar_texi/fdl.texi(,179)
+../tar_texi/fdl.texi(,180) It is requested, but not required, that you contact
the authors of the
+../tar_texi/fdl.texi(,181) Document well before redistributing any large
number of copies, to give
+../tar_texi/fdl.texi(,182) them a chance to provide you with an updated
version of the Document.
+../tar_texi/fdl.texi(,183)
+../tar_texi/fdl.texi(,184) @item
+../tar_texi/fdl.texi(,185) MODIFICATIONS
+../tar_texi/fdl.texi(,186)
+../tar_texi/fdl.texi(,187) You may copy and distribute a Modified Version of
the Document under
+../tar_texi/fdl.texi(,188) the conditions of sections 2 and 3 above, provided
that you release
+../tar_texi/fdl.texi(,189) the Modified Version under precisely this License,
with the Modified
+../tar_texi/fdl.texi(,190) Version filling the role of the Document, thus
licensing distribution
+../tar_texi/fdl.texi(,191) and modification of the Modified Version to whoever
possesses a copy
+../tar_texi/fdl.texi(,192) of it. In addition, you must do these things in
the Modified Version:
+../tar_texi/fdl.texi(,193)
+../tar_texi/fdl.texi(,194) @enumerate A
+../tar_texi/fdl.texi(,195) @item
+../tar_texi/fdl.texi(,196) Use in the Title Page (and on the covers, if any) a
title distinct
+../tar_texi/fdl.texi(,197) from that of the Document, and from those of
previous versions
+../tar_texi/fdl.texi(,198) (which should, if there were any, be listed in the
History section
+../tar_texi/fdl.texi(,199) of the Document). You may use the same title as a
previous version
+../tar_texi/fdl.texi(,200) if the original publisher of that version gives
permission.
+../tar_texi/fdl.texi(,201)
+../tar_texi/fdl.texi(,202) @item
+../tar_texi/fdl.texi(,203) List on the Title Page, as authors, one or more
persons or entities
+../tar_texi/fdl.texi(,204) responsible for authorship of the modifications in
the Modified
+../tar_texi/fdl.texi(,205) Version, together with at least five of the
principal authors of the
+../tar_texi/fdl.texi(,206) Document (all of its principal authors, if it has
fewer than five),
+../tar_texi/fdl.texi(,207) unless they release you from this requirement.
+../tar_texi/fdl.texi(,208)
+../tar_texi/fdl.texi(,209) @item
+../tar_texi/fdl.texi(,210) State on the Title page the name of the publisher
of the
+../tar_texi/fdl.texi(,211) Modified Version, as the publisher.
+../tar_texi/fdl.texi(,212)
+../tar_texi/fdl.texi(,213) @item
+../tar_texi/fdl.texi(,214) Preserve all the copyright notices of the Document.
+../tar_texi/fdl.texi(,215)
+../tar_texi/fdl.texi(,216) @item
+../tar_texi/fdl.texi(,217) Add an appropriate copyright notice for your
modifications
+../tar_texi/fdl.texi(,218) adjacent to the other copyright notices.
+../tar_texi/fdl.texi(,219)
+../tar_texi/fdl.texi(,220) @item
+../tar_texi/fdl.texi(,221) Include, immediately after the copyright notices, a
license notice
+../tar_texi/fdl.texi(,222) giving the public permission to use the Modified
Version under the
+../tar_texi/fdl.texi(,223) terms of this License, in the form shown in the
Addendum below.
+../tar_texi/fdl.texi(,224)
+../tar_texi/fdl.texi(,225) @item
+../tar_texi/fdl.texi(,226) Preserve in that license notice the full lists of
Invariant Sections
+../tar_texi/fdl.texi(,227) and required Cover Texts given in the Document's
license notice.
+../tar_texi/fdl.texi(,228)
+../tar_texi/fdl.texi(,229) @item
+../tar_texi/fdl.texi(,230) Include an unaltered copy of this License.
+../tar_texi/fdl.texi(,231)
+../tar_texi/fdl.texi(,232) @item
+../tar_texi/fdl.texi(,233) Preserve the section Entitled ``History'', Preserve
its Title, and add
+../tar_texi/fdl.texi(,234) to it an item stating at least the title, year, new
authors, and
+../tar_texi/fdl.texi(,235) publisher of the Modified Version as given on the
Title Page. If
+../tar_texi/fdl.texi(,236) there is no section Entitled ``History'' in the
Document, create one
+../tar_texi/fdl.texi(,237) stating the title, year, authors, and publisher of
the Document as
+../tar_texi/fdl.texi(,238) given on its Title Page, then add an item
describing the Modified
+../tar_texi/fdl.texi(,239) Version as stated in the previous sentence.
+../tar_texi/fdl.texi(,240)
+../tar_texi/fdl.texi(,241) @item
+../tar_texi/fdl.texi(,242) Preserve the network location, if any, given in the
Document for
+../tar_texi/fdl.texi(,243) public access to a Transparent copy of the
Document, and likewise
+../tar_texi/fdl.texi(,244) the network locations given in the Document for
previous versions
+../tar_texi/fdl.texi(,245) it was based on. These may be placed in the
``History'' section.
+../tar_texi/fdl.texi(,246) You may omit a network location for a work that was
published at
+../tar_texi/fdl.texi(,247) least four years before the Document itself, or if
the original
+../tar_texi/fdl.texi(,248) publisher of the version it refers to gives
permission.
+../tar_texi/fdl.texi(,249)
+../tar_texi/fdl.texi(,250) @item
+../tar_texi/fdl.texi(,251) For any section Entitled ``Acknowledgements'' or
``Dedications'', Preserve
+../tar_texi/fdl.texi(,252) the Title of the section, and preserve in the
section all the
+../tar_texi/fdl.texi(,253) substance and tone of each of the contributor
acknowledgements and/or
+../tar_texi/fdl.texi(,254) dedications given therein.
+../tar_texi/fdl.texi(,255)
+../tar_texi/fdl.texi(,256) @item
+../tar_texi/fdl.texi(,257) Preserve all the Invariant Sections of the Document,
+../tar_texi/fdl.texi(,258) unaltered in their text and in their titles.
Section numbers
+../tar_texi/fdl.texi(,259) or the equivalent are not considered part of the
section titles.
+../tar_texi/fdl.texi(,260)
+../tar_texi/fdl.texi(,261) @item
+../tar_texi/fdl.texi(,262) Delete any section Entitled ``Endorsements''. Such
a section
+../tar_texi/fdl.texi(,263) may not be included in the Modified Version.
+../tar_texi/fdl.texi(,264)
+../tar_texi/fdl.texi(,265) @item
+../tar_texi/fdl.texi(,266) Do not retitle any existing section to be Entitled
``Endorsements'' or
+../tar_texi/fdl.texi(,267) to conflict in title with any Invariant Section.
+../tar_texi/fdl.texi(,268)
+../tar_texi/fdl.texi(,269) @item
+../tar_texi/fdl.texi(,270) Preserve any Warranty Disclaimers.
+../tar_texi/fdl.texi(,271) @end enumerate
+../tar_texi/fdl.texi(,272)
+../tar_texi/fdl.texi(,273) If the Modified Version includes new front-matter
sections or
+../tar_texi/fdl.texi(,274) appendices that qualify as Secondary Sections and
contain no material
+../tar_texi/fdl.texi(,275) copied from the Document, you may at your option
designate some or all
+../tar_texi/fdl.texi(,276) of these sections as invariant. To do this, add
their titles to the
+../tar_texi/fdl.texi(,277) list of Invariant Sections in the Modified
Version's license notice.
+../tar_texi/fdl.texi(,278) These titles must be distinct from any other
section titles.
+../tar_texi/fdl.texi(,279)
+../tar_texi/fdl.texi(,280) You may add a section Entitled ``Endorsements'',
provided it contains
+../tar_texi/fdl.texi(,281) nothing but endorsements of your Modified Version
by various
+../tar_texi/fdl.texi(,282) parties---for example, statements of peer review or
that the text has
+../tar_texi/fdl.texi(,283) been approved by an organization as the
authoritative definition of a
+../tar_texi/fdl.texi(,284) standard.
+../tar_texi/fdl.texi(,285)
+../tar_texi/fdl.texi(,286) You may add a passage of up to five words as a
Front-Cover Text, and a
+../tar_texi/fdl.texi(,287) passage of up to 25 words as a Back-Cover Text, to
the end of the list
+../tar_texi/fdl.texi(,288) of Cover Texts in the Modified Version. Only one
passage of
+../tar_texi/fdl.texi(,289) Front-Cover Text and one of Back-Cover Text may be
added by (or
+../tar_texi/fdl.texi(,290) through arrangements made by) any one entity. If
the Document already
+../tar_texi/fdl.texi(,291) includes a cover text for the same cover,
previously added by you or
+../tar_texi/fdl.texi(,292) by arrangement made by the same entity you are
acting on behalf of,
+../tar_texi/fdl.texi(,293) you may not add another; but you may replace the
old one, on explicit
+../tar_texi/fdl.texi(,294) permission from the previous publisher that added
the old one.
+../tar_texi/fdl.texi(,295)
+../tar_texi/fdl.texi(,296) The author(s) and publisher(s) of the Document do
not by this License
+../tar_texi/fdl.texi(,297) give permission to use their names for publicity
for or to assert or
+../tar_texi/fdl.texi(,298) imply endorsement of any Modified Version.
+../tar_texi/fdl.texi(,299)
+../tar_texi/fdl.texi(,300) @item
+../tar_texi/fdl.texi(,301) COMBINING DOCUMENTS
+../tar_texi/fdl.texi(,302)
+../tar_texi/fdl.texi(,303) You may combine the Document with other documents
released under this
+../tar_texi/fdl.texi(,304) License, under the terms defined in section 4 above
for modified
+../tar_texi/fdl.texi(,305) versions, provided that you include in the
combination all of the
+../tar_texi/fdl.texi(,306) Invariant Sections of all of the original
documents, unmodified, and
+../tar_texi/fdl.texi(,307) list them all as Invariant Sections of your
combined work in its
+../tar_texi/fdl.texi(,308) license notice, and that you preserve all their
Warranty Disclaimers.
+../tar_texi/fdl.texi(,309)
+../tar_texi/fdl.texi(,310) The combined work need only contain one copy of
this License, and
+../tar_texi/fdl.texi(,311) multiple identical Invariant Sections may be
replaced with a single
+../tar_texi/fdl.texi(,312) copy. If there are multiple Invariant Sections
with the same name but
+../tar_texi/fdl.texi(,313) different contents, make the title of each such
section unique by
+../tar_texi/fdl.texi(,314) adding at the end of it, in parentheses, the name
of the original
+../tar_texi/fdl.texi(,315) author or publisher of that section if known, or
else a unique number.
+../tar_texi/fdl.texi(,316) Make the same adjustment to the section titles in
the list of
+../tar_texi/fdl.texi(,317) Invariant Sections in the license notice of the
combined work.
+../tar_texi/fdl.texi(,318)
+../tar_texi/fdl.texi(,319) In the combination, you must combine any sections
Entitled ``History''
+../tar_texi/fdl.texi(,320) in the various original documents, forming one
section Entitled
+../tar_texi/fdl.texi(,321) ``History''; likewise combine any sections Entitled
``Acknowledgements'',
+../tar_texi/fdl.texi(,322) and any sections Entitled ``Dedications''. You
must delete all
+../tar_texi/fdl.texi(,323) sections Entitled ``Endorsements.''
+../tar_texi/fdl.texi(,324)
+../tar_texi/fdl.texi(,325) @item
+../tar_texi/fdl.texi(,326) COLLECTIONS OF DOCUMENTS
+../tar_texi/fdl.texi(,327)
+../tar_texi/fdl.texi(,328) You may make a collection consisting of the
Document and other documents
+../tar_texi/fdl.texi(,329) released under this License, and replace the
individual copies of this
+../tar_texi/fdl.texi(,330) License in the various documents with a single copy
that is included in
+../tar_texi/fdl.texi(,331) the collection, provided that you follow the rules
of this License for
+../tar_texi/fdl.texi(,332) verbatim copying of each of the documents in all
other respects.
+../tar_texi/fdl.texi(,333)
+../tar_texi/fdl.texi(,334) You may extract a single document from such a
collection, and distribute
+../tar_texi/fdl.texi(,335) it individually under this License, provided you
insert a copy of this
+../tar_texi/fdl.texi(,336) License into the extracted document, and follow
this License in all
+../tar_texi/fdl.texi(,337) other respects regarding verbatim copying of that
document.
+../tar_texi/fdl.texi(,338)
+../tar_texi/fdl.texi(,339) @item
+../tar_texi/fdl.texi(,340) AGGREGATION WITH INDEPENDENT WORKS
+../tar_texi/fdl.texi(,341)
+../tar_texi/fdl.texi(,342) A compilation of the Document or its derivatives
with other separate
+../tar_texi/fdl.texi(,343) and independent documents or works, in or on a
volume of a storage or
+../tar_texi/fdl.texi(,344) distribution medium, is called an ``aggregate'' if
the copyright
+../tar_texi/fdl.texi(,345) resulting from the compilation is not used to limit
the legal rights
+../tar_texi/fdl.texi(,346) of the compilation's users beyond what the
individual works permit.
+../tar_texi/fdl.texi(,347) When the Document is included in an aggregate, this
License does not
+../tar_texi/fdl.texi(,348) apply to the other works in the aggregate which are
not themselves
+../tar_texi/fdl.texi(,349) derivative works of the Document.
+../tar_texi/fdl.texi(,350)
+../tar_texi/fdl.texi(,351) If the Cover Text requirement of section 3 is
applicable to these
+../tar_texi/fdl.texi(,352) copies of the Document, then if the Document is
less than one half of
+../tar_texi/fdl.texi(,353) the entire aggregate, the Document's Cover Texts
may be placed on
+../tar_texi/fdl.texi(,354) covers that bracket the Document within the
aggregate, or the
+../tar_texi/fdl.texi(,355) electronic equivalent of covers if the Document is
in electronic form.
+../tar_texi/fdl.texi(,356) Otherwise they must appear on printed covers that
bracket the whole
+../tar_texi/fdl.texi(,357) aggregate.
+../tar_texi/fdl.texi(,358)
+../tar_texi/fdl.texi(,359) @item
+../tar_texi/fdl.texi(,360) TRANSLATION
+../tar_texi/fdl.texi(,361)
+../tar_texi/fdl.texi(,362) Translation is considered a kind of modification,
so you may
+../tar_texi/fdl.texi(,363) distribute translations of the Document under the
terms of section 4.
+../tar_texi/fdl.texi(,364) Replacing Invariant Sections with translations
requires special
+../tar_texi/fdl.texi(,365) permission from their copyright holders, but you
may include
+../tar_texi/fdl.texi(,366) translations of some or all Invariant Sections in
addition to the
+../tar_texi/fdl.texi(,367) original versions of these Invariant Sections. You
may include a
+../tar_texi/fdl.texi(,368) translation of this License, and all the license
notices in the
+../tar_texi/fdl.texi(,369) Document, and any Warranty Disclaimers, provided
that you also include
+../tar_texi/fdl.texi(,370) the original English version of this License and
the original versions
+../tar_texi/fdl.texi(,371) of those notices and disclaimers. In case of a
disagreement between
+../tar_texi/fdl.texi(,372) the translation and the original version of this
License or a notice
+../tar_texi/fdl.texi(,373) or disclaimer, the original version will prevail.
+../tar_texi/fdl.texi(,374)
+../tar_texi/fdl.texi(,375) If a section in the Document is Entitled
``Acknowledgements'',
+../tar_texi/fdl.texi(,376) ``Dedications'', or ``History'', the requirement
(section 4) to Preserve
+../tar_texi/fdl.texi(,377) its Title (section 1) will typically require
changing the actual
+../tar_texi/fdl.texi(,378) title.
+../tar_texi/fdl.texi(,379)
+../tar_texi/fdl.texi(,380) @item
+../tar_texi/fdl.texi(,381) TERMINATION
+../tar_texi/fdl.texi(,382)
+../tar_texi/fdl.texi(,383) You may not copy, modify, sublicense, or distribute
the Document except
+../tar_texi/fdl.texi(,384) as expressly provided for under this License. Any
other attempt to
+../tar_texi/fdl.texi(,385) copy, modify, sublicense or distribute the Document
is void, and will
+../tar_texi/fdl.texi(,386) automatically terminate your rights under this
License. However,
+../tar_texi/fdl.texi(,387) parties who have received copies, or rights, from
you under this
+../tar_texi/fdl.texi(,388) License will not have their licenses terminated so
long as such
+../tar_texi/fdl.texi(,389) parties remain in full compliance.
+../tar_texi/fdl.texi(,390)
+../tar_texi/fdl.texi(,391) @item
+../tar_texi/fdl.texi(,392) FUTURE REVISIONS OF THIS LICENSE
+../tar_texi/fdl.texi(,393)
+../tar_texi/fdl.texi(,394) The Free Software Foundation may publish new,
revised versions
+../tar_texi/fdl.texi(,395) of the GNU Free Documentation License from time to
time. Such new
+../tar_texi/fdl.texi(,396) versions will be similar in spirit to the present
version, but may
+../tar_texi/fdl.texi(,397) differ in detail to address new problems or
concerns. See
+../tar_texi/fdl.texi(,398) @uref{http://www.gnu.org/copyleft/}.
+../tar_texi/fdl.texi(,399)
+../tar_texi/fdl.texi(,400) Each version of the License is given a
distinguishing version number.
+../tar_texi/fdl.texi(,401) If the Document specifies that a particular
numbered version of this
+../tar_texi/fdl.texi(,402) License ``or any later version'' applies to it, you
have the option of
+../tar_texi/fdl.texi(,403) following the terms and conditions either of that
specified version or
+../tar_texi/fdl.texi(,404) of any later version that has been published (not
as a draft) by the
+../tar_texi/fdl.texi(,405) Free Software Foundation. If the Document does not
specify a version
+../tar_texi/fdl.texi(,406) number of this License, you may choose any version
ever published (not
+../tar_texi/fdl.texi(,407) as a draft) by the Free Software Foundation.
+../tar_texi/fdl.texi(,408) @end enumerate
+../tar_texi/fdl.texi(,409)
+../tar_texi/fdl.texi(,410) @page
+../tar_texi/fdl.texi(,411) @appendixsubsec ADDENDUM: How to use this License
for your documents
+../tar_texi/fdl.texi(,412)
+../tar_texi/fdl.texi(,413) To use this License in a document you have written,
include a copy of
+../tar_texi/fdl.texi(,414) the License in the document and put the following
copyright and
+../tar_texi/fdl.texi(,415) license notices just after the title page:
+../tar_texi/fdl.texi(,416)
+../tar_texi/fdl.texi(,417) @smallexample
+../tar_texi/fdl.texi(,418) @group
+../tar_texi/fdl.texi(,419) Copyright (C) @var{year} @var{your name}.
+../tar_texi/fdl.texi(,420) Permission is granted to copy, distribute and/or
modify this document
+../tar_texi/fdl.texi(,421) under the terms of the GNU Free Documentation
License, Version 1.2
+../tar_texi/fdl.texi(,422) or any later version published by the Free
Software Foundation;
+../tar_texi/fdl.texi(,423) with no Invariant Sections, no Front-Cover Texts,
and no Back-Cover
+../tar_texi/fdl.texi(,424) Texts. A copy of the license is included in the
section entitled ``GNU
+../tar_texi/fdl.texi(,425) Free Documentation License''.
+../tar_texi/fdl.texi(,426) @end group
+../tar_texi/fdl.texi(,427) @end smallexample
+../tar_texi/fdl.texi(,428)
+../tar_texi/fdl.texi(,429) If you have Invariant Sections, Front-Cover Texts
and Back-Cover Texts,
+../tar_texi/fdl.texi(,430) replace the ``with...Texts.'' line with this:
+../tar_texi/fdl.texi(,431)
+../tar_texi/fdl.texi(,432) @smallexample
+../tar_texi/fdl.texi(,433) @group
+../tar_texi/fdl.texi(,434) with the Invariant Sections being @var{list
their titles}, with
+../tar_texi/fdl.texi(,435) the Front-Cover Texts being @var{list}, and
with the Back-Cover Texts
+../tar_texi/fdl.texi(,436) being @var{list}.
+../tar_texi/fdl.texi(,437) @end group
+../tar_texi/fdl.texi(,438) @end smallexample
+../tar_texi/fdl.texi(,439)
+../tar_texi/fdl.texi(,440) If you have Invariant Sections without Cover Texts,
or some other
+../tar_texi/fdl.texi(,441) combination of the three, merge those two
alternatives to suit the
+../tar_texi/fdl.texi(,442) situation.
+../tar_texi/fdl.texi(,443)
+../tar_texi/fdl.texi(,444) If your document contains nontrivial examples of
program code, we
+../tar_texi/fdl.texi(,445) recommend releasing these examples in parallel
under your choice of
+../tar_texi/fdl.texi(,446) free software license, such as the GNU General
Public License,
+../tar_texi/fdl.texi(,447) to permit their use in free software.
+../tar_texi/fdl.texi(,448)
+../tar_texi/fdl.texi(,449) @c Local Variables:
+../tar_texi/fdl.texi(,450) @c ispell-local-pdict: "ispell-dict"
+../tar_texi/fdl.texi(,451) @c End:
+../tar_texi/fdl.texi(,452)
+../tar_texi/tar.texi(,10794)
+../tar_texi/tar.texi(,10795) @node Index of Command Line Options
+../tar_texi/tar.texi(,10796) @appendix Index of Command Line Options
+../tar_texi/tar.texi(,10797)
+../tar_texi/tar.texi(GNUTAR,10798) This appendix contains an index of all
@acronym{GNU} @command{tar} long command line
+../tar_texi/tar.texi(,10799) options. The options are listed without the
preceeding double-dash.
+../tar_texi/tar.texi(,10800) For a cross-reference of short command line
options, @ref{Short Option Summary}.
+../tar_texi/tar.texi(,10801)
+../tar_texi/tar.texi(,10802) @printindex op
+../tar_texi/tar.texi(,10803)
+../tar_texi/tar.texi(,10804) @node Index
+../tar_texi/tar.texi(,10805) @appendix Index
+../tar_texi/tar.texi(,10806)
+../tar_texi/tar.texi(,10807) @printindex cp
+../tar_texi/tar.texi(,10808)
+../tar_texi/tar.texi(,10809) @summarycontents
+../tar_texi/tar.texi(,10810) @contents
+../tar_texi/tar.texi(,10811) @bye
Index: Tests/tar_res/tar.passtexi
===================================================================
RCS file: Tests/tar_res/tar.passtexi
diff -N Tests/tar_res/tar.passtexi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_res/tar.passtexi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,13454 @@
+../tar_texi/tar.texi(,2) @comment %**start of header
+../tar_texi/tar.texi(,3) @setfilename tar.info
+../tar_texi/tar.texi(,5) @settitle GNU tar 1.15.92
+../tar_texi/tar.texi(,6) @setchapternewpage odd
+../tar_texi/tar.texi(,7)
+../tar_texi/tar.texi(,8) @finalout
+../tar_texi/tar.texi(,9)
+../tar_texi/tar.texi(,10) @smallbook
+../tar_texi/tar.texi(,11) @c %**end of header
+../tar_texi/tar.texi(,12)
+../tar_texi/tar.texi(,13) @c Maintenance notes:
+../tar_texi/tar.texi(,14) @c 1. Pay attention to @FIXME{}s and @UNREVISED{}s
+../tar_texi/tar.texi(,15) @c 2. Before creating final variant:
+../tar_texi/tar.texi(,16) @c 2.1. Run `make check-options' to make sure all
options are properly
+../tar_texi/tar.texi(,17) @c documented;
+../tar_texi/tar.texi(,18) @c 2.2. Run `make master-menu' (see comment
before the master menu).
+../tar_texi/tar.texi(,19)
+../tar_texi/rendition.texi(,1) @c This is part of GNU tar manual.
+../tar_texi/rendition.texi(,2) @c Copyright (C) 1992, 1994, 1995, 1996, 1997,
1999, 2000, 2001,
+../tar_texi/rendition.texi(,3) @c 2003, 2004, 2006 Free Software Foundation,
Inc.
+../tar_texi/rendition.texi(,4) @c See file tar.texi for copying conditions.
+../tar_texi/rendition.texi(,5)
+../tar_texi/rendition.texi(,6) @c This file contains support for 'renditions'
by Fran@,{c}ois Pinard
+../tar_texi/rendition.texi(,7) @c I extended it by adding a FIXME_FOOTNOTE
variable, which controls
+../tar_texi/rendition.texi(,8) @c whether FIXME information should be placed
in footnotes or
+../tar_texi/rendition.texi(,9) @c inlined. --gray
+../tar_texi/rendition.texi(,10)
+../tar_texi/rendition.texi(,11) @c
======================================================================
+../tar_texi/rendition.texi(,12) @c This document has three levels of
rendition: PUBLISH, DISTRIB or PROOF,
+../tar_texi/rendition.texi(,13) @c as decided by @set symbols. The PUBLISH
rendition does not show
+../tar_texi/rendition.texi(,14) @c notes or marks asking for revision. Most
users will prefer having more
+../tar_texi/rendition.texi(,15) @c information, even if this information is
not fully revised for adequacy,
+../tar_texi/rendition.texi(,16) @c so DISTRIB is the default for
distributions. The PROOF rendition
+../tar_texi/rendition.texi(,17) @c show all marks to the point of ugliness,
but is nevertheless useful to
+../tar_texi/rendition.texi(,18) @c those working on the manual itself.
+../tar_texi/rendition.texi(,19) @c
======================================================================
+../tar_texi/rendition.texi(,20)
+../tar_texi/rendition.texi(,21) @c Set this symbol if you wish FIXMEs to
appear in footnotes, instead
+../tar_texi/rendition.texi(,22) @c of being inserted into the text.
+../tar_texi/rendition.texi(,23) @c @set PROOF_FOOTNOTED
+../tar_texi/rendition.texi(,24)
+../tar_texi/rendition.texi(,32)
+../tar_texi/rendition.texi(,36)
+../tar_texi/rendition.texi(,40)
+../tar_texi/rendition.texi(,44)
+../tar_texi/rendition.texi(,45) @c Output marks for nodes needing revision,
but not in PUBLISH rendition.
+../tar_texi/rendition.texi(,46)
+../tar_texi/rendition.texi(,54)
+../tar_texi/rendition.texi(,55) @c Output various FIXME information only in
PROOF rendition.
+../tar_texi/rendition.texi(,56)
+../tar_texi/rendition.texi(,72)
+../tar_texi/rendition.texi(,79)
+../tar_texi/rendition.texi(,87)
+../tar_texi/rendition.texi(,94)
+../tar_texi/rendition.texi(,95) @c End of rendition.texi
+../tar_texi/value.texi(,1) @c This is part of GNU tar manual.
+../tar_texi/value.texi(,2) @c Copyright (C) 1992, 1994, 1995, 1996, 1997,
1999, 2000, 2001,
+../tar_texi/value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation,
Inc.
+../tar_texi/value.texi(,4) @c See file tar.texi for copying conditions.
+../tar_texi/value.texi(,5)
+../tar_texi/value.texi(,9)
+../tar_texi/value.texi(,13)
+../tar_texi/value.texi(,21)
+../tar_texi/value.texi(,22)
+../tar_texi/tar.texi(,22)
+../tar_texi/tar.texi(,23) @defcodeindex op
+../tar_texi/tar.texi(,24)
+../tar_texi/tar.texi(,25) @c Put everything in one index (arbitrarily chosen
to be the concept index).
+../tar_texi/tar.texi(,26) @syncodeindex fn cp
+../tar_texi/tar.texi(,27) @syncodeindex ky cp
+../tar_texi/tar.texi(,28) @syncodeindex pg cp
+../tar_texi/tar.texi(,29) @syncodeindex vr cp
+../tar_texi/tar.texi(,30)
+../tar_texi/tar.texi(,31) @copying
+../tar_texi/tar.texi(,32)
+../tar_texi/tar.texi(,33) This manual is for @acronym{GNU} @command{tar}
(version
+../tar_texi/tar.texi(,34) 1.15.92, 26 June 2006), which creates and extracts
files
+../tar_texi/tar.texi(,35) from archives.
+../tar_texi/tar.texi(,36)
+../tar_texi/tar.texi(,37) Copyright @copyright{} 1992, 1994, 1995, 1996, 1997,
1999, 2000, 2001,
+../tar_texi/tar.texi(,38) 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+../tar_texi/tar.texi(,39)
+../tar_texi/tar.texi(,40) @quotation
+../tar_texi/tar.texi(,41) Permission is granted to copy, distribute and/or
modify this document
+../tar_texi/tar.texi(,42) under the terms of the GNU Free Documentation
License, Version 1.1 or
+../tar_texi/tar.texi(,43) any later version published by the Free Software
Foundation; with no
+../tar_texi/tar.texi(,44) Invariant Sections, with the Front-Cover Texts being
``A GNU Manual,''
+../tar_texi/tar.texi(,45) and with the Back-Cover Texts as in (a) below. A
copy of the license
+../tar_texi/tar.texi(,46) is included in the section entitled "GNU Free
Documentation License".
+../tar_texi/tar.texi(,47)
+../tar_texi/tar.texi(,48) (a) The FSF's Back-Cover Text is: ``You are free to
copy and modify
+../tar_texi/tar.texi(,49) this GNU Manual. Buying copies from GNU Press
supports the FSF in
+../tar_texi/tar.texi(,50) developing GNU and promoting software freedom.''
+../tar_texi/tar.texi(,51) @end quotation
+../tar_texi/tar.texi(,52) @end copying
+../tar_texi/tar.texi(,53)
+../tar_texi/tar.texi(,54) @dircategory Archiving
+../tar_texi/tar.texi(,58)
+../tar_texi/tar.texi(,59) @dircategory Individual utilities
+../tar_texi/tar.texi(,63)
+../tar_texi/tar.texi(,64) @shorttitlepage @acronym{GNU} @command{tar}
+../tar_texi/tar.texi(,65)
+../tar_texi/tar.texi(,66) @titlepage
+../tar_texi/tar.texi(,67) @title @acronym{GNU} tar: an archiver tool
+../tar_texi/tar.texi(,68) @subtitle FTP release, version 1.15.92, 26 June 2006
+../tar_texi/tar.texi(,69) @author John Gilmore, Jay Fenlason et al.
+../tar_texi/tar.texi(,70)
+../tar_texi/tar.texi(,71) @page
+../tar_texi/tar.texi(,72) @vskip 0pt plus 1filll
+../tar_texi/tar.texi(,73) @insertcopying
+../tar_texi/tar.texi(,74) @end titlepage
+../tar_texi/tar.texi(,75)
+../tar_texi/tar.texi(,77) @node Top
+../tar_texi/tar.texi(,78) @top @acronym{GNU} tar: an archiver tool
+../tar_texi/tar.texi(,79)
+../tar_texi/tar.texi(,80) @insertcopying
+../tar_texi/tar.texi(,81)
+../tar_texi/tar.texi(,82) @cindex file archival
+../tar_texi/tar.texi(,83) @cindex archiving files
+../tar_texi/tar.texi(,84)
+../tar_texi/tar.texi(,85) The first part of this master menu lists the major
nodes in this Info
+../tar_texi/tar.texi(,86) document. The rest of the menu lists all the lower
level nodes.
+../tar_texi/tar.texi(,88)
+../tar_texi/tar.texi(,89) @c The master menu goes here.
+../tar_texi/tar.texi(,90) @c
+../tar_texi/tar.texi(,91) @c NOTE: To update it from within Emacs, make sure
mastermenu.el is
+../tar_texi/tar.texi(,92) @c loaded and run texinfo-master-menu.
+../tar_texi/tar.texi(,93) @c To update it from the command line, run
+../tar_texi/tar.texi(,94) @c
+../tar_texi/tar.texi(,95) @c make master-menu
+../tar_texi/tar.texi(,96)
+../tar_texi/tar.texi(,97) @menu
+../tar_texi/tar.texi(,98) * Introduction::
+../tar_texi/tar.texi(,99) * Tutorial::
+../tar_texi/tar.texi(,100) * tar invocation::
+../tar_texi/tar.texi(,101) * operations::
+../tar_texi/tar.texi(,102) * Backups::
+../tar_texi/tar.texi(,103) * Choosing::
+../tar_texi/tar.texi(,104) * Date input formats::
+../tar_texi/tar.texi(,105) * Formats::
+../tar_texi/tar.texi(,106) * Media::
+../tar_texi/tar.texi(,107)
+../tar_texi/tar.texi(,108) Appendices
+../tar_texi/tar.texi(,109)
+../tar_texi/tar.texi(,110) * Changes::
+../tar_texi/tar.texi(,111) * Configuring Help Summary::
+../tar_texi/tar.texi(,112) * Tar Internals::
+../tar_texi/tar.texi(,113) * Genfile::
+../tar_texi/tar.texi(,114) * Free Software Needs Free Documentation::
+../tar_texi/tar.texi(,115) * Copying This Manual::
+../tar_texi/tar.texi(,116) * Index of Command Line Options::
+../tar_texi/tar.texi(,117) * Index::
+../tar_texi/tar.texi(,118)
+../tar_texi/tar.texi(,119) @detailmenu
+../tar_texi/tar.texi(,120) --- The Detailed Node Listing ---
+../tar_texi/tar.texi(,121)
+../tar_texi/tar.texi(,122) Introduction
+../tar_texi/tar.texi(,123)
+../tar_texi/tar.texi(,124) * Book Contents:: What this Book
Contains
+../tar_texi/tar.texi(,125) * Definitions:: Some Definitions
+../tar_texi/tar.texi(,126) * What tar Does:: What @command{tar}
Does
+../tar_texi/tar.texi(,127) * Naming tar Archives:: How @command{tar}
Archives are Named
+../tar_texi/tar.texi(GNUTAR,128) * Authors::
../tar_texi/tar.texi(GNUTAR,128) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,128) Authors
+../tar_texi/tar.texi(,129) * Reports:: Reporting bugs or
suggestions
+../tar_texi/tar.texi(,130)
+../tar_texi/tar.texi(,131) Tutorial Introduction to @command{tar}
+../tar_texi/tar.texi(,132)
+../tar_texi/tar.texi(,133) * assumptions::
+../tar_texi/tar.texi(,134) * stylistic conventions::
+../tar_texi/tar.texi(,135) * basic tar options:: Basic @command{tar}
Operations and Options
+../tar_texi/tar.texi(,136) * frequent operations::
+../tar_texi/tar.texi(,137) * Two Frequent Options::
+../tar_texi/tar.texi(,138) * create:: How to Create
Archives
+../tar_texi/tar.texi(,139) * list:: How to List Archives
+../tar_texi/tar.texi(,140) * extract:: How to Extract
Members from an Archive
+../tar_texi/tar.texi(,141) * going further::
+../tar_texi/tar.texi(,142)
+../tar_texi/tar.texi(,143) Two Frequently Used Options
+../tar_texi/tar.texi(,144)
+../tar_texi/tar.texi(,145) * file tutorial::
+../tar_texi/tar.texi(,146) * verbose tutorial::
+../tar_texi/tar.texi(,147) * help tutorial::
+../tar_texi/tar.texi(,148)
+../tar_texi/tar.texi(,149) How to Create Archives
+../tar_texi/tar.texi(,150)
+../tar_texi/tar.texi(,151) * prepare for examples::
+../tar_texi/tar.texi(,152) * Creating the archive::
+../tar_texi/tar.texi(,153) * create verbose::
+../tar_texi/tar.texi(,154) * short create::
+../tar_texi/tar.texi(,155) * create dir::
+../tar_texi/tar.texi(,156)
+../tar_texi/tar.texi(,157) How to List Archives
+../tar_texi/tar.texi(,158)
+../tar_texi/tar.texi(,159) * list dir::
+../tar_texi/tar.texi(,160)
+../tar_texi/tar.texi(,161) How to Extract Members from an Archive
+../tar_texi/tar.texi(,162)
+../tar_texi/tar.texi(,163) * extracting archives::
+../tar_texi/tar.texi(,164) * extracting files::
+../tar_texi/tar.texi(,165) * extract dir::
+../tar_texi/tar.texi(,166) * extracting untrusted archives::
+../tar_texi/tar.texi(,167) * failing commands::
+../tar_texi/tar.texi(,168)
+../tar_texi/tar.texi(GNUTAR,169) Invoking ../tar_texi/tar.texi(GNUTAR,169)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,169)
+../tar_texi/tar.texi(,170)
+../tar_texi/tar.texi(,171) * Synopsis::
+../tar_texi/tar.texi(,172) * using tar options::
+../tar_texi/tar.texi(,173) * Styles::
+../tar_texi/tar.texi(,174) * All Options::
+../tar_texi/tar.texi(,175) * help::
+../tar_texi/tar.texi(,176) * defaults::
+../tar_texi/tar.texi(,177) * verbose::
+../tar_texi/tar.texi(,178) * interactive::
+../tar_texi/tar.texi(,179)
+../tar_texi/tar.texi(,180) The Three Option Styles
+../tar_texi/tar.texi(,181)
+../tar_texi/tar.texi(,182) * Long Options:: Long Option Style
+../tar_texi/tar.texi(,183) * Short Options:: Short Option Style
+../tar_texi/tar.texi(,184) * Old Options:: Old Option Style
+../tar_texi/tar.texi(,185) * Mixing:: Mixing Option Styles
+../tar_texi/tar.texi(,186)
+../tar_texi/tar.texi(,187) All @command{tar} Options
+../tar_texi/tar.texi(,188)
+../tar_texi/tar.texi(,189) * Operation Summary::
+../tar_texi/tar.texi(,190) * Option Summary::
+../tar_texi/tar.texi(,191) * Short Option Summary::
+../tar_texi/tar.texi(,192)
+../tar_texi/tar.texi(GNUTAR,193) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,193) Operations
+../tar_texi/tar.texi(,194)
+../tar_texi/tar.texi(,195) * Basic tar::
+../tar_texi/tar.texi(,196) * Advanced tar::
+../tar_texi/tar.texi(,197) * create options::
+../tar_texi/tar.texi(,198) * extract options::
+../tar_texi/tar.texi(,199) * backup::
+../tar_texi/tar.texi(,200) * Applications::
+../tar_texi/tar.texi(,201) * looking ahead::
+../tar_texi/tar.texi(,202)
+../tar_texi/tar.texi(GNUTAR,203) Advanced ../tar_texi/tar.texi(GNUTAR,203)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,203) Operations
+../tar_texi/tar.texi(,204)
+../tar_texi/tar.texi(,205) * Operations::
+../tar_texi/tar.texi(,206) * append::
+../tar_texi/tar.texi(,207) * update::
+../tar_texi/tar.texi(,208) * concatenate::
+../tar_texi/tar.texi(,209) * delete::
+../tar_texi/tar.texi(,210) * compare::
+../tar_texi/tar.texi(,211)
+../tar_texi/tar.texi(,212) How to Add Files to Existing Archives:
@option{--append}
+../tar_texi/tar.texi(,213)
+../tar_texi/tar.texi(,214) * appending files:: Appending Files to
an Archive
+../tar_texi/tar.texi(,215) * multiple::
+../tar_texi/tar.texi(,216)
+../tar_texi/tar.texi(,217) Updating an Archive
+../tar_texi/tar.texi(,218)
+../tar_texi/tar.texi(,219) * how to update::
+../tar_texi/tar.texi(,220)
+../tar_texi/tar.texi(,221) Options Used by @option{--create}
+../tar_texi/tar.texi(,222)
+../tar_texi/tar.texi(,223) * override:: Overriding File
Metadata.
+../tar_texi/tar.texi(,224) * Ignore Failed Read::
+../tar_texi/tar.texi(,225)
+../tar_texi/tar.texi(,226) Options Used by @option{--extract}
+../tar_texi/tar.texi(,227)
+../tar_texi/tar.texi(,228) * Reading:: Options to Help
Read Archives
+../tar_texi/tar.texi(,229) * Writing:: Changing How
@command{tar} Writes Files
+../tar_texi/tar.texi(,230) * Scarce:: Coping with Scarce
Resources
+../tar_texi/tar.texi(,231)
+../tar_texi/tar.texi(,232) Options to Help Read Archives
+../tar_texi/tar.texi(,233)
+../tar_texi/tar.texi(,234) * read full records::
+../tar_texi/tar.texi(,235) * Ignore Zeros::
+../tar_texi/tar.texi(,236)
+../tar_texi/tar.texi(,237) Changing How @command{tar} Writes Files
+../tar_texi/tar.texi(,238)
+../tar_texi/tar.texi(,239) * Dealing with Old Files::
+../tar_texi/tar.texi(,240) * Overwrite Old Files::
+../tar_texi/tar.texi(,241) * Keep Old Files::
+../tar_texi/tar.texi(,242) * Keep Newer Files::
+../tar_texi/tar.texi(,243) * Unlink First::
+../tar_texi/tar.texi(,244) * Recursive Unlink::
+../tar_texi/tar.texi(,245) * Data Modification Times::
+../tar_texi/tar.texi(,246) * Setting Access Permissions::
+../tar_texi/tar.texi(,247) * Directory Modification Times and Permissions::
+../tar_texi/tar.texi(,248) * Writing to Standard Output::
+../tar_texi/tar.texi(,249) * Writing to an External Program::
+../tar_texi/tar.texi(,250) * remove files::
+../tar_texi/tar.texi(,251)
+../tar_texi/tar.texi(,252) Coping with Scarce Resources
+../tar_texi/tar.texi(,253)
+../tar_texi/tar.texi(,254) * Starting File::
+../tar_texi/tar.texi(,255) * Same Order::
+../tar_texi/tar.texi(,256)
+../tar_texi/tar.texi(,257) Performing Backups and Restoring Files
+../tar_texi/tar.texi(,258)
+../tar_texi/tar.texi(,259) * Full Dumps:: Using @command{tar}
to Perform Full Dumps
+../tar_texi/tar.texi(,260) * Incremental Dumps:: Using @command{tar}
to Perform Incremental Dumps
+../tar_texi/tar.texi(,261) * Backup Levels:: Levels of Backups
+../tar_texi/tar.texi(,262) * Backup Parameters:: Setting Parameters
for Backups and Restoration
+../tar_texi/tar.texi(,263) * Scripted Backups:: Using the Backup
Scripts
+../tar_texi/tar.texi(,264) * Scripted Restoration:: Using the Restore
Script
+../tar_texi/tar.texi(,265)
+../tar_texi/tar.texi(,266) Setting Parameters for Backups and Restoration
+../tar_texi/tar.texi(,267)
+../tar_texi/tar.texi(,268) * General-Purpose Variables::
+../tar_texi/tar.texi(,269) * Magnetic Tape Control::
+../tar_texi/tar.texi(,270) * User Hooks::
+../tar_texi/tar.texi(,271) * backup-specs example:: An Example Text of
@file{Backup-specs}
+../tar_texi/tar.texi(,272)
+../tar_texi/tar.texi(,273) Choosing Files and Names for @command{tar}
+../tar_texi/tar.texi(,274)
+../tar_texi/tar.texi(,275) * file:: Choosing the
Archive's Name
+../tar_texi/tar.texi(,276) * Selecting Archive Members::
+../tar_texi/tar.texi(,277) * files:: Reading Names from
a File
+../tar_texi/tar.texi(,278) * exclude:: Excluding Some Files
+../tar_texi/tar.texi(,279) * wildcards:: Wildcards Patterns
and Matching
+../tar_texi/tar.texi(,280) * quoting styles:: Ways of Quoting
Special Characters in Names
+../tar_texi/tar.texi(,281) * transform:: Modifying File and
Member Names
+../tar_texi/tar.texi(,282) * after:: Operating Only on
New Files
+../tar_texi/tar.texi(,283) * recurse:: Descending into
Directories
+../tar_texi/tar.texi(,284) * one:: Crossing File
System Boundaries
+../tar_texi/tar.texi(,285)
+../tar_texi/tar.texi(,286) Reading Names from a File
+../tar_texi/tar.texi(,287)
+../tar_texi/tar.texi(,288) * nul::
+../tar_texi/tar.texi(,289)
+../tar_texi/tar.texi(,290) Excluding Some Files
+../tar_texi/tar.texi(,291)
+../tar_texi/tar.texi(,292) * problems with exclude::
+../tar_texi/tar.texi(,293)
+../tar_texi/tar.texi(,294) Wildcards Patterns and Matching
+../tar_texi/tar.texi(,295)
+../tar_texi/tar.texi(,296) * controlling pattern-matching::
+../tar_texi/tar.texi(,297)
+../tar_texi/tar.texi(,298) Crossing File System Boundaries
+../tar_texi/tar.texi(,299)
+../tar_texi/tar.texi(,300) * directory:: Changing Directory
+../tar_texi/tar.texi(,301) * absolute:: Absolute File Names
+../tar_texi/tar.texi(,302)
+../tar_texi/tar.texi(,303) Date input formats
+../tar_texi/tar.texi(,304)
+../tar_texi/tar.texi(,305) * General date syntax:: Common rules.
+../tar_texi/tar.texi(,306) * Calendar date items:: 19 Dec 1994.
+../tar_texi/tar.texi(,307) * Time of day items:: 9:20pm.
+../tar_texi/tar.texi(,308) * Time zone items:: @sc{est},
@sc{pdt}, @sc{gmt}.
+../tar_texi/tar.texi(,309) * Day of week items:: Monday and
others.
+../tar_texi/tar.texi(,310) * Relative items in date strings:: next tuesday, 2
years ago.
+../tar_texi/tar.texi(,311) * Pure numbers in date strings:: 19931219, 1440.
+../tar_texi/tar.texi(,312) * Seconds since the Epoch:: @@1078100502.
+../tar_texi/tar.texi(,313) * Specifying time zone rules::
TZ="America/New_York", TZ="UTC0".
+../tar_texi/tar.texi(,314) * Authors of get_date:: Bellovin,
Eggert, Salz, Berets, et al.
+../tar_texi/tar.texi(,315)
+../tar_texi/tar.texi(,316) Controlling the Archive Format
+../tar_texi/tar.texi(,317)
+../tar_texi/tar.texi(,318) * Portability:: Making
@command{tar} Archives More Portable
+../tar_texi/tar.texi(,319) * Compression:: Using Less Space
through Compression
+../tar_texi/tar.texi(,320) * Attributes:: Handling File
Attributes
+../tar_texi/tar.texi(,321) * cpio:: Comparison of
@command{tar} and @command{cpio}
+../tar_texi/tar.texi(,322)
+../tar_texi/tar.texi(,323) Making @command{tar} Archives More Portable
+../tar_texi/tar.texi(,324)
+../tar_texi/tar.texi(,325) * Portable Names:: Portable Names
+../tar_texi/tar.texi(,326) * dereference:: Symbolic Links
+../tar_texi/tar.texi(,327) * old:: Old V7 Archives
+../tar_texi/tar.texi(,328) * ustar:: Ustar Archives
+../tar_texi/tar.texi(,329) * gnu:: GNU and old GNU
format archives.
+../tar_texi/tar.texi(,330) * posix:: @acronym{POSIX}
archives
+../tar_texi/tar.texi(,331) * Checksumming:: Checksumming
Problems
+../tar_texi/tar.texi(,332) * Large or Negative Values:: Large files,
negative time stamps, etc.
+../tar_texi/tar.texi(,333) * Other Tars:: How to Extract
GNU-Specific Data Using
+../tar_texi/tar.texi(,334) Other @command{tar}
Implementations
+../tar_texi/tar.texi(,335)
+../tar_texi/tar.texi(GNUTAR,336) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,336) and @acronym{POSIX} @command{tar}
+../tar_texi/tar.texi(,337)
+../tar_texi/tar.texi(,338) * PAX keywords:: Controlling Extended Header
Keywords.
+../tar_texi/tar.texi(,339)
+../tar_texi/tar.texi(,340) How to Extract GNU-Specific Data Using Other
@command{tar} Implementations
+../tar_texi/tar.texi(,341)
+../tar_texi/tar.texi(,342) * Split Recovery:: Members Split Between
Volumes
+../tar_texi/tar.texi(,343) * Sparse Recovery:: Sparse Members
+../tar_texi/tar.texi(,344)
+../tar_texi/tar.texi(,345) Using Less Space through Compression
+../tar_texi/tar.texi(,346)
+../tar_texi/tar.texi(,347) * gzip:: Creating and
Reading Compressed Archives
+../tar_texi/tar.texi(,348) * sparse:: Archiving Sparse
Files
+../tar_texi/tar.texi(,349)
+../tar_texi/tar.texi(,350) Tapes and Other Archive Media
+../tar_texi/tar.texi(,351)
+../tar_texi/tar.texi(,352) * Device:: Device selection
and switching
+../tar_texi/tar.texi(,353) * Remote Tape Server::
+../tar_texi/tar.texi(,354) * Common Problems and Solutions::
+../tar_texi/tar.texi(,355) * Blocking:: Blocking
+../tar_texi/tar.texi(,356) * Many:: Many archives on
one tape
+../tar_texi/tar.texi(,357) * Using Multiple Tapes:: Using Multiple Tapes
+../tar_texi/tar.texi(,358) * label:: Including a Label
in the Archive
+../tar_texi/tar.texi(,359) * verify::
+../tar_texi/tar.texi(,360) * Write Protection::
+../tar_texi/tar.texi(,361)
+../tar_texi/tar.texi(,362) Blocking
+../tar_texi/tar.texi(,363)
+../tar_texi/tar.texi(,364) * Format Variations:: Format Variations
+../tar_texi/tar.texi(,365) * Blocking Factor:: The Blocking Factor
of an Archive
+../tar_texi/tar.texi(,366)
+../tar_texi/tar.texi(,367) Many Archives on One Tape
+../tar_texi/tar.texi(,368)
+../tar_texi/tar.texi(,369) * Tape Positioning:: Tape Positions and
Tape Marks
+../tar_texi/tar.texi(,370) * mt:: The @command{mt}
Utility
+../tar_texi/tar.texi(,371)
+../tar_texi/tar.texi(,372) Using Multiple Tapes
+../tar_texi/tar.texi(,373)
+../tar_texi/tar.texi(,374) * Multi-Volume Archives:: Archives Longer
than One Tape or Disk
+../tar_texi/tar.texi(,375) * Tape Files:: Tape Files
+../tar_texi/tar.texi(,376) * Tarcat:: Concatenate Volumes
into a Single Archive
+../tar_texi/tar.texi(,377)
+../tar_texi/tar.texi(,378)
+../tar_texi/tar.texi(,379) Tar Internals
+../tar_texi/tar.texi(,380)
+../tar_texi/tar.texi(,381) * Standard:: Basic Tar Format
+../tar_texi/tar.texi(,382) * Extensions:: @acronym{GNU} Extensions to
the Archive Format
+../tar_texi/tar.texi(,383) * Sparse Formats:: Storing Sparse Files
+../tar_texi/tar.texi(,384) * Snapshot Files::
+../tar_texi/tar.texi(,385) * Dumpdir::
+../tar_texi/tar.texi(,386)
+../tar_texi/tar.texi(,387) Storing Sparse Files
+../tar_texi/tar.texi(,388)
+../tar_texi/tar.texi(,389) * Old GNU Format::
+../tar_texi/tar.texi(,390) * PAX 0:: PAX Format, Versions 0.0
and 0.1
+../tar_texi/tar.texi(,391) * PAX 1:: PAX Format, Version 1.0
+../tar_texi/tar.texi(,392)
+../tar_texi/tar.texi(,393) Genfile
+../tar_texi/tar.texi(,394)
+../tar_texi/tar.texi(,395) * Generate Mode:: File Generation Mode.
+../tar_texi/tar.texi(,396) * Status Mode:: File Status Mode.
+../tar_texi/tar.texi(,397) * Exec Mode:: Synchronous Execution mode.
+../tar_texi/tar.texi(,398)
+../tar_texi/tar.texi(,399) Copying This Manual
+../tar_texi/tar.texi(,400)
+../tar_texi/tar.texi(,401) * GNU Free Documentation License:: License for
copying this manual
+../tar_texi/tar.texi(,402)
+../tar_texi/tar.texi(,403) @end detailmenu
+../tar_texi/tar.texi(,404) @end menu
+../tar_texi/tar.texi(,405)
+../tar_texi/tar.texi(,406) @node Introduction
+../tar_texi/tar.texi(,407) @chapter Introduction
+../tar_texi/tar.texi(,408)
+../tar_texi/tar.texi(GNUTAR,409) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,409) creates
+../tar_texi/tar.texi(,410) and manipulates @dfn{archives} which are actually
collections of
+../tar_texi/tar.texi(,411) many other files; the program provides users with
an organized and
+../tar_texi/tar.texi(,412) systematic method for controlling a large amount of
data.
+../tar_texi/tar.texi(,413) The name ``tar'' originally came from the phrase
``Tape ARchive'', but
+../tar_texi/tar.texi(,414) archives need not (and these days, typically do
not) reside on tapes.
+../tar_texi/tar.texi(,415)
+../tar_texi/tar.texi(,416) @menu
+../tar_texi/tar.texi(,417) * Book Contents:: What this Book
Contains
+../tar_texi/tar.texi(,418) * Definitions:: Some Definitions
+../tar_texi/tar.texi(,419) * What tar Does:: What @command{tar}
Does
+../tar_texi/tar.texi(,420) * Naming tar Archives:: How @command{tar}
Archives are Named
+../tar_texi/tar.texi(GNUTAR,421) * Authors::
../tar_texi/tar.texi(GNUTAR,421) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,421) Authors
+../tar_texi/tar.texi(,422) * Reports:: Reporting bugs or
suggestions
+../tar_texi/tar.texi(,423) @end menu
+../tar_texi/tar.texi(,424)
+../tar_texi/tar.texi(,425) @node Book Contents
+../tar_texi/tar.texi(,426) @section What this Book Contains
+../tar_texi/tar.texi(,427)
+../tar_texi/tar.texi(,428) The first part of this chapter introduces you to
various terms that will
+../tar_texi/tar.texi(GNUTAR,429) recur throughout the book. It also tells you
who has worked on ../tar_texi/tar.texi(GNUTAR,429) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,429)
+../tar_texi/tar.texi(,430) and its documentation, and where you should send
bug reports
+../tar_texi/tar.texi(,431) or comments.
+../tar_texi/tar.texi(,432)
+../tar_texi/tar.texi(,433) The second chapter is a tutorial (@pxref{Tutorial})
which provides a
+../tar_texi/tar.texi(,434) gentle introduction for people who are new to using
@command{tar}. It is
+../tar_texi/tar.texi(,435) meant to be self contained, not requiring any
reading from subsequent
+../tar_texi/tar.texi(,436) chapters to make sense. It moves from topic to
topic in a logical,
+../tar_texi/tar.texi(,437) progressive order, building on information already
explained.
+../tar_texi/tar.texi(,438)
+../tar_texi/tar.texi(,439) Although the tutorial is paced and structured to
allow beginners to
+../tar_texi/tar.texi(,440) learn how to use @command{tar}, it is not intended
solely for beginners.
+../tar_texi/tar.texi(,441) The tutorial explains how to use the three most
frequently used
+../tar_texi/tar.texi(,442) operations (@samp{create}, @samp{list}, and
@samp{extract}) as well as
+../tar_texi/tar.texi(,443) two frequently used options (@samp{file} and
@samp{verbose}). The other
+../tar_texi/tar.texi(,444) chapters do not refer to the tutorial frequently;
however, if a section
+../tar_texi/tar.texi(,445) discusses something which is a complex variant of a
basic concept, there
+../tar_texi/tar.texi(,446) may be a cross reference to that basic concept.
(The entire book,
+../tar_texi/tar.texi(,447) including the tutorial, assumes that the reader
understands some basic
+../tar_texi/tar.texi(,448) concepts of using a Unix-type operating system;
@pxref{Tutorial}.)
+../tar_texi/tar.texi(,449)
+../tar_texi/tar.texi(,450) The third chapter presents the remaining five
operations, and
+../tar_texi/tar.texi(,451) information about using @command{tar} options and
option syntax.
+../tar_texi/tar.texi(,452)
+../tar_texi/tar.texi(FIXME,455) @allow-recursion
+../tar_texi/tar.texi(FIXME,455) @quote-arg
+../tar_texi/tar.texi(FIXME,455) The other chapters are meant to be used as a
+../tar_texi/tar.texi(,456) reference. Each chapter presents everything that
needs to be said
+../tar_texi/tar.texi(,457) about a specific topic.
+../tar_texi/tar.texi(,458)
+../tar_texi/tar.texi(,459) One of the chapters (@pxref{Date input formats})
exists in its
+../tar_texi/tar.texi(,460) entirety in other @acronym{GNU} manuals, and is
mostly self-contained.
+../tar_texi/tar.texi(,461) In addition, one section of this manual
(@pxref{Standard}) contains a
+../tar_texi/tar.texi(,462) big quote which is taken directly from
@command{tar} sources.
+../tar_texi/tar.texi(,463)
+../tar_texi/tar.texi(,464) In general, we give both long and short
(abbreviated) option names
+../tar_texi/tar.texi(,465) at least once in each section where the relevant
option is covered, so
+../tar_texi/tar.texi(,466) that novice readers will become familiar with both
styles. (A few
+../tar_texi/tar.texi(,467) options have no short versions, and the relevant
sections will
+../tar_texi/tar.texi(,468) indicate this.)
+../tar_texi/tar.texi(,469)
+../tar_texi/tar.texi(,470) @node Definitions
+../tar_texi/tar.texi(,471) @section Some Definitions
+../tar_texi/tar.texi(,472)
+../tar_texi/tar.texi(,473) @cindex archive
+../tar_texi/tar.texi(,474) @cindex tar archive
+../tar_texi/tar.texi(,475) The @command{tar} program is used to create and
manipulate @command{tar}
+../tar_texi/tar.texi(,476) archives. An @dfn{archive} is a single file which
contains the contents
+../tar_texi/tar.texi(,477) of many files, while still identifying the names of
the files, their
+../tar_texi/tar.texi(,478) owner(s), and so forth. (In addition, archives
record access
+../tar_texi/tar.texi(,479) permissions, user and group, size in bytes, and
data modification time.
+../tar_texi/tar.texi(,480) Some archives also record the file names in each
archived directory, as
+../tar_texi/tar.texi(,481) well as other file and directory information.) You
can use @command{tar}
+../tar_texi/tar.texi(,482) to @dfn{create} a new archive in a specified
directory.
+../tar_texi/tar.texi(,483)
+../tar_texi/tar.texi(,484) @cindex member
+../tar_texi/tar.texi(,485) @cindex archive member
+../tar_texi/tar.texi(,486) @cindex file name
+../tar_texi/tar.texi(,487) @cindex member name
+../tar_texi/tar.texi(,488) The files inside an archive are called
@dfn{members}. Within this
+../tar_texi/tar.texi(,489) manual, we use the term @dfn{file} to refer only to
files accessible in
+../tar_texi/tar.texi(,490) the normal ways (by @command{ls}, @command{cat},
and so forth), and the term
+../tar_texi/tar.texi(,491) @dfn{member} to refer only to the members of an
archive. Similarly, a
+../tar_texi/tar.texi(,492) @dfn{file name} is the name of a file, as it
resides in the file system,
+../tar_texi/tar.texi(,493) and a @dfn{member name} is the name of an archive
member within the
+../tar_texi/tar.texi(,494) archive.
+../tar_texi/tar.texi(,495)
+../tar_texi/tar.texi(,496) @cindex extraction
+../tar_texi/tar.texi(,497) @cindex unpacking
+../tar_texi/tar.texi(,498) The term @dfn{extraction} refers to the process of
copying an archive
+../tar_texi/tar.texi(,499) member (or multiple members) into a file in the
file system. Extracting
+../tar_texi/tar.texi(,500) all the members of an archive is often called
@dfn{extracting the
+../tar_texi/tar.texi(,501) archive}. The term @dfn{unpack} can also be used
to refer to the
+../tar_texi/tar.texi(,502) extraction of many or all the members of an
archive. Extracting an
+../tar_texi/tar.texi(,503) archive does not destroy the archive's structure,
just as creating an
+../tar_texi/tar.texi(,504) archive does not destroy the copies of the files
that exist outside of
+../tar_texi/tar.texi(,505) the archive. You may also @dfn{list} the members
in a given archive
+../tar_texi/tar.texi(,506) (this is often thought of as ``printing'' them to
the standard output,
+../tar_texi/tar.texi(,507) or the command line), or @dfn{append} members to a
pre-existing archive.
+../tar_texi/tar.texi(,508) All of these operations can be performed using
@command{tar}.
+../tar_texi/tar.texi(,509)
+../tar_texi/tar.texi(,510) @node What tar Does
+../tar_texi/tar.texi(,511) @section What @command{tar} Does
+../tar_texi/tar.texi(,512)
+../tar_texi/tar.texi(,513) @cindex tar
+../tar_texi/tar.texi(,514) The @command{tar} program provides the ability to
create @command{tar}
+../tar_texi/tar.texi(,515) archives, as well as various other kinds of
manipulation. For example,
+../tar_texi/tar.texi(,516) you can use @command{tar} on previously created
archives to extract files,
+../tar_texi/tar.texi(,517) to store additional files, or to update or list
files which were already
+../tar_texi/tar.texi(,518) stored.
+../tar_texi/tar.texi(,519)
+../tar_texi/tar.texi(,520) Initially, @command{tar} archives were used to
store files conveniently on
+../tar_texi/tar.texi(,521) magnetic tape. The name @command{tar} comes from
this use; it stands for
+../tar_texi/tar.texi(,522) @code{t}ape @code{ar}chiver. Despite the utility's
name, @command{tar} can
+../tar_texi/tar.texi(,523) direct its output to available devices, files, or
other programs (using
+../tar_texi/tar.texi(,524) pipes). @command{tar} may even access remote
devices or files (as archives).
+../tar_texi/tar.texi(,525)
+../tar_texi/tar.texi(,526) You can use @command{tar} archives in many ways.
We want to stress a few
+../tar_texi/tar.texi(,527) of them: storage, backup, and transportation.
+../tar_texi/tar.texi(,528)
+../tar_texi/tar.texi(FIXME,529) @allow-recursion
+../tar_texi/tar.texi(FIXME,529) @quote-arg
+../tar_texi/tar.texi(FIXME,529)
+../tar_texi/tar.texi(,530) @table @asis
+../tar_texi/tar.texi(,531) @item Storage
+../tar_texi/tar.texi(,532) Often, @command{tar} archives are used to store
related files for
+../tar_texi/tar.texi(,533) convenient file transfer over a network. For
example, the
+../tar_texi/tar.texi(,534) @acronym{GNU} Project distributes its software
bundled into
+../tar_texi/tar.texi(,535) @command{tar} archives, so that all the files
relating to a particular
+../tar_texi/tar.texi(,536) program (or set of related programs) can be
transferred as a single
+../tar_texi/tar.texi(,537) unit.
+../tar_texi/tar.texi(,538)
+../tar_texi/tar.texi(,539) A magnetic tape can store several files in
sequence. However, the tape
+../tar_texi/tar.texi(,540) has no names for these files; it only knows their
relative position on
+../tar_texi/tar.texi(,541) the tape. One way to store several files on one
tape and retain their
+../tar_texi/tar.texi(,542) names is by creating a @command{tar} archive. Even
when the basic transfer
+../tar_texi/tar.texi(,543) mechanism can keep track of names, as FTP can, the
nuisance of handling
+../tar_texi/tar.texi(,544) multiple files, directories, and multiple links
makes @command{tar}
+../tar_texi/tar.texi(,545) archives useful.
+../tar_texi/tar.texi(,546)
+../tar_texi/tar.texi(,547) Archive files are also used for long-term storage.
You can think of
+../tar_texi/tar.texi(,548) this as transportation from the present into the
future. (It is a
+../tar_texi/tar.texi(,549) science-fiction idiom that you can move through
time as well as in
+../tar_texi/tar.texi(,550) space; the idea here is that @command{tar} can be
used to move archives in
+../tar_texi/tar.texi(,551) all dimensions, even time!)
+../tar_texi/tar.texi(,552)
+../tar_texi/tar.texi(,553) @item Backup
+../tar_texi/tar.texi(,554) Because the archive created by @command{tar} is
capable of preserving
+../tar_texi/tar.texi(,555) file information and directory structure,
@command{tar} is commonly
+../tar_texi/tar.texi(,556) used for performing full and incremental backups of
disks. A backup
+../tar_texi/tar.texi(,557) puts a collection of files (possibly pertaining to
many users and
+../tar_texi/tar.texi(,558) projects) together on a disk or a tape. This
guards against
+../tar_texi/tar.texi(,559) accidental destruction of the information in those
files.
+../tar_texi/tar.texi(GNUTAR,560) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,560) has special features that allow
it to be
+../tar_texi/tar.texi(,561) used to make incremental and full dumps of all the
files in a
+../tar_texi/tar.texi(,562) file system.
+../tar_texi/tar.texi(,563)
+../tar_texi/tar.texi(,564) @item Transportation
+../tar_texi/tar.texi(,565) You can create an archive on one system, transfer
it to another system,
+../tar_texi/tar.texi(,566) and extract the contents there. This allows you to
transport a group of
+../tar_texi/tar.texi(,567) files from one system to another.
+../tar_texi/tar.texi(,568) @end table
+../tar_texi/tar.texi(,569)
+../tar_texi/tar.texi(,570) @node Naming tar Archives
+../tar_texi/tar.texi(,571) @section How @command{tar} Archives are Named
+../tar_texi/tar.texi(,572)
+../tar_texi/tar.texi(,573) Conventionally, @command{tar} archives are given
names ending with
+../tar_texi/tar.texi(,574) @samp{.tar}. This is not necessary for
@command{tar} to operate properly,
+../tar_texi/tar.texi(,575) but this manual follows that convention in order to
accustom readers to
+../tar_texi/tar.texi(,576) it and to make examples more clear.
+../tar_texi/tar.texi(,577)
+../tar_texi/tar.texi(,578) @cindex tar file
+../tar_texi/tar.texi(,579) @cindex entry
+../tar_texi/tar.texi(,580) @cindex tar entry
+../tar_texi/tar.texi(,581) Often, people refer to @command{tar} archives as
address@hidden files,'' and
+../tar_texi/tar.texi(,582) archive members as ``files'' or ``entries''. For
people familiar with
+../tar_texi/tar.texi(,583) the operation of @command{tar}, this causes no
difficulty. However, in
+../tar_texi/tar.texi(,584) this manual, we consistently refer to ``archives''
and ``archive
+../tar_texi/tar.texi(,585) members'' to make learning to use @command{tar}
easier for novice users.
+../tar_texi/tar.texi(,586)
+../tar_texi/tar.texi(,587) @node Authors
+../tar_texi/tar.texi(GNUTAR,588) @section ../tar_texi/tar.texi(GNUTAR,588)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,588) Authors
+../tar_texi/tar.texi(,589)
+../tar_texi/tar.texi(GNUTAR,590) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,590) was originally written by John
Gilmore,
+../tar_texi/tar.texi(,591) and modified by many people. The @acronym{GNU}
enhancements were
+../tar_texi/tar.texi(,592) written by Jay Fenlason, then Joy Kendall, and the
whole package has
+../tar_texi/tar.texi(,593) been further maintained by Thomas Bushnell, n/BSG,
address@hidden
+../tar_texi/tar.texi(,594) Pinard, Paul Eggert, and finally Sergey Poznyakoff
with the help of
+../tar_texi/tar.texi(,595) numerous and kind users.
+../tar_texi/tar.texi(,596)
+../tar_texi/tar.texi(,597) We wish to stress that @command{tar} is a
collective work, and owes much to
+../tar_texi/tar.texi(,598) all those people who reported problems, offered
solutions and other
+../tar_texi/tar.texi(,599) insights, or shared their thoughts and suggestions.
An impressive, yet
+../tar_texi/tar.texi(,600) partial list of those contributors can be found in
the @file{THANKS}
+../tar_texi/tar.texi(GNUTAR,601) file from the
../tar_texi/tar.texi(GNUTAR,601) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,601) distribution.
+../tar_texi/tar.texi(,602)
+../tar_texi/tar.texi(FIXME,606) @allow-recursion
+../tar_texi/tar.texi(FIXME,606) @quote-arg
+../tar_texi/tar.texi(FIXME,606)
+../tar_texi/tar.texi(,607)
+../tar_texi/tar.texi(FIXME,609) @allow-recursion
+../tar_texi/tar.texi(FIXME,609) @quote-arg
+../tar_texi/tar.texi(FIXME,609)
+../tar_texi/tar.texi(,610)
+../tar_texi/tar.texi(GNUTAR,611) Jay Fenlason put together a draft of a
../tar_texi/tar.texi(GNUTAR,611) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,611)
+../tar_texi/tar.texi(,612) manual, borrowing notes from the original man page
from John Gilmore.
+../tar_texi/tar.texi(,613) This was withdrawn in version 1.11. Thomas
Bushnell, n/BSG and Amy
+../tar_texi/tar.texi(GNUTAR,614) Gorin worked on a tutorial and manual for
../tar_texi/tar.texi(GNUTAR,614) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,614) .
+../tar_texi/tar.texi(,615) address@hidden Pinard put version 1.11.8 of the
manual together by
+../tar_texi/tar.texi(,616) taking information from all these sources and
merging them. Melissa
+../tar_texi/tar.texi(,617) Weisshaus finally edited and redesigned the book to
create version
+../tar_texi/tar.texi(,618) 1.12. The book for versions from 1.14 up to
1.15.92 were edited
+../tar_texi/tar.texi(,619) by the current maintainer, Sergey Poznyakoff.
+../tar_texi/tar.texi(,620)
+../tar_texi/tar.texi(,621) For version 1.12, Daniel Hagerty contributed a
great deal of technical
+../tar_texi/tar.texi(,622) consulting. In particular, he is the primary
author of @ref{Backups}.
+../tar_texi/tar.texi(,623)
+../tar_texi/tar.texi(GNUTAR,624) In July, 2003
../tar_texi/tar.texi(GNUTAR,624) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,624) was put on CVS at
savannah.gnu.org
+../tar_texi/tar.texi(,625) (see @url{http://savannah.gnu.org/projects/tar}),
and
+../tar_texi/tar.texi(,626) active development and maintenance work has started
+../tar_texi/tar.texi(GNUTAR,627) again. Currently
../tar_texi/tar.texi(GNUTAR,627) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,627) is being maintained by Paul
Eggert, Sergey
+../tar_texi/tar.texi(,628) Poznyakoff and Jeff Bailey.
+../tar_texi/tar.texi(,629)
+../tar_texi/tar.texi(,630) Support for @acronym{POSIX} archives was added by
Sergey Poznyakoff.
+../tar_texi/tar.texi(,631)
+../tar_texi/tar.texi(,632) @node Reports
+../tar_texi/tar.texi(,633) @section Reporting bugs or suggestions
+../tar_texi/tar.texi(,634)
+../tar_texi/tar.texi(,635) @cindex bug reports
+../tar_texi/tar.texi(,636) @cindex reporting bugs
+../tar_texi/tar.texi(,637) If you find problems or have suggestions about this
program or manual,
+../tar_texi/tar.texi(,638) please report them to @file{bug-tar@@gnu.org}.
+../tar_texi/tar.texi(,639)
+../tar_texi/tar.texi(,640) When reporting a bug, please be sure to include as
much detail as
+../tar_texi/tar.texi(FIXME,643) possible, in order to reproduce it.
../tar_texi/tar.texi(FIXME,643) @allow-recursion
+../tar_texi/tar.texi(FIXME,643) @quote-arg
+../tar_texi/tar.texi(FIXME,643) .
+../tar_texi/tar.texi(,644)
+../tar_texi/tar.texi(,645) @node Tutorial
+../tar_texi/tar.texi(,646) @chapter Tutorial Introduction to @command{tar}
+../tar_texi/tar.texi(,647)
+../tar_texi/tar.texi(,648) This chapter guides you through some basic examples
of three @command{tar}
+../tar_texi/tar.texi(,649) operations: @option{--create}, @option{--list}, and
@option{--extract}. If
+../tar_texi/tar.texi(,650) you already know how to use some other version of
@command{tar}, then you
+../tar_texi/tar.texi(,651) may not need to read this chapter. This chapter
omits most complicated
+../tar_texi/tar.texi(,652) details about how @command{tar} works.
+../tar_texi/tar.texi(,653)
+../tar_texi/tar.texi(,654) @menu
+../tar_texi/tar.texi(,655) * assumptions::
+../tar_texi/tar.texi(,656) * stylistic conventions::
+../tar_texi/tar.texi(,657) * basic tar options:: Basic @command{tar}
Operations and Options
+../tar_texi/tar.texi(,658) * frequent operations::
+../tar_texi/tar.texi(,659) * Two Frequent Options::
+../tar_texi/tar.texi(,660) * create:: How to Create
Archives
+../tar_texi/tar.texi(,661) * list:: How to List Archives
+../tar_texi/tar.texi(,662) * extract:: How to Extract
Members from an Archive
+../tar_texi/tar.texi(,663) * going further::
+../tar_texi/tar.texi(,664) @end menu
+../tar_texi/tar.texi(,665)
+../tar_texi/tar.texi(,666) @node assumptions
+../tar_texi/tar.texi(,667) @section Assumptions this Tutorial Makes
+../tar_texi/tar.texi(,668)
+../tar_texi/tar.texi(,669) This chapter is paced to allow beginners to learn
about @command{tar}
+../tar_texi/tar.texi(,670) slowly. At the same time, we will try to cover all
the basic aspects of
+../tar_texi/tar.texi(,671) these three operations. In order to accomplish
both of these tasks, we
+../tar_texi/tar.texi(,672) have made certain assumptions about your knowledge
before reading this
+../tar_texi/tar.texi(,673) manual, and the hardware you will be using:
+../tar_texi/tar.texi(,674)
+../tar_texi/tar.texi(,675) @itemize @bullet
+../tar_texi/tar.texi(,676) @item
+../tar_texi/tar.texi(,677) Before you start to work through this tutorial, you
should understand
+../tar_texi/tar.texi(,678) what the terms ``archive'' and ``archive member''
mean
+../tar_texi/tar.texi(,679) (@pxref{Definitions}). In addition, you should
understand something
+../tar_texi/tar.texi(,680) about how Unix-type operating systems work, and you
should know how to
+../tar_texi/tar.texi(,681) use some basic utilities. For example, you should
know how to create,
+../tar_texi/tar.texi(,682) list, copy, rename, edit, and delete files and
directories; how to
+../tar_texi/tar.texi(,683) change between directories; and how to figure out
where you are in the
+../tar_texi/tar.texi(,684) file system. You should have some basic
understanding of directory
+../tar_texi/tar.texi(,685) structure and how files are named according to
which directory they are
+../tar_texi/tar.texi(,686) in. You should understand concepts such as
standard output and standard
+../tar_texi/tar.texi(,687) input, what various definitions of the term
``argument'' mean, and the
+../tar_texi/tar.texi(FIXME,689) differences between relative and absolute path
names. ../tar_texi/tar.texi(FIXME,689) @allow-recursion
+../tar_texi/tar.texi(FIXME,689) @quote-arg
+../tar_texi/tar.texi(FIXME,689)
+../tar_texi/tar.texi(,690)
+../tar_texi/tar.texi(,691) @item
+../tar_texi/tar.texi(,692) This manual assumes that you are working from your
own home directory
+../tar_texi/tar.texi(,693) (unless we state otherwise). In this tutorial, you
will create a
+../tar_texi/tar.texi(,694) directory to practice @command{tar} commands in.
When we show path names,
+../tar_texi/tar.texi(,695) we will assume that those paths are relative to
your home directory.
+../tar_texi/tar.texi(,696) For example, my home directory path is
@file{/home/fsf/melissa}. All of
+../tar_texi/tar.texi(,697) my examples are in a subdirectory of the directory
named by that path
+../tar_texi/tar.texi(,698) name; the subdirectory is called @file{practice}.
+../tar_texi/tar.texi(,699)
+../tar_texi/tar.texi(,700) @item
+../tar_texi/tar.texi(,701) In general, we show examples of archives which
exist on (or can be
+../tar_texi/tar.texi(,702) written to, or worked with from) a directory on a
hard disk. In most
+../tar_texi/tar.texi(,703) cases, you could write those archives to, or work
with them on any other
+../tar_texi/tar.texi(,704) device, such as a tape drive. However, some of the
later examples in
+../tar_texi/tar.texi(,705) the tutorial and next chapter will not work on tape
drives.
+../tar_texi/tar.texi(,706) Additionally, working with tapes is much more
complicated than working
+../tar_texi/tar.texi(,707) with hard disks. For these reasons, the tutorial
does not cover working
+../tar_texi/tar.texi(,708) with tape drives. @xref{Media}, for complete
information on using
+../tar_texi/tar.texi(,709) @command{tar} archives with tape drives.
+../tar_texi/tar.texi(,710)
+../tar_texi/tar.texi(FIXME,711) @allow-recursion
+../tar_texi/tar.texi(FIXME,711) @quote-arg
+../tar_texi/tar.texi(FIXME,711)
+../tar_texi/tar.texi(,712) @end itemize
+../tar_texi/tar.texi(,713)
+../tar_texi/tar.texi(,714) @node stylistic conventions
+../tar_texi/tar.texi(,715) @section Stylistic Conventions
+../tar_texi/tar.texi(,716)
+../tar_texi/tar.texi(,717) In the examples, @samp{$} represents a typical
shell prompt. It
+../tar_texi/tar.texi(,718) precedes lines you should type; to make this more
clear, those lines are
+../tar_texi/tar.texi(,719) shown in @kbd{this font}, as opposed to lines which
represent the
+../tar_texi/tar.texi(,720) computer's response; those lines are shown in
@code{this font}, or
+../tar_texi/tar.texi(,721) sometimes @samp{like this}.
+../tar_texi/tar.texi(,722)
+../tar_texi/tar.texi(,723) @c When we have lines which are too long to be
+../tar_texi/tar.texi(,724) @c displayed in any other way, we will show them
like this:
+../tar_texi/tar.texi(,725)
+../tar_texi/tar.texi(,726) @node basic tar options
+../tar_texi/tar.texi(,727) @section Basic @command{tar} Operations and Options
+../tar_texi/tar.texi(,728)
+../tar_texi/tar.texi(,729) @command{tar} can take a wide variety of arguments
which specify and define
+../tar_texi/tar.texi(,730) the actions it will have on the particular set of
files or the archive.
+../tar_texi/tar.texi(,731) The main types of arguments to @command{tar} fall
into one of two classes:
+../tar_texi/tar.texi(,732) operations, and options.
+../tar_texi/tar.texi(,733)
+../tar_texi/tar.texi(,734) Some arguments fall into a class called
@dfn{operations}; exactly one of
+../tar_texi/tar.texi(,735) these is both allowed and required for any instance
of using @command{tar};
+../tar_texi/tar.texi(,736) you may @emph{not} specify more than one. People
sometimes speak of
+../tar_texi/tar.texi(,737) @dfn{operating modes}. You are in a particular
operating mode when you
+../tar_texi/tar.texi(,738) have specified the operation which specifies it;
there are eight
+../tar_texi/tar.texi(,739) operations in total, and thus there are eight
operating modes.
+../tar_texi/tar.texi(,740)
+../tar_texi/tar.texi(,741) The other arguments fall into the class known as
@dfn{options}. You are
+../tar_texi/tar.texi(,742) not required to specify any options, and you are
allowed to specify more
+../tar_texi/tar.texi(,743) than one at a time (depending on the way you are
using @command{tar} at
+../tar_texi/tar.texi(,744) that time). Some options are used so frequently,
and are so useful for
+../tar_texi/tar.texi(,745) helping you type commands more carefully that they
are effectively
+../tar_texi/tar.texi(,746) ``required''. We will discuss them in this chapter.
+../tar_texi/tar.texi(,747)
+../tar_texi/tar.texi(,748) You can write most of the @command{tar} operations
and options in any
+../tar_texi/tar.texi(,749) of three forms: long (mnemonic) form, short form,
and old style. Some
+../tar_texi/tar.texi(,750) of the operations and options have no short or
``old'' forms; however,
+../tar_texi/tar.texi(,751) the operations and options which we will cover in
this tutorial have
+../tar_texi/tar.texi(FIXME,753) corresponding abbreviations.
../tar_texi/tar.texi(FIXME,753) @allow-recursion
+../tar_texi/tar.texi(FIXME,753) @quote-arg
+../tar_texi/tar.texi(FIXME,753) We will indicate those abbreviations
appropriately to get
+../tar_texi/tar.texi(,754) you used to seeing them. (Note that the ``old
style'' option forms
+../tar_texi/tar.texi(GNUTAR,755) exist in ../tar_texi/tar.texi(GNUTAR,755)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,755) for compatibility
with Unix
+../tar_texi/tar.texi(,756) @command{tar}. In this book we present a full
discussion of this way
+../tar_texi/tar.texi(,757) of writing options and operations (@pxref{Old
Options}), and we discuss
+../tar_texi/tar.texi(,758) the other two styles of writing options (@xref{Long
Options}, and
+../tar_texi/tar.texi(,759) @pxref{Short Options}).
+../tar_texi/tar.texi(,760)
+../tar_texi/tar.texi(,761) In the examples and in the text of this tutorial,
we usually use the
+../tar_texi/tar.texi(,762) long forms of operations and options; but the
``short'' forms produce
+../tar_texi/tar.texi(,763) the same result and can make typing long
@command{tar} commands easier.
+../tar_texi/tar.texi(,764) For example, instead of typing
+../tar_texi/tar.texi(,765)
+../tar_texi/tar.texi(,766) @smallexample
+../tar_texi/tar.texi(,767) @kbd{tar --create --verbose --file=afiles.tar apple
angst aspic}
+../tar_texi/tar.texi(,768) @end smallexample
+../tar_texi/tar.texi(,769)
+../tar_texi/tar.texi(,770) @noindent
+../tar_texi/tar.texi(,771) you can type
+../tar_texi/tar.texi(,772) @smallexample
+../tar_texi/tar.texi(,773) @kbd{tar -c -v -f afiles.tar apple angst aspic}
+../tar_texi/tar.texi(,774) @end smallexample
+../tar_texi/tar.texi(,775)
+../tar_texi/tar.texi(,776) @noindent
+../tar_texi/tar.texi(,777) or even
+../tar_texi/tar.texi(,778) @smallexample
+../tar_texi/tar.texi(,779) @kbd{tar -cvf afiles.tar apple angst aspic}
+../tar_texi/tar.texi(,780) @end smallexample
+../tar_texi/tar.texi(,781)
+../tar_texi/tar.texi(,782) @noindent
+../tar_texi/tar.texi(,783) For more information on option syntax, see
@ref{Advanced tar}. In
+../tar_texi/tar.texi(,784) discussions in the text, when we name an option by
its long form, we
+../tar_texi/tar.texi(,785) also give the corresponding short option in
parentheses.
+../tar_texi/tar.texi(,786)
+../tar_texi/tar.texi(,787) The term, ``option'', can be confusing at times,
since ``operations''
+../tar_texi/tar.texi(,788) are often lumped in with the actual,
@emph{optional} ``options'' in certain
+../tar_texi/tar.texi(,789) general class statements. For example, we just
talked about ``short and
+../tar_texi/tar.texi(,790) long forms of options and operations''. However,
experienced @command{tar}
+../tar_texi/tar.texi(,791) users often refer to these by shorthand terms such
as, ``short and long
+../tar_texi/tar.texi(,792) options''. This term assumes that the
``operations'' are included, also.
+../tar_texi/tar.texi(,793) Context will help you determine which definition of
``options'' to use.
+../tar_texi/tar.texi(,794)
+../tar_texi/tar.texi(,795) Similarly, the term ``command'' can be confusing,
as it is often used in
+../tar_texi/tar.texi(,796) two different ways. People sometimes refer to
@command{tar} ``commands''.
+../tar_texi/tar.texi(,797) A @command{tar} @dfn{command} is the entire command
line of user input
+../tar_texi/tar.texi(,798) which tells @command{tar} what to do --- including
the operation, options,
+../tar_texi/tar.texi(,799) and any arguments (file names, pipes, other
commands, etc). However,
+../tar_texi/tar.texi(,800) you will also sometimes hear the term ``the
@command{tar} command''. When
+../tar_texi/tar.texi(,801) the word ``command'' is used specifically like
this, a person is usually
+../tar_texi/tar.texi(,802) referring to the @command{tar} @emph{operation},
not the whole line.
+../tar_texi/tar.texi(,803) Again, use context to figure out which of the
meanings the speaker
+../tar_texi/tar.texi(,804) intends.
+../tar_texi/tar.texi(,805)
+../tar_texi/tar.texi(,806) @node frequent operations
+../tar_texi/tar.texi(,807) @section The Three Most Frequently Used Operations
+../tar_texi/tar.texi(,808)
+../tar_texi/tar.texi(,809) Here are the three most frequently used operations
(both short and long
+../tar_texi/tar.texi(,810) forms), as well as a brief description of their
meanings. The rest of
+../tar_texi/tar.texi(,811) this chapter will cover how to use these operations
in detail. We will
+../tar_texi/tar.texi(,812) present the rest of the operations in the next
chapter.
+../tar_texi/tar.texi(,813)
+../tar_texi/tar.texi(,814) @table @option
+../tar_texi/tar.texi(,815) @item --create
+../tar_texi/tar.texi(,816) @itemx -c
+../tar_texi/tar.texi(,817) Create a new @command{tar} archive.
+../tar_texi/tar.texi(,818) @item --list
+../tar_texi/tar.texi(,819) @itemx -t
+../tar_texi/tar.texi(,820) List the contents of an archive.
+../tar_texi/tar.texi(,821) @item --extract
+../tar_texi/tar.texi(,822) @itemx -x
+../tar_texi/tar.texi(,823) Extract one or more members from an archive.
+../tar_texi/tar.texi(,824) @end table
+../tar_texi/tar.texi(,825)
+../tar_texi/tar.texi(,826) @node Two Frequent Options
+../tar_texi/tar.texi(,827) @section Two Frequently Used Options
+../tar_texi/tar.texi(,828)
+../tar_texi/tar.texi(,829) To understand how to run @command{tar} in the three
operating modes listed
+../tar_texi/tar.texi(,830) previously, you also need to understand how to use
two of the options to
+../tar_texi/tar.texi(,831) @command{tar}: @option{--file} (which takes an
archive file as an argument)
+../tar_texi/tar.texi(,832) and @option{--verbose}. (You are usually not
@emph{required} to specify
+../tar_texi/tar.texi(,833) either of these options when you run @command{tar},
but they can be very
+../tar_texi/tar.texi(,834) useful in making things more clear and helping you
avoid errors.)
+../tar_texi/tar.texi(,835)
+../tar_texi/tar.texi(,836) @menu
+../tar_texi/tar.texi(,837) * file tutorial::
+../tar_texi/tar.texi(,838) * verbose tutorial::
+../tar_texi/tar.texi(,839) * help tutorial::
+../tar_texi/tar.texi(,840) @end menu
+../tar_texi/tar.texi(,841)
+../tar_texi/tar.texi(,842) @node file tutorial
+../tar_texi/tar.texi(,843) @unnumberedsubsec The @option{--file} Option
+../tar_texi/tar.texi(,844)
+../tar_texi/tar.texi(,845) @table @option
+../tar_texi/tar.texi(xopindex,846) @opindex address@hidden,
tutorial}../tar_texi/tar.texi(xopindex,846)
+../tar_texi/tar.texi(,847) @item address@hidden
+../tar_texi/tar.texi(,848) @itemx -f @var{archive-name}
+../tar_texi/tar.texi(,849) Specify the name of an archive file.
+../tar_texi/tar.texi(,850) @end table
+../tar_texi/tar.texi(,851)
+../tar_texi/tar.texi(,852) You can specify an argument for the @address@hidden
(@option{-f @var{archive-name}}) option whenever you
+../tar_texi/tar.texi(,853) use @command{tar}; this option determines the name
of the archive file
+../tar_texi/tar.texi(,854) that @command{tar} will work on.
+../tar_texi/tar.texi(,855)
+../tar_texi/tar.texi(,856) @vrindex TAPE
+../tar_texi/tar.texi(,857) If you don't specify this argument, then
@command{tar} will examine
+../tar_texi/tar.texi(,858) the environment variable @env{TAPE}. If it is set,
its value will be
+../tar_texi/tar.texi(,859) used as the archive name. Otherwise, @command{tar}
will use the
+../tar_texi/tar.texi(,860) default archive, determined at the compile time.
Usually it is
+../tar_texi/tar.texi(,861) standard output or some physical tape drive
attached to your machine
+../tar_texi/tar.texi(,862) (you can verify what the default is by running
@kbd{tar
+../tar_texi/tar.texi(,863) --show-defaults}, @pxref{defaults}). If there is
no tape drive
+../tar_texi/tar.texi(,864) attached, or the default is not meaningful, then
@command{tar} will
+../tar_texi/tar.texi(,865) print an error message. The error message might
look roughly like one
+../tar_texi/tar.texi(,866) of the following:
+../tar_texi/tar.texi(,867)
+../tar_texi/tar.texi(,868) @smallexample
+../tar_texi/tar.texi(,869) tar: can't open /dev/rmt8 : No such device or
address
+../tar_texi/tar.texi(,870) tar: can't open /dev/rsmt0 : I/O error
+../tar_texi/tar.texi(,871) @end smallexample
+../tar_texi/tar.texi(,872)
+../tar_texi/tar.texi(,873) @noindent
+../tar_texi/tar.texi(,874) To avoid confusion, we recommend that you always
specify an archive file
+../tar_texi/tar.texi(,875) name by using @address@hidden (@option{-f
@var{archive-name}}) when writing your @command{tar} commands.
+../tar_texi/tar.texi(,876) For more information on using the @address@hidden
(@option{-f @var{archive-name}}) option, see
+../tar_texi/tar.texi(,877) @ref{file}.
+../tar_texi/tar.texi(,878)
+../tar_texi/tar.texi(,879) @node verbose tutorial
+../tar_texi/tar.texi(,880) @unnumberedsubsec The @option{--verbose} Option
+../tar_texi/tar.texi(,881)
+../tar_texi/tar.texi(,882) @table @option
+../tar_texi/tar.texi(xopindex,883) @opindex address@hidden,
introduced}../tar_texi/tar.texi(xopindex,883)
+../tar_texi/tar.texi(,884) @item --verbose
+../tar_texi/tar.texi(,885) @itemx -v
+../tar_texi/tar.texi(,886) Show the files being worked on as @command{tar} is
running.
+../tar_texi/tar.texi(,887) @end table
+../tar_texi/tar.texi(,888)
+../tar_texi/tar.texi(,889) @option{--verbose} (@option{-v}) shows details
about the results of running
+../tar_texi/tar.texi(,890) @command{tar}. This can be especially useful when
the results might not be
+../tar_texi/tar.texi(,891) obvious. For example, if you want to see the
progress of @command{tar} as
+../tar_texi/tar.texi(,892) it writes files into the archive, you can use the
@option{--verbose}
+../tar_texi/tar.texi(,893) option. In the beginning, you may find it useful
to use
+../tar_texi/tar.texi(,894) @option{--verbose} at all times; when you are more
accustomed to
+../tar_texi/tar.texi(,895) @command{tar}, you will likely want to use it at
certain times but not at
+../tar_texi/tar.texi(,896) others. We will use @option{--verbose} at times to
help make something
+../tar_texi/tar.texi(,897) clear, and we will give many examples both using
and not using
+../tar_texi/tar.texi(,898) @option{--verbose} to show the differences.
+../tar_texi/tar.texi(,899)
+../tar_texi/tar.texi(,900) Each instance of @option{--verbose} on the command
line increases the
+../tar_texi/tar.texi(,901) verbosity level by one, so if you need more details
on the output,
+../tar_texi/tar.texi(,902) specify it twice.
+../tar_texi/tar.texi(,903)
+../tar_texi/tar.texi(,904) When reading archives (@option{--list},
@option{--extract},
+../tar_texi/tar.texi(,905) @option{--diff}), @command{tar} by default prints
only the names of
+../tar_texi/tar.texi(,906) the members being extracted. Using
@option{--verbose} will show a full,
+../tar_texi/tar.texi(,907) @command{ls} style member listing.
+../tar_texi/tar.texi(,908)
+../tar_texi/tar.texi(,909) In contrast, when writing archives
(@option{--create}, @option{--append},
+../tar_texi/tar.texi(,910) @option{--update}), @command{tar} does not print
file names by
+../tar_texi/tar.texi(,911) default. So, a single @option{--verbose} option
shows the file names
+../tar_texi/tar.texi(,912) being added to the archive, while two
@option{--verbose} options
+../tar_texi/tar.texi(,913) enable the full listing.
+../tar_texi/tar.texi(,914)
+../tar_texi/tar.texi(,915) For example, to create an archive in verbose mode:
+../tar_texi/tar.texi(,916)
+../tar_texi/tar.texi(,917) @smallexample
+../tar_texi/tar.texi(,918) $ @kbd{tar -cvf afiles.tar apple angst aspic}
+../tar_texi/tar.texi(,919) apple
+../tar_texi/tar.texi(,920) angst
+../tar_texi/tar.texi(,921) aspic
+../tar_texi/tar.texi(,922) @end smallexample
+../tar_texi/tar.texi(,923)
+../tar_texi/tar.texi(,924) @noindent
+../tar_texi/tar.texi(,925) Creating the same archive with the verbosity level
2 could give:
+../tar_texi/tar.texi(,926)
+../tar_texi/tar.texi(,927) @smallexample
+../tar_texi/tar.texi(,928) $ @kbd{tar -cvvf afiles.tar apple angst aspic}
+../tar_texi/tar.texi(,929) -rw-r--r-- gray/staff 62373 2006-06-09 12:06
apple
+../tar_texi/tar.texi(,930) -rw-r--r-- gray/staff 11481 2006-06-09 12:06
angst
+../tar_texi/tar.texi(,931) -rw-r--r-- gray/staff 23152 2006-06-09 12:06
aspic
+../tar_texi/tar.texi(,932) @end smallexample
+../tar_texi/tar.texi(,933)
+../tar_texi/tar.texi(,934) @noindent
+../tar_texi/tar.texi(,935) This works equally well using short or long forms
of options. Using
+../tar_texi/tar.texi(,936) long forms, you would simply write out the mnemonic
form of the option
+../tar_texi/tar.texi(,937) twice, like this:
+../tar_texi/tar.texi(,938)
+../tar_texi/tar.texi(,939) @smallexample
+../tar_texi/tar.texi(,940) $ @kbd{tar --create --verbose --verbose @dots{}}
+../tar_texi/tar.texi(,941) @end smallexample
+../tar_texi/tar.texi(,942)
+../tar_texi/tar.texi(,943) @noindent
+../tar_texi/tar.texi(,944) Note that you must double the hyphens properly each
time.
+../tar_texi/tar.texi(,945)
+../tar_texi/tar.texi(,946) Later in the tutorial, we will give examples using
@address@hidden
+../tar_texi/tar.texi(,947) --verbose}}.
+../tar_texi/tar.texi(,948)
+../tar_texi/tar.texi(,949) @anchor{verbose member listing}
+../tar_texi/tar.texi(,950) The full output consists of six fields:
+../tar_texi/tar.texi(,951)
+../tar_texi/tar.texi(,952) @itemize @bullet
+../tar_texi/tar.texi(,953) @item File type and permissions in symbolic form.
+../tar_texi/tar.texi(,954) These are displayed in the same format as the first
column of
+../tar_texi/tar.texi(,955) @command{ls -l} output (@pxref{What information is
listed,
+../tar_texi/tar.texi(,956) format=verbose, Verbose listing, fileutils, GNU
file utilities}).
+../tar_texi/tar.texi(,957)
+../tar_texi/tar.texi(,958) @item Owner name and group separated by a slash
character.
+../tar_texi/tar.texi(,959) If these data are not available (for example, when
listing a @samp{v7} format
+../tar_texi/tar.texi(,960) archive), numeric ID values are printed instead.
+../tar_texi/tar.texi(,961)
+../tar_texi/tar.texi(,962) @item Size of the file, in bytes.
+../tar_texi/tar.texi(,963)
+../tar_texi/tar.texi(,964) @item File modification date in ISO 8601 format.
+../tar_texi/tar.texi(,965)
+../tar_texi/tar.texi(,966) @item File modification time.
+../tar_texi/tar.texi(,967)
+../tar_texi/tar.texi(,968) @item File name.
+../tar_texi/tar.texi(,969) If the name contains any special characters (white
space, newlines,
+../tar_texi/tar.texi(,970) etc.) these are displayed in an unambiguous form
using so called
+../tar_texi/tar.texi(,971) @dfn{quoting style}. For the detailed discussion
of available styles
+../tar_texi/tar.texi(,972) and on how to use them, see @ref{quoting styles}.
+../tar_texi/tar.texi(,973)
+../tar_texi/tar.texi(,974) Depending on the file type, the name can be
followed by some
+../tar_texi/tar.texi(,975) additional information, described in the following
table:
+../tar_texi/tar.texi(,976)
+../tar_texi/tar.texi(,977) @table @samp
+../tar_texi/tar.texi(,978) @item -> @var{link-name}
+../tar_texi/tar.texi(,979) The file or archive member is a @dfn{symbolic link}
and
+../tar_texi/tar.texi(,980) @var{link-name} is the name of file it links to.
+../tar_texi/tar.texi(,981)
+../tar_texi/tar.texi(,982) @item link to @var{link-name}
+../tar_texi/tar.texi(,983) The file or archive member is a @dfn{hard link} and
@var{link-name} is
+../tar_texi/tar.texi(,984) the name of file it links to.
+../tar_texi/tar.texi(,985)
+../tar_texi/tar.texi(,986) @item --Long Link--
+../tar_texi/tar.texi(,987) The archive member is an old GNU format long link.
You will normally
+../tar_texi/tar.texi(,988) not encounter this.
+../tar_texi/tar.texi(,989)
+../tar_texi/tar.texi(,990) @item --Long Name--
+../tar_texi/tar.texi(,991) The archive member is an old GNU format long name.
You will normally
+../tar_texi/tar.texi(,992) not encounter this.
+../tar_texi/tar.texi(,993)
+../tar_texi/tar.texi(,994) @item --Volume Header--
+../tar_texi/tar.texi(,995) The archive member is a GNU @dfn{volume header}
(@pxref{Tape Files}).
+../tar_texi/tar.texi(,996)
+../tar_texi/tar.texi(,997) @item --Continued at byte @var{n}--
+../tar_texi/tar.texi(,998) Encountered only at the beginning of a multy-volume
archive
+../tar_texi/tar.texi(,999) (@pxref{Using Multiple Tapes}). This archive
member is a continuation
+../tar_texi/tar.texi(,1000) from the previous volume. The number @var{n} gives
the offset where
+../tar_texi/tar.texi(,1001) the original file was split.
+../tar_texi/tar.texi(,1002)
+../tar_texi/tar.texi(,1003) @item --Mangled file names--
+../tar_texi/tar.texi(,1004) This archive member contains @dfn{mangled file
names} declarations,
+../tar_texi/tar.texi(GNUTAR,1005) a special member type that was used by early
versions of ../tar_texi/tar.texi(GNUTAR,1005) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1005) .
+../tar_texi/tar.texi(,1006) You probably will never encounter this, unless you
are reading a very
+../tar_texi/tar.texi(,1007) old archive.
+../tar_texi/tar.texi(,1008)
+../tar_texi/tar.texi(,1009) @item unknown file type @var{c}
+../tar_texi/tar.texi(,1010) An archive member of unknown type. @var{c} is the
type character from
+../tar_texi/tar.texi(,1011) the archive header. If you encounter such a
message, it means that
+../tar_texi/tar.texi(GNUTAR,1012) either your archive contains proprietary
member types ../tar_texi/tar.texi(GNUTAR,1012) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1012) is not
+../tar_texi/tar.texi(,1013) able to handle, or the archive is corrupted.
+../tar_texi/tar.texi(,1014) @end table
+../tar_texi/tar.texi(,1015)
+../tar_texi/tar.texi(,1016) @end itemize
+../tar_texi/tar.texi(,1017)
+../tar_texi/tar.texi(,1018) For example, here is an archive listing containing
most of the special
+../tar_texi/tar.texi(,1019) suffixes explained above:
+../tar_texi/tar.texi(,1020)
+../tar_texi/tar.texi(,1021) @smallexample
+../tar_texi/tar.texi(,1022) @group
+../tar_texi/tar.texi(,1023) V--------- 0/0 1536 2006-06-09 13:07
MyVolume--Volume Header--
+../tar_texi/tar.texi(,1024) -rw-r--r-- gray/staff 456783 2006-06-09 12:06
aspic--Continued at
+../tar_texi/tar.texi(,1025) byte 32456--
+../tar_texi/tar.texi(,1026) -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+../tar_texi/tar.texi(,1027) lrwxrwxrwx gray/staff 0 2006-06-09 13:01
angst -> apple
+../tar_texi/tar.texi(,1028) -rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+../tar_texi/tar.texi(,1029) hrw-r--r-- gray/staff 0 2006-06-09 12:06
music link to blues
+../tar_texi/tar.texi(,1030) @end group
+../tar_texi/tar.texi(,1031) @end smallexample
+../tar_texi/tar.texi(,1032)
+../tar_texi/tar.texi(,1033) @smallexample
+../tar_texi/tar.texi(,1034) @end smallexample
+../tar_texi/tar.texi(,1035)
+../tar_texi/tar.texi(,1036) @node help tutorial
+../tar_texi/tar.texi(,1037) @unnumberedsubsec Getting Help: Using the
@option{--help} Option
+../tar_texi/tar.texi(,1038)
+../tar_texi/tar.texi(,1039) @table @option
+../tar_texi/tar.texi(,1040) @opindex help
+../tar_texi/tar.texi(,1041) @item --help
+../tar_texi/tar.texi(,1042)
+../tar_texi/tar.texi(,1043) The @option{--help} option to @command{tar} prints
out a very brief list of
+../tar_texi/tar.texi(,1044) all operations and option available for the
current version of
+../tar_texi/tar.texi(,1045) @command{tar} available on your system.
+../tar_texi/tar.texi(,1046) @end table
+../tar_texi/tar.texi(,1047)
+../tar_texi/tar.texi(,1048) @node create
+../tar_texi/tar.texi(,1049) @section How to Create Archives
+../tar_texi/tar.texi(UNREVISED,1050) @quotation
+../tar_texi/tar.texi(UNREVISED,1050) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,1050) @end quotation
+../tar_texi/tar.texi(UNREVISED,1050)
+../tar_texi/tar.texi(,1051)
+../tar_texi/tar.texi(,1052) @cindex Creation of the archive
+../tar_texi/tar.texi(,1053) @cindex Archive, creation of
+../tar_texi/tar.texi(,1054) One of the basic operations of @command{tar} is
@option{--create} (@option{-c}), which
+../tar_texi/tar.texi(,1055) you use to create a @command{tar} archive. We
will explain
+../tar_texi/tar.texi(,1056) @option{--create} first because, in order to learn
about the other
+../tar_texi/tar.texi(,1057) operations, you will find it useful to have an
archive available to
+../tar_texi/tar.texi(,1058) practice on.
+../tar_texi/tar.texi(,1059)
+../tar_texi/tar.texi(,1060) To make this easier, in this section you will
first create a directory
+../tar_texi/tar.texi(,1061) containing three files. Then, we will show you
how to create an
+../tar_texi/tar.texi(,1062) @emph{archive} (inside the new directory). Both
the directory, and
+../tar_texi/tar.texi(,1063) the archive are specifically for you to practice
on. The rest of this
+../tar_texi/tar.texi(,1064) chapter and the next chapter will show many
examples using this
+../tar_texi/tar.texi(,1065) directory and the files you will create: some of
those files may be
+../tar_texi/tar.texi(,1066) other directories and other archives.
+../tar_texi/tar.texi(,1067)
+../tar_texi/tar.texi(,1068) The three files you will archive in this example
are called
+../tar_texi/tar.texi(,1069) @file{blues}, @file{folk}, and @file{jazz}. The
archive is called
+../tar_texi/tar.texi(,1070) @file{collection.tar}.
+../tar_texi/tar.texi(,1071)
+../tar_texi/tar.texi(,1072) This section will proceed slowly, detailing how to
use @option{--create}
+../tar_texi/tar.texi(,1073) in @code{verbose} mode, and showing examples using
both short and long
+../tar_texi/tar.texi(,1074) forms. In the rest of the tutorial, and in the
examples in the next
+../tar_texi/tar.texi(,1075) chapter, we will proceed at a slightly quicker
pace. This section
+../tar_texi/tar.texi(,1076) moves more slowly to allow beginning users to
understand how
+../tar_texi/tar.texi(,1077) @command{tar} works.
+../tar_texi/tar.texi(,1078)
+../tar_texi/tar.texi(,1079) @menu
+../tar_texi/tar.texi(,1080) * prepare for examples::
+../tar_texi/tar.texi(,1081) * Creating the archive::
+../tar_texi/tar.texi(,1082) * create verbose::
+../tar_texi/tar.texi(,1083) * short create::
+../tar_texi/tar.texi(,1084) * create dir::
+../tar_texi/tar.texi(,1085) @end menu
+../tar_texi/tar.texi(,1086)
+../tar_texi/tar.texi(,1087) @node prepare for examples
+../tar_texi/tar.texi(,1088) @subsection Preparing a Practice Directory for
Examples
+../tar_texi/tar.texi(,1089)
+../tar_texi/tar.texi(,1090) To follow along with this and future examples,
create a new directory
+../tar_texi/tar.texi(,1091) called @file{practice} containing files called
@file{blues}, @file{folk}
+../tar_texi/tar.texi(,1092) and @file{jazz}. The files can contain any
information you like:
+../tar_texi/tar.texi(,1093) ideally, they should contain information which
relates to their names,
+../tar_texi/tar.texi(,1094) and be of different lengths. Our examples assume
that @file{practice}
+../tar_texi/tar.texi(,1095) is a subdirectory of your home directory.
+../tar_texi/tar.texi(,1096)
+../tar_texi/tar.texi(,1097) Now @command{cd} to the directory named
@file{practice}; @file{practice}
+../tar_texi/tar.texi(,1098) is now your @dfn{working directory}.
(@emph{Please note}: Although
+../tar_texi/tar.texi(,1099) the full path name of this directory is
+../tar_texi/tar.texi(,1100) @file{/@var{homedir}/practice}, in our examples we
will refer to
+../tar_texi/tar.texi(,1101) this directory as @file{practice}; the
@var{homedir} is presumed.
+../tar_texi/tar.texi(,1102)
+../tar_texi/tar.texi(,1103) In general, you should check that the files to be
archived exist where
+../tar_texi/tar.texi(,1104) you think they do (in the working directory) by
running @command{ls}.
+../tar_texi/tar.texi(,1105) Because you just created the directory and the
files and have changed to
+../tar_texi/tar.texi(,1106) that directory, you probably don't need to do that
this time.
+../tar_texi/tar.texi(,1107)
+../tar_texi/tar.texi(,1108) It is very important to make sure there isn't
already a file in the
+../tar_texi/tar.texi(,1109) working directory with the archive name you intend
to use (in this case,
+../tar_texi/tar.texi(,1110) @samp{collection.tar}), or that you don't care
about its contents.
+../tar_texi/tar.texi(,1111) Whenever you use @samp{create}, @command{tar} will
erase the current
+../tar_texi/tar.texi(,1112) contents of the file named by @address@hidden
(@option{-f @var{archive-name}}) if it exists. @command{tar}
+../tar_texi/tar.texi(,1113) will not tell you if you are about to overwrite an
archive unless you
+../tar_texi/tar.texi(,1114) specify an option which does this (@pxref{backup},
for the
+../tar_texi/tar.texi(,1115) information on how to do so). To add files to an
existing archive,
+../tar_texi/tar.texi(,1116) you need to use a different option, such as
@option{--append} (@option{-r}); see
+../tar_texi/tar.texi(,1117) @ref{append} for information on how to do this.
+../tar_texi/tar.texi(,1118)
+../tar_texi/tar.texi(,1119) @node Creating the archive
+../tar_texi/tar.texi(,1120) @subsection Creating the Archive
+../tar_texi/tar.texi(,1121)
+../tar_texi/tar.texi(xopindex,1122) @opindex address@hidden,
introduced}../tar_texi/tar.texi(xopindex,1122)
+../tar_texi/tar.texi(,1123) To place the files @file{blues}, @file{folk}, and
@file{jazz} into an
+../tar_texi/tar.texi(,1124) archive named @file{collection.tar}, use the
following command:
+../tar_texi/tar.texi(,1125)
+../tar_texi/tar.texi(,1126) @smallexample
+../tar_texi/tar.texi(,1127) $ @kbd{tar --create --file=collection.tar blues
folk jazz}
+../tar_texi/tar.texi(,1128) @end smallexample
+../tar_texi/tar.texi(,1129)
+../tar_texi/tar.texi(,1130) The order of the arguments is not very important,
@emph{when using long
+../tar_texi/tar.texi(,1131) option forms}. You could also say:
+../tar_texi/tar.texi(,1132)
+../tar_texi/tar.texi(,1133) @smallexample
+../tar_texi/tar.texi(,1134) $ @kbd{tar blues --create folk
--file=collection.tar jazz}
+../tar_texi/tar.texi(,1135) @end smallexample
+../tar_texi/tar.texi(,1136)
+../tar_texi/tar.texi(,1137) @noindent
+../tar_texi/tar.texi(,1138) However, you can see that this order is harder to
understand; this is
+../tar_texi/tar.texi(,1139) why we will list the arguments in the order that
makes the commands
+../tar_texi/tar.texi(,1140) easiest to understand (and we encourage you to do
the same when you use
+../tar_texi/tar.texi(,1141) @command{tar}, to avoid errors).
+../tar_texi/tar.texi(,1142)
+../tar_texi/tar.texi(,1143) Note that the sequence
+../tar_texi/tar.texi(,1144) @address@hidden is considered to be @emph{one}
argument.
+../tar_texi/tar.texi(,1145) If you substituted any other string of characters
for
+../tar_texi/tar.texi(,1146) @kbd{collection.tar}, then that string would
become the name of the
+../tar_texi/tar.texi(,1147) archive file you create.
+../tar_texi/tar.texi(,1148)
+../tar_texi/tar.texi(,1149) The order of the options becomes more important
when you begin to use
+../tar_texi/tar.texi(,1150) short forms. With short forms, if you type
commands in the wrong order
+../tar_texi/tar.texi(,1151) (even if you type them correctly in all other
ways), you may end up with
+../tar_texi/tar.texi(,1152) results you don't expect. For this reason, it is
a good idea to get
+../tar_texi/tar.texi(,1153) into the habit of typing options in the order that
makes inherent sense.
+../tar_texi/tar.texi(,1154) @xref{short create}, for more information on this.
+../tar_texi/tar.texi(,1155)
+../tar_texi/tar.texi(,1156) In this example, you type the command as shown
above: @option{--create}
+../tar_texi/tar.texi(,1157) is the operation which creates the new archive
+../tar_texi/tar.texi(,1158) (@file{collection.tar}), and @option{--file} is
the option which lets
+../tar_texi/tar.texi(,1159) you give it the name you chose. The files,
@file{blues}, @file{folk},
+../tar_texi/tar.texi(,1160) and @file{jazz}, are now members of the archive,
@file{collection.tar}
+../tar_texi/tar.texi(,1161) (they are @dfn{file name arguments} to the
@option{--create} operation.
+../tar_texi/tar.texi(,1162) @xref{Choosing}, for the detailed discussion on
these.) Now that they are
+../tar_texi/tar.texi(,1163) in the archive, they are called @emph{archive
members}, not files.
+../tar_texi/tar.texi(,1164) (@pxref{Definitions,members}).
+../tar_texi/tar.texi(,1165)
+../tar_texi/tar.texi(,1166) When you create an archive, you @emph{must}
specify which files you
+../tar_texi/tar.texi(,1167) want placed in the archive. If you do not specify
any archive
+../tar_texi/tar.texi(GNUTAR,1168) members, ../tar_texi/tar.texi(GNUTAR,1168)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,1168) will complain.
+../tar_texi/tar.texi(,1169)
+../tar_texi/tar.texi(,1170) If you now list the contents of the working
directory (@command{ls}), you will
+../tar_texi/tar.texi(,1171) find the archive file listed as well as the files
you saw previously:
+../tar_texi/tar.texi(,1172)
+../tar_texi/tar.texi(,1173) @smallexample
+../tar_texi/tar.texi(,1174) blues folk jazz collection.tar
+../tar_texi/tar.texi(,1175) @end smallexample
+../tar_texi/tar.texi(,1176)
+../tar_texi/tar.texi(,1177) @noindent
+../tar_texi/tar.texi(,1178) Creating the archive @samp{collection.tar} did not
destroy the copies of
+../tar_texi/tar.texi(,1179) the files in the directory.
+../tar_texi/tar.texi(,1180)
+../tar_texi/tar.texi(,1181) Keep in mind that if you don't indicate an
operation, @command{tar} will not
+../tar_texi/tar.texi(,1182) run and will prompt you for one. If you don't
name any files, @command{tar}
+../tar_texi/tar.texi(,1183) will complain. You must have write access to the
working directory,
+../tar_texi/tar.texi(,1184) or else you will not be able to create an archive
in that directory.
+../tar_texi/tar.texi(,1185)
+../tar_texi/tar.texi(,1186) @emph{Caution}: Do not attempt to use
@option{--create} (@option{-c}) to add files to
+../tar_texi/tar.texi(,1187) an existing archive; it will delete the archive
and write a new one.
+../tar_texi/tar.texi(,1188) Use @option{--append} (@option{-r}) instead.
@xref{append}.
+../tar_texi/tar.texi(,1189)
+../tar_texi/tar.texi(,1190) @node create verbose
+../tar_texi/tar.texi(,1191) @subsection Running @option{--create} with
@option{--verbose}
+../tar_texi/tar.texi(,1192)
+../tar_texi/tar.texi(xopindex,1193) @opindex address@hidden, using with
@option{--verbose}}../tar_texi/tar.texi(xopindex,1193)
+../tar_texi/tar.texi(xopindex,1194) @opindex address@hidden, using with
@option{--create}}../tar_texi/tar.texi(xopindex,1194)
+../tar_texi/tar.texi(,1195) If you include the @option{--verbose}
(@option{-v}) option on the command line,
+../tar_texi/tar.texi(,1196) @command{tar} will list the files it is acting on
as it is working. In
+../tar_texi/tar.texi(,1197) verbose mode, the @code{create} example above
would appear as:
+../tar_texi/tar.texi(,1198)
+../tar_texi/tar.texi(,1199) @smallexample
+../tar_texi/tar.texi(,1200) $ @kbd{tar --create --verbose
--file=collection.tar blues folk jazz}
+../tar_texi/tar.texi(,1201) blues
+../tar_texi/tar.texi(,1202) folk
+../tar_texi/tar.texi(,1203) jazz
+../tar_texi/tar.texi(,1204) @end smallexample
+../tar_texi/tar.texi(,1205)
+../tar_texi/tar.texi(,1206) This example is just like the example we showed
which did not use
+../tar_texi/tar.texi(,1207) @option{--verbose}, except that @command{tar}
generated the remaining lines
+../tar_texi/tar.texi(,1214)
+../tar_texi/tar.texi(,1215) In the rest of the examples in this chapter, we
will frequently use
+../tar_texi/tar.texi(,1216) @code{verbose} mode so we can show actions or
@command{tar} responses that
+../tar_texi/tar.texi(,1217) you would otherwise not see, and which are
important for you to
+../tar_texi/tar.texi(,1218) understand.
+../tar_texi/tar.texi(,1219)
+../tar_texi/tar.texi(,1220) @node short create
+../tar_texi/tar.texi(,1221) @subsection Short Forms with @samp{create}
+../tar_texi/tar.texi(,1222)
+../tar_texi/tar.texi(,1223) As we said before, the @option{--create}
(@option{-c}) operation is one of the most
+../tar_texi/tar.texi(,1224) basic uses of @command{tar}, and you will use it
countless times.
+../tar_texi/tar.texi(,1225) Eventually, you will probably want to use
abbreviated (or ``short'')
+../tar_texi/tar.texi(,1226) forms of options. A full discussion of the three
different forms that
+../tar_texi/tar.texi(,1227) options can take appears in @ref{Styles}; for now,
here is what the
+../tar_texi/tar.texi(,1228) previous example (including the @option{--verbose}
(@option{-v}) option) looks like
+../tar_texi/tar.texi(,1229) using short option forms:
+../tar_texi/tar.texi(,1230)
+../tar_texi/tar.texi(,1231) @smallexample
+../tar_texi/tar.texi(,1232) $ @kbd{tar -cvf collection.tar blues folk jazz}
+../tar_texi/tar.texi(,1233) blues
+../tar_texi/tar.texi(,1234) folk
+../tar_texi/tar.texi(,1235) jazz
+../tar_texi/tar.texi(,1236) @end smallexample
+../tar_texi/tar.texi(,1237)
+../tar_texi/tar.texi(,1238) @noindent
+../tar_texi/tar.texi(,1239) As you can see, the system responds the same no
matter whether you use
+../tar_texi/tar.texi(,1240) long or short option forms.
+../tar_texi/tar.texi(,1241)
+../tar_texi/tar.texi(FIXME,1242) @allow-recursion
+../tar_texi/tar.texi(FIXME,1242) @quote-arg
+../tar_texi/tar.texi(FIXME,1242) One difference between using
+../tar_texi/tar.texi(,1243) short and long option forms is that, although the
exact placement of
+../tar_texi/tar.texi(,1244) arguments following options is no more specific
when using short forms,
+../tar_texi/tar.texi(,1245) it is easier to become confused and make a mistake
when using short
+../tar_texi/tar.texi(,1246) forms. For example, suppose you attempted the
above example in the
+../tar_texi/tar.texi(,1247) following way:
+../tar_texi/tar.texi(,1248)
+../tar_texi/tar.texi(,1249) @smallexample
+../tar_texi/tar.texi(,1250) $ @kbd{tar -cfv collection.tar blues folk jazz}
+../tar_texi/tar.texi(,1251) @end smallexample
+../tar_texi/tar.texi(,1252)
+../tar_texi/tar.texi(,1253) @noindent
+../tar_texi/tar.texi(,1254) In this case, @command{tar} will make an archive
file called @file{v},
+../tar_texi/tar.texi(,1255) containing the files @file{blues}, @file{folk},
and @file{jazz}, because
+../tar_texi/tar.texi(,1256) the @samp{v} is the closest ``file name'' to the
@option{-f} option, and
+../tar_texi/tar.texi(,1257) is thus taken to be the chosen archive file name.
@command{tar} will try
+../tar_texi/tar.texi(,1258) to add a file called @file{collection.tar} to the
@file{v} archive file;
+../tar_texi/tar.texi(,1259) if the file @file{collection.tar} did not already
exist, @command{tar} will
+../tar_texi/tar.texi(,1260) report an error indicating that this file does not
exist. If the file
+../tar_texi/tar.texi(,1261) @file{collection.tar} does already exist (e.g.,
from a previous command
+../tar_texi/tar.texi(,1262) you may have run), then @command{tar} will add
this file to the archive.
+../tar_texi/tar.texi(,1263) Because the @option{-v} option did not get
registered, @command{tar} will not
+../tar_texi/tar.texi(,1264) run under @samp{verbose} mode, and will not report
its progress.
+../tar_texi/tar.texi(,1265)
+../tar_texi/tar.texi(,1266) The end result is that you may be quite confused
about what happened,
+../tar_texi/tar.texi(,1267) and possibly overwrite a file. To illustrate this
further, we will show
+../tar_texi/tar.texi(,1268) you how an example we showed previously would look
using short forms.
+../tar_texi/tar.texi(,1269)
+../tar_texi/tar.texi(,1270) This example,
+../tar_texi/tar.texi(,1271)
+../tar_texi/tar.texi(,1272) @smallexample
+../tar_texi/tar.texi(,1273) $ @kbd{tar blues --create folk
--file=collection.tar jazz}
+../tar_texi/tar.texi(,1274) @end smallexample
+../tar_texi/tar.texi(,1275)
+../tar_texi/tar.texi(,1276) @noindent
+../tar_texi/tar.texi(,1277) is confusing as it is. When shown using short
forms, however, it
+../tar_texi/tar.texi(,1278) becomes much more so:
+../tar_texi/tar.texi(,1279)
+../tar_texi/tar.texi(,1280) @smallexample
+../tar_texi/tar.texi(,1281) $ @kbd{tar blues -c folk -f collection.tar jazz}
+../tar_texi/tar.texi(,1282) @end smallexample
+../tar_texi/tar.texi(,1283)
+../tar_texi/tar.texi(,1284) @noindent
+../tar_texi/tar.texi(,1285) It would be very easy to put the wrong string of
characters
+../tar_texi/tar.texi(,1286) immediately following the @option{-f}, but doing
that could sacrifice
+../tar_texi/tar.texi(,1287) valuable data.
+../tar_texi/tar.texi(,1288)
+../tar_texi/tar.texi(,1289) For this reason, we recommend that you pay very
careful attention to
+../tar_texi/tar.texi(,1290) the order of options and placement of file and
archive names,
+../tar_texi/tar.texi(,1291) especially when using short option forms. Not
having the option name
+../tar_texi/tar.texi(,1292) written out mnemonically can affect how well you
remember which option
+../tar_texi/tar.texi(,1293) does what, and therefore where different names
have to be placed.
+../tar_texi/tar.texi(,1294)
+../tar_texi/tar.texi(,1295) @node create dir
+../tar_texi/tar.texi(,1296) @subsection Archiving Directories
+../tar_texi/tar.texi(,1297)
+../tar_texi/tar.texi(,1298) @cindex Archiving Directories
+../tar_texi/tar.texi(,1299) @cindex Directories, Archiving
+../tar_texi/tar.texi(,1300) You can archive a directory by specifying its
directory name as a
+../tar_texi/tar.texi(,1301) file name argument to @command{tar}. The files in
the directory will be
+../tar_texi/tar.texi(,1302) archived relative to the working directory, and
the directory will be
+../tar_texi/tar.texi(,1303) re-created along with its contents when the
archive is extracted.
+../tar_texi/tar.texi(,1304)
+../tar_texi/tar.texi(,1305) To archive a directory, first move to its superior
directory. If you
+../tar_texi/tar.texi(,1306) have followed the previous instructions in this
tutorial, you should
+../tar_texi/tar.texi(,1307) type:
+../tar_texi/tar.texi(,1308)
+../tar_texi/tar.texi(,1309) @smallexample
+../tar_texi/tar.texi(,1310) $ @kbd{cd ..}
+../tar_texi/tar.texi(,1311) $
+../tar_texi/tar.texi(,1312) @end smallexample
+../tar_texi/tar.texi(,1313)
+../tar_texi/tar.texi(,1314) @noindent
+../tar_texi/tar.texi(,1315) This will put you into the directory which
contains @file{practice},
+../tar_texi/tar.texi(,1316) i.e., your home directory. Once in the superior
directory, you can
+../tar_texi/tar.texi(,1317) specify the subdirectory, @file{practice}, as a
file name argument. To
+../tar_texi/tar.texi(,1318) store @file{practice} in the new archive file
@file{music.tar}, type:
+../tar_texi/tar.texi(,1319)
+../tar_texi/tar.texi(,1320) @smallexample
+../tar_texi/tar.texi(,1321) $ @kbd{tar --create --verbose --file=music.tar
practice}
+../tar_texi/tar.texi(,1322) @end smallexample
+../tar_texi/tar.texi(,1323)
+../tar_texi/tar.texi(,1324) @noindent
+../tar_texi/tar.texi(,1325) @command{tar} should output:
+../tar_texi/tar.texi(,1326)
+../tar_texi/tar.texi(,1327) @smallexample
+../tar_texi/tar.texi(,1328) practice/
+../tar_texi/tar.texi(,1329) practice/blues
+../tar_texi/tar.texi(,1330) practice/folk
+../tar_texi/tar.texi(,1331) practice/jazz
+../tar_texi/tar.texi(,1332) practice/collection.tar
+../tar_texi/tar.texi(,1333) @end smallexample
+../tar_texi/tar.texi(,1334)
+../tar_texi/tar.texi(,1335) Note that the archive thus created is not in the
subdirectory
+../tar_texi/tar.texi(,1336) @file{practice}, but rather in the current working
directory---the
+../tar_texi/tar.texi(,1337) directory from which @command{tar} was invoked.
Before trying to archive a
+../tar_texi/tar.texi(,1338) directory from its superior directory, you should
make sure you have
+../tar_texi/tar.texi(,1339) write access to the superior directory itself, not
only the directory
+../tar_texi/tar.texi(,1340) you are trying archive with @command{tar}. For
example, you will probably
+../tar_texi/tar.texi(,1341) not be able to store your home directory in an
archive by invoking
+../tar_texi/tar.texi(,1342) @command{tar} from the root directory;
@xref{absolute}. (Note
+../tar_texi/tar.texi(,1343) also that @file{collection.tar}, the original
archive file, has itself
+../tar_texi/tar.texi(,1344) been archived. @command{tar} will accept any file
as a file to be
+../tar_texi/tar.texi(,1345) archived, regardless of its content. When
@file{music.tar} is
+../tar_texi/tar.texi(,1346) extracted, the archive file @file{collection.tar}
will be re-written
+../tar_texi/tar.texi(,1347) into the file system).
+../tar_texi/tar.texi(,1348)
+../tar_texi/tar.texi(,1349) If you give @command{tar} a command such as
+../tar_texi/tar.texi(,1350)
+../tar_texi/tar.texi(,1351) @smallexample
+../tar_texi/tar.texi(,1352) $ @kbd{tar --create --file=foo.tar .}
+../tar_texi/tar.texi(,1353) @end smallexample
+../tar_texi/tar.texi(,1354)
+../tar_texi/tar.texi(,1355) @noindent
+../tar_texi/tar.texi(,1356) @command{tar} will report @samp{tar: ./foo.tar is
the archive; not
+../tar_texi/tar.texi(,1357) dumped}. This happens because @command{tar}
creates the archive
+../tar_texi/tar.texi(,1358) @file{foo.tar} in the current directory before
putting any files into
+../tar_texi/tar.texi(,1359) it. Then, when @command{tar} attempts to add all
the files in the
+../tar_texi/tar.texi(,1360) directory @file{.} to the archive, it notices that
the file
+../tar_texi/tar.texi(,1361) @file{./foo.tar} is the same as the archive
@file{foo.tar}, and skips
+../tar_texi/tar.texi(GNUTAR,1362) it. (It makes no sense to put an archive
into itself.) ../tar_texi/tar.texi(GNUTAR,1362) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1362)
+../tar_texi/tar.texi(,1363) will continue in this case, and create the archive
+../tar_texi/tar.texi(,1364) normally, except for the exclusion of that one
file. (@emph{Please
+../tar_texi/tar.texi(,1365) note:} Other implementations of @command{tar} may
not be so clever;
+../tar_texi/tar.texi(,1366) they will enter an infinite loop when this
happens, so you should not
+../tar_texi/tar.texi(,1367) depend on this behavior unless you are certain you
are running
+../tar_texi/tar.texi(GNUTAR,1368) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1368) . In general, it is wise to
always place the archive outside
+../tar_texi/tar.texi(,1369) of the directory being dumped.
+../tar_texi/tar.texi(,1370)
+../tar_texi/tar.texi(,1371) @node list
+../tar_texi/tar.texi(,1372) @section How to List Archives
+../tar_texi/tar.texi(,1373)
+../tar_texi/tar.texi(,1374) @opindex list
+../tar_texi/tar.texi(,1375) Frequently, you will find yourself wanting to
determine exactly what a
+../tar_texi/tar.texi(,1376) particular archive contains. You can use the
@option{--list}
+../tar_texi/tar.texi(,1377) (@option{-t}) operation to get the member names as
they currently
+../tar_texi/tar.texi(,1378) appear in the archive, as well as various
attributes of the files at
+../tar_texi/tar.texi(,1379) the time they were archived. For example, you can
examine the archive
+../tar_texi/tar.texi(,1380) @file{collection.tar} that you created in the last
section with the
+../tar_texi/tar.texi(,1381) command,
+../tar_texi/tar.texi(,1382)
+../tar_texi/tar.texi(,1383) @smallexample
+../tar_texi/tar.texi(,1384) $ @kbd{tar --list --file=collection.tar}
+../tar_texi/tar.texi(,1385) @end smallexample
+../tar_texi/tar.texi(,1386)
+../tar_texi/tar.texi(,1387) @noindent
+../tar_texi/tar.texi(,1388) The output of @command{tar} would then be:
+../tar_texi/tar.texi(,1389)
+../tar_texi/tar.texi(,1390) @smallexample
+../tar_texi/tar.texi(,1391) blues
+../tar_texi/tar.texi(,1392) folk
+../tar_texi/tar.texi(,1393) jazz
+../tar_texi/tar.texi(,1394) @end smallexample
+../tar_texi/tar.texi(,1395)
+../tar_texi/tar.texi(,1396) @noindent
+../tar_texi/tar.texi(,1397) The archive @file{bfiles.tar} would list as
follows:
+../tar_texi/tar.texi(,1398)
+../tar_texi/tar.texi(,1399) @smallexample
+../tar_texi/tar.texi(,1400) ./birds
+../tar_texi/tar.texi(,1401) baboon
+../tar_texi/tar.texi(,1402) ./box
+../tar_texi/tar.texi(,1403) @end smallexample
+../tar_texi/tar.texi(,1404)
+../tar_texi/tar.texi(,1405) @noindent
+../tar_texi/tar.texi(,1406) Be sure to use a @address@hidden (@option{-f
+../tar_texi/tar.texi(,1407) @var{archive-name}}) option just as with
@option{--create}
+../tar_texi/tar.texi(,1408) (@option{-c}) to specify the name of the archive.
+../tar_texi/tar.texi(,1409)
+../tar_texi/tar.texi(xopindex,1410) @opindex address@hidden, using with
@option{--verbose}}../tar_texi/tar.texi(xopindex,1410)
+../tar_texi/tar.texi(xopindex,1411) @opindex address@hidden, using with
@option{--list}}../tar_texi/tar.texi(xopindex,1411)
+../tar_texi/tar.texi(,1412) If you use the @option{--verbose} (@option{-v})
option with
+../tar_texi/tar.texi(,1413) @option{--list}, then @command{tar} will print out
a listing
+../tar_texi/tar.texi(,1414) reminiscent of @address@hidden -l}}, showing
owner, file size, and so
+../tar_texi/tar.texi(,1415) forth. This output is described in detail in
@ref{verbose member listing}.
+../tar_texi/tar.texi(,1416)
+../tar_texi/tar.texi(,1417) If you had used @option{--verbose} (@option{-v})
mode, the example
+../tar_texi/tar.texi(,1418) above would look like:
+../tar_texi/tar.texi(,1419)
+../tar_texi/tar.texi(,1420) @smallexample
+../tar_texi/tar.texi(,1421) $ @kbd{tar --list --verbose --file=collection.tar
folk}
+../tar_texi/tar.texi(,1422) -rw-r--r-- myself user 62 1990-05-23 10:55 folk
+../tar_texi/tar.texi(,1423) @end smallexample
+../tar_texi/tar.texi(,1424)
+../tar_texi/tar.texi(,1425) @cindex listing member and file names
+../tar_texi/tar.texi(,1426) @anchor{listing member and file names}
+../tar_texi/tar.texi(,1427) It is important to notice that the output of
@kbd{tar --list
+../tar_texi/tar.texi(,1428) --verbose} does not necessarily match that
produced by @kbd{tar
+../tar_texi/tar.texi(,1429) --create --verbose} while creating the archive.
It is because
+../tar_texi/tar.texi(GNUTAR,1430) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1430) , unless told explicitly not to
do so, removes some directory
+../tar_texi/tar.texi(,1431) prefixes from file names before storing them in
the archive
+../tar_texi/tar.texi(,1432) (@xref{absolute}, for more information). In other
+../tar_texi/tar.texi(GNUTAR,1433) words, in verbose mode
../tar_texi/tar.texi(GNUTAR,1433) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1433) shows @dfn{file names} when
creating
+../tar_texi/tar.texi(,1434) an archive and @dfn{member names} when listing it.
Consider this
+../tar_texi/tar.texi(,1435) example:
+../tar_texi/tar.texi(,1436)
+../tar_texi/tar.texi(,1437) @smallexample
+../tar_texi/tar.texi(,1438) @group
+../tar_texi/tar.texi(,1439) $ @kbd{tar cfv archive /etc/mail}
+../tar_texi/tar.texi(,1440) tar: Removing leading `/' from member names
+../tar_texi/tar.texi(,1441) /etc/mail/
+../tar_texi/tar.texi(,1442) /etc/mail/sendmail.cf
+../tar_texi/tar.texi(,1443) /etc/mail/aliases
+../tar_texi/tar.texi(,1444) $ @kbd{tar tf archive}
+../tar_texi/tar.texi(,1445) etc/mail/
+../tar_texi/tar.texi(,1446) etc/mail/sendmail.cf
+../tar_texi/tar.texi(,1447) etc/mail/aliases
+../tar_texi/tar.texi(,1448) @end group
+../tar_texi/tar.texi(,1449) @end smallexample
+../tar_texi/tar.texi(,1450)
+../tar_texi/tar.texi(,1451) @opindex show-stored-names
+../tar_texi/tar.texi(,1452) This default behavior can sometimes be
inconvenient. You can force
+../tar_texi/tar.texi(GNUTAR,1453) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1453) show member names when creating
archive by supplying
+../tar_texi/tar.texi(,1454) @option{--show-stored-names} option.
+../tar_texi/tar.texi(,1455)
+../tar_texi/tar.texi(,1456) @table @option
+../tar_texi/tar.texi(,1457) @item --show-stored-names
+../tar_texi/tar.texi(,1458) Print member (as opposed to @emph{file}) names
when creating the archive.
+../tar_texi/tar.texi(,1459) @end table
+../tar_texi/tar.texi(,1460)
+../tar_texi/tar.texi(,1461) @cindex File name arguments, using @option{--list}
with
+../tar_texi/tar.texi(xopindex,1462) @opindex address@hidden, using with file
name arguments}../tar_texi/tar.texi(xopindex,1462)
+../tar_texi/tar.texi(,1463) You can specify one or more individual member
names as arguments when
+../tar_texi/tar.texi(,1464) using @samp{list}. In this case, @command{tar}
will only list the
+../tar_texi/tar.texi(,1465) names of members you identify. For example,
@address@hidden --list
+../tar_texi/tar.texi(,1466) --file=afiles.tar apple}} would only print
@file{apple}.
+../tar_texi/tar.texi(,1467)
+../tar_texi/tar.texi(,1468) Because @command{tar} preserves paths, file names
must be specified as
+../tar_texi/tar.texi(,1469) they appear in the archive (i.e., relative to the
directory from which
+../tar_texi/tar.texi(,1470) the archive was created). Therefore, it is
essential when specifying
+../tar_texi/tar.texi(,1471) member names to @command{tar} that you give the
exact member names.
+../tar_texi/tar.texi(,1472) For example, @address@hidden --list
--file=bfiles.tar birds}} would produce an
+../tar_texi/tar.texi(,1473) error message something like @samp{tar: birds: Not
found in archive},
+../tar_texi/tar.texi(,1474) because there is no member named @file{birds},
only one named
+../tar_texi/tar.texi(,1475) @file{./birds}. While the names @file{birds} and
@file{./birds} name
+../tar_texi/tar.texi(,1476) the same file, @emph{member} names by default are
compared verbatim.
+../tar_texi/tar.texi(,1477)
+../tar_texi/tar.texi(,1478) However, @address@hidden --list --file=bfiles.tar
baboon}} would respond
+../tar_texi/tar.texi(,1479) with @file{baboon}, because this exact member name
is in the archive file
+../tar_texi/tar.texi(,1480) @file{bfiles.tar}. If you are not sure of the
exact file name,
+../tar_texi/tar.texi(,1481) use @dfn{globbing patterns}, for example:
+../tar_texi/tar.texi(,1482)
+../tar_texi/tar.texi(,1483) @smallexample
+../tar_texi/tar.texi(,1484) $ @kbd{tar --list --file=bfiles.tar --wildcards
'*b*'}
+../tar_texi/tar.texi(,1485) @end smallexample
+../tar_texi/tar.texi(,1486)
+../tar_texi/tar.texi(,1487) @noindent
+../tar_texi/tar.texi(,1488) will list all members whose name contains
@samp{b}. @xref{wildcards},
+../tar_texi/tar.texi(,1489) for a detailed discussion of globbing patterns and
related
+../tar_texi/tar.texi(,1490) @command{tar} command line options.
+../tar_texi/tar.texi(,1491)
+../tar_texi/tar.texi(,1492) @menu
+../tar_texi/tar.texi(,1493) * list dir::
+../tar_texi/tar.texi(,1494) @end menu
+../tar_texi/tar.texi(,1495)
+../tar_texi/tar.texi(,1496) @node list dir
+../tar_texi/tar.texi(,1497) @unnumberedsubsec Listing the Contents of a Stored
Directory
+../tar_texi/tar.texi(,1498)
+../tar_texi/tar.texi(,1499) To get information about the contents of an
archived directory,
+../tar_texi/tar.texi(,1500) use the directory name as a file name argument in
conjunction with
+../tar_texi/tar.texi(,1501) @option{--list} (@option{-t}). To find out file
attributes, include the
+../tar_texi/tar.texi(,1502) @option{--verbose} (@option{-v}) option.
+../tar_texi/tar.texi(,1503)
+../tar_texi/tar.texi(,1504) For example, to find out about files in the
directory @file{practice}, in
+../tar_texi/tar.texi(,1505) the archive file @file{music.tar}, type:
+../tar_texi/tar.texi(,1506)
+../tar_texi/tar.texi(,1507) @smallexample
+../tar_texi/tar.texi(,1508) $ @kbd{tar --list --verbose --file=music.tar
practice}
+../tar_texi/tar.texi(,1509) @end smallexample
+../tar_texi/tar.texi(,1510)
+../tar_texi/tar.texi(,1511) @command{tar} responds:
+../tar_texi/tar.texi(,1512)
+../tar_texi/tar.texi(,1513) @smallexample
+../tar_texi/tar.texi(,1514) drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
+../tar_texi/tar.texi(,1515) -rw-r--r-- myself user 42 1990-05-21 13:29
practice/blues
+../tar_texi/tar.texi(,1516) -rw-r--r-- myself user 62 1990-05-23 10:55
practice/folk
+../tar_texi/tar.texi(,1517) -rw-r--r-- myself user 40 1990-05-21 13:30
practice/jazz
+../tar_texi/tar.texi(,1518) -rw-r--r-- myself user 10240 1990-05-31 21:49
practice/collection.tar
+../tar_texi/tar.texi(,1519) @end smallexample
+../tar_texi/tar.texi(,1520)
+../tar_texi/tar.texi(,1521) When you use a directory name as a file name
argument, @command{tar} acts on
+../tar_texi/tar.texi(,1522) all the files (including sub-directories) in that
directory.
+../tar_texi/tar.texi(,1523)
+../tar_texi/tar.texi(,1524) @node extract
+../tar_texi/tar.texi(,1525) @section How to Extract Members from an Archive
+../tar_texi/tar.texi(UNREVISED,1526) @quotation
+../tar_texi/tar.texi(UNREVISED,1526) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,1526) @end quotation
+../tar_texi/tar.texi(UNREVISED,1526)
+../tar_texi/tar.texi(,1527) @cindex Extraction
+../tar_texi/tar.texi(,1528) @cindex Retrieving files from an archive
+../tar_texi/tar.texi(,1529) @cindex Resurrecting files from an archive
+../tar_texi/tar.texi(,1530)
+../tar_texi/tar.texi(,1531) @opindex extract
+../tar_texi/tar.texi(,1532) Creating an archive is only half the job---there
is no point in storing
+../tar_texi/tar.texi(,1533) files in an archive if you can't retrieve them.
The act of retrieving
+../tar_texi/tar.texi(,1534) members from an archive so they can be used and
manipulated as
+../tar_texi/tar.texi(,1535) unarchived files again is called @dfn{extraction}.
To extract files
+../tar_texi/tar.texi(,1536) from an archive, use the @option{--extract}
(@option{--get} or
+../tar_texi/tar.texi(,1537) @option{-x}) operation. As with
@option{--create}, specify the name
+../tar_texi/tar.texi(,1538) of the archive with @option{--file} (@option{-f})
option. Extracting
+../tar_texi/tar.texi(,1539) an archive does not modify the archive in any way;
you can extract it
+../tar_texi/tar.texi(,1540) multiple times if you want or need to.
+../tar_texi/tar.texi(,1541)
+../tar_texi/tar.texi(,1542) Using @option{--extract}, you can extract an
entire archive, or specific
+../tar_texi/tar.texi(,1543) files. The files can be directories containing
other files, or not. As
+../tar_texi/tar.texi(,1544) with @option{--create} (@option{-c}) and
@option{--list} (@option{-t}), you may use the short or the
+../tar_texi/tar.texi(,1545) long form of the operation without affecting the
performance.
+../tar_texi/tar.texi(,1546)
+../tar_texi/tar.texi(,1547) @menu
+../tar_texi/tar.texi(,1548) * extracting archives::
+../tar_texi/tar.texi(,1549) * extracting files::
+../tar_texi/tar.texi(,1550) * extract dir::
+../tar_texi/tar.texi(,1551) * extracting untrusted archives::
+../tar_texi/tar.texi(,1552) * failing commands::
+../tar_texi/tar.texi(,1553) @end menu
+../tar_texi/tar.texi(,1554)
+../tar_texi/tar.texi(,1555) @node extracting archives
+../tar_texi/tar.texi(,1556) @subsection Extracting an Entire Archive
+../tar_texi/tar.texi(,1557)
+../tar_texi/tar.texi(,1558) To extract an entire archive, specify the archive
file name only, with
+../tar_texi/tar.texi(,1559) no individual file names as arguments. For
example,
+../tar_texi/tar.texi(,1560)
+../tar_texi/tar.texi(,1561) @smallexample
+../tar_texi/tar.texi(,1562) $ @kbd{tar -xvf collection.tar}
+../tar_texi/tar.texi(,1563) @end smallexample
+../tar_texi/tar.texi(,1564)
+../tar_texi/tar.texi(,1565) @noindent
+../tar_texi/tar.texi(,1566) produces this:
+../tar_texi/tar.texi(,1567)
+../tar_texi/tar.texi(,1568) @smallexample
+../tar_texi/tar.texi(,1569) -rw-r--r-- me user 28 1996-10-18 16:31 jazz
+../tar_texi/tar.texi(,1570) -rw-r--r-- me user 21 1996-09-23 16:44 blues
+../tar_texi/tar.texi(,1571) -rw-r--r-- me user 20 1996-09-23 16:44 folk
+../tar_texi/tar.texi(,1572) @end smallexample
+../tar_texi/tar.texi(,1573)
+../tar_texi/tar.texi(,1574) @node extracting files
+../tar_texi/tar.texi(,1575) @subsection Extracting Specific Files
+../tar_texi/tar.texi(,1576)
+../tar_texi/tar.texi(,1577) To extract specific archive members, give their
exact member names as
+../tar_texi/tar.texi(,1578) arguments, as printed by @option{--list}
(@option{-t}). If you had
+../tar_texi/tar.texi(,1579) mistakenly deleted one of the files you had placed
in the archive
+../tar_texi/tar.texi(,1580) @file{collection.tar} earlier (say, @file{blues}),
you can extract it
+../tar_texi/tar.texi(,1581) from the archive without changing the archive's
structure. Its
+../tar_texi/tar.texi(,1582) contents will be identical to the original file
@file{blues} that you
+../tar_texi/tar.texi(,1583) deleted.
+../tar_texi/tar.texi(,1584)
+../tar_texi/tar.texi(,1585) First, make sure you are in the @file{practice}
directory, and list the
+../tar_texi/tar.texi(,1586) files in the directory. Now, delete the file,
@samp{blues}, and list
+../tar_texi/tar.texi(,1587) the files in the directory again.
+../tar_texi/tar.texi(,1588)
+../tar_texi/tar.texi(,1589) You can now extract the member @file{blues} from
the archive file
+../tar_texi/tar.texi(,1590) @file{collection.tar} like this:
+../tar_texi/tar.texi(,1591)
+../tar_texi/tar.texi(,1592) @smallexample
+../tar_texi/tar.texi(,1593) $ @kbd{tar --extract --file=collection.tar blues}
+../tar_texi/tar.texi(,1594) @end smallexample
+../tar_texi/tar.texi(,1595)
+../tar_texi/tar.texi(,1596) @noindent
+../tar_texi/tar.texi(,1597) If you list the files in the directory again, you
will see that the file
+../tar_texi/tar.texi(,1598) @file{blues} has been restored, with its original
permissions, data
+../tar_texi/tar.texi(,1599) modification times, and address@hidden is only
accidentally
+../tar_texi/tar.texi(,1600) true, but not in general. Whereas modification
times are always
+../tar_texi/tar.texi(,1601) restored, in most cases, one has to be root for
restoring the owner,
+../tar_texi/tar.texi(,1602) and use a special option for restoring
permissions. Here, it just
+../tar_texi/tar.texi(,1603) happens that the restoring user is also the owner
of the archived
+../tar_texi/tar.texi(,1604) members, and that the current @code{umask} is
compatible with original
+../tar_texi/tar.texi(,1605) permissions.} (These parameters will be identical
to those which
+../tar_texi/tar.texi(,1606) the file had when you originally placed it in the
archive; any changes
+../tar_texi/tar.texi(,1607) you may have made before deleting the file from
the file system,
+../tar_texi/tar.texi(,1608) however, will @emph{not} have been made to the
archive member.) The
+../tar_texi/tar.texi(,1609) archive file, @samp{collection.tar}, is the same
as it was before you
+../tar_texi/tar.texi(,1610) extracted @samp{blues}. You can confirm this by
running @command{tar} with
+../tar_texi/tar.texi(,1611) @option{--list} (@option{-t}).
+../tar_texi/tar.texi(,1612)
+../tar_texi/tar.texi(,1613) Remember that as with other operations, specifying
the exact member
+../tar_texi/tar.texi(,1614) name is important. @address@hidden --extract
--file=bfiles.tar birds}}
+../tar_texi/tar.texi(,1615) will fail, because there is no member named
@file{birds}. To extract
+../tar_texi/tar.texi(,1616) the member named @file{./birds}, you must specify
@address@hidden
+../tar_texi/tar.texi(,1617) --extract --file=bfiles.tar ./birds}}. If you
don't remember the
+../tar_texi/tar.texi(,1618) exact member names, use @option{--list}
(@option{-t}) option
+../tar_texi/tar.texi(,1619) (@pxref{list}). You can also extract those
members that match a
+../tar_texi/tar.texi(,1620) specific @dfn{globbing pattern}. For example, to
extract from
+../tar_texi/tar.texi(,1621) @file{bfiles.tar} all files that begin with
@samp{b}, no matter their
+../tar_texi/tar.texi(,1622) directory prefix, you could type:
+../tar_texi/tar.texi(,1623)
+../tar_texi/tar.texi(,1624) @smallexample
+../tar_texi/tar.texi(,1625) $ @kbd{tar -x -f bfiles.tar --wildcards
--no-anchored 'b*'}
+../tar_texi/tar.texi(,1626) @end smallexample
+../tar_texi/tar.texi(,1627)
+../tar_texi/tar.texi(,1628) @noindent
+../tar_texi/tar.texi(,1629) Here, @option{--wildcards} instructs @command{tar}
to treat
+../tar_texi/tar.texi(,1630) command line arguments as globbing patterns and
@option{--no-anchored}
+../tar_texi/tar.texi(,1631) informs it that the patterns apply to member names
after any @samp{/}
+../tar_texi/tar.texi(,1632) delimiter. The use of globbing patterns is
discussed in detail in
+../tar_texi/tar.texi(,1633) @xref{wildcards}.
+../tar_texi/tar.texi(,1634)
+../tar_texi/tar.texi(,1635) You can extract a file to standard output by
combining the above options
+../tar_texi/tar.texi(,1636) with the @option{--to-stdout} (@option{-O}) option
(@pxref{Writing to Standard
+../tar_texi/tar.texi(,1637) Output}).
+../tar_texi/tar.texi(,1638)
+../tar_texi/tar.texi(,1639) If you give the @option{--verbose} option, then
@option{--extract}
+../tar_texi/tar.texi(,1640) will print the names of the archive members as it
extracts them.
+../tar_texi/tar.texi(,1641)
+../tar_texi/tar.texi(,1642) @node extract dir
+../tar_texi/tar.texi(,1643) @subsection Extracting Files that are Directories
+../tar_texi/tar.texi(,1644)
+../tar_texi/tar.texi(,1645) Extracting directories which are members of an
archive is similar to
+../tar_texi/tar.texi(,1646) extracting other files. The main difference to be
aware of is that if
+../tar_texi/tar.texi(,1647) the extracted directory has the same name as any
directory already in
+../tar_texi/tar.texi(,1648) the working directory, then files in the extracted
directory will be
+../tar_texi/tar.texi(,1649) placed into the directory of the same name.
Likewise, if there are
+../tar_texi/tar.texi(,1650) files in the pre-existing directory with the same
names as the members
+../tar_texi/tar.texi(,1651) which you extract, the files from the extracted
archive will replace
+../tar_texi/tar.texi(,1652) the files already in the working directory (and
possible
+../tar_texi/tar.texi(,1653) subdirectories). This will happen regardless of
whether or not the
+../tar_texi/tar.texi(,1654) files in the working directory were more recent
than those extracted
+../tar_texi/tar.texi(,1655) (there exist, however, special options that alter
this behavior
+../tar_texi/tar.texi(,1656) @pxref{Writing}).
+../tar_texi/tar.texi(,1657)
+../tar_texi/tar.texi(,1658) However, if a file was stored with a directory
name as part of its file
+../tar_texi/tar.texi(,1659) name, and that directory does not exist under the
working directory when
+../tar_texi/tar.texi(,1660) the file is extracted, @command{tar} will create
the directory.
+../tar_texi/tar.texi(,1661)
+../tar_texi/tar.texi(,1662) We can demonstrate how to use @option{--extract}
to extract a directory
+../tar_texi/tar.texi(,1663) file with an example. Change to the
@file{practice} directory if you
+../tar_texi/tar.texi(,1664) weren't there, and remove the files @file{folk}
and @file{jazz}. Then,
+../tar_texi/tar.texi(,1665) go back to the parent directory and extract the
archive
+../tar_texi/tar.texi(,1666) @file{music.tar}. You may either extract the
entire archive, or you may
+../tar_texi/tar.texi(,1667) extract only the files you just deleted. To
extract the entire archive,
+../tar_texi/tar.texi(,1668) don't give any file names as arguments after the
archive name
+../tar_texi/tar.texi(,1669) @file{music.tar}. To extract only the files you
deleted, use the
+../tar_texi/tar.texi(,1670) following command:
+../tar_texi/tar.texi(,1671)
+../tar_texi/tar.texi(,1672) @smallexample
+../tar_texi/tar.texi(,1673) $ @kbd{tar -xvf music.tar practice/folk
practice/jazz}
+../tar_texi/tar.texi(,1674) practice/folk
+../tar_texi/tar.texi(,1675) practice/jazz
+../tar_texi/tar.texi(,1676) @end smallexample
+../tar_texi/tar.texi(,1677)
+../tar_texi/tar.texi(,1678) @noindent
+../tar_texi/tar.texi(,1679) If you were to specify two @option{--verbose}
(@option{-v}) options, @command{tar}
+../tar_texi/tar.texi(,1680) would have displayed more detail about the
extracted files, as shown
+../tar_texi/tar.texi(,1681) in the example below:
+../tar_texi/tar.texi(,1682)
+../tar_texi/tar.texi(,1683) @smallexample
+../tar_texi/tar.texi(,1684) $ @kbd{tar -xvvf music.tar practice/folk
practice/jazz}
+../tar_texi/tar.texi(,1685) -rw-r--r-- me user 28 1996-10-18 16:31
practice/jazz
+../tar_texi/tar.texi(,1686) -rw-r--r-- me user 20 1996-09-23 16:44
practice/folk
+../tar_texi/tar.texi(,1687) @end smallexample
+../tar_texi/tar.texi(,1688)
+../tar_texi/tar.texi(,1689) @noindent
+../tar_texi/tar.texi(,1690) Because you created the directory with
@file{practice} as part of the
+../tar_texi/tar.texi(,1691) file names of each of the files by archiving the
@file{practice}
+../tar_texi/tar.texi(,1692) directory as @file{practice}, you must give
@file{practice} as part
+../tar_texi/tar.texi(,1693) of the file names when you extract those files
from the archive.
+../tar_texi/tar.texi(,1694)
+../tar_texi/tar.texi(,1695) @node extracting untrusted archives
+../tar_texi/tar.texi(,1696) @subsection Extracting Archives from Untrusted
Sources
+../tar_texi/tar.texi(,1697)
+../tar_texi/tar.texi(,1698) Extracting files from archives can overwrite files
that already exist.
+../tar_texi/tar.texi(,1699) If you receive an archive from an untrusted
source, you should make a
+../tar_texi/tar.texi(,1700) new directory and extract into that directory, so
that you don't have
+../tar_texi/tar.texi(,1701) to worry about the extraction overwriting one of
your existing files.
+../tar_texi/tar.texi(,1702) For example, if @file{untrusted.tar} came from
somewhere else on the
+../tar_texi/tar.texi(,1703) Internet, and you don't necessarily trust its
contents, you can
+../tar_texi/tar.texi(,1704) extract it as follows:
+../tar_texi/tar.texi(,1705)
+../tar_texi/tar.texi(,1706) @smallexample
+../tar_texi/tar.texi(,1707) $ @kbd{mkdir newdir}
+../tar_texi/tar.texi(,1708) $ @kbd{cd newdir}
+../tar_texi/tar.texi(,1709) $ @kbd{tar -xvf ../untrusted.tar}
+../tar_texi/tar.texi(,1710) @end smallexample
+../tar_texi/tar.texi(,1711)
+../tar_texi/tar.texi(,1712) It is also a good practice to examine contents of
the archive
+../tar_texi/tar.texi(,1713) before extracting it, using @option{--list}
(@option{-t}) option, possibly combined
+../tar_texi/tar.texi(,1714) with @option{--verbose} (@option{-v}).
+../tar_texi/tar.texi(,1715)
+../tar_texi/tar.texi(,1716) @node failing commands
+../tar_texi/tar.texi(,1717) @subsection Commands That Will Fail
+../tar_texi/tar.texi(,1718)
+../tar_texi/tar.texi(,1719) Here are some sample commands you might try which
will not work, and why
+../tar_texi/tar.texi(,1720) they won't work.
+../tar_texi/tar.texi(,1721)
+../tar_texi/tar.texi(,1722) If you try to use this command,
+../tar_texi/tar.texi(,1723)
+../tar_texi/tar.texi(,1724) @smallexample
+../tar_texi/tar.texi(,1725) $ @kbd{tar -xvf music.tar folk jazz}
+../tar_texi/tar.texi(,1726) @end smallexample
+../tar_texi/tar.texi(,1727)
+../tar_texi/tar.texi(,1728) @noindent
+../tar_texi/tar.texi(,1729) you will get the following response:
+../tar_texi/tar.texi(,1730)
+../tar_texi/tar.texi(,1731) @smallexample
+../tar_texi/tar.texi(,1732) tar: folk: Not found in archive
+../tar_texi/tar.texi(,1733) tar: jazz: Not found in archive
+../tar_texi/tar.texi(,1734) $
+../tar_texi/tar.texi(,1735) @end smallexample
+../tar_texi/tar.texi(,1736)
+../tar_texi/tar.texi(,1737) @noindent
+../tar_texi/tar.texi(,1738) This is because these files were not originally
@emph{in} the parent
+../tar_texi/tar.texi(,1739) directory @file{..}, where the archive is located;
they were in the
+../tar_texi/tar.texi(,1740) @file{practice} directory, and their file names
reflect this:
+../tar_texi/tar.texi(,1741)
+../tar_texi/tar.texi(,1742) @smallexample
+../tar_texi/tar.texi(,1743) $ @kbd{tar -tvf music.tar}
+../tar_texi/tar.texi(,1744) practice/folk
+../tar_texi/tar.texi(,1745) practice/jazz
+../tar_texi/tar.texi(,1746) practice/rock
+../tar_texi/tar.texi(,1747) @end smallexample
+../tar_texi/tar.texi(,1748)
+../tar_texi/tar.texi(FIXME,1750) @allow-recursion
+../tar_texi/tar.texi(FIXME,1750) @quote-arg
+../tar_texi/tar.texi(FIXME,1750)
+../tar_texi/tar.texi(,1751)
+../tar_texi/tar.texi(,1752) @noindent
+../tar_texi/tar.texi(,1753) Likewise, if you try to use this command,
+../tar_texi/tar.texi(,1754)
+../tar_texi/tar.texi(,1755) @smallexample
+../tar_texi/tar.texi(,1756) $ @kbd{tar -tvf music.tar folk jazz}
+../tar_texi/tar.texi(,1757) @end smallexample
+../tar_texi/tar.texi(,1758)
+../tar_texi/tar.texi(,1759) @noindent
+../tar_texi/tar.texi(,1760) you would get a similar response. Members with
those names are not in the
+../tar_texi/tar.texi(,1761) archive. You must use the correct member names,
or wildcards, in order
+../tar_texi/tar.texi(,1762) to extract the files from the archive.
+../tar_texi/tar.texi(,1763)
+../tar_texi/tar.texi(,1764) If you have forgotten the correct names of the
files in the archive,
+../tar_texi/tar.texi(,1765) use @address@hidden --list --verbose}} to list
them correctly.
+../tar_texi/tar.texi(,1766)
+../tar_texi/tar.texi(FIXME,1767) @allow-recursion
+../tar_texi/tar.texi(FIXME,1767) @quote-arg
+../tar_texi/tar.texi(FIXME,1767)
+../tar_texi/tar.texi(,1768)
+../tar_texi/tar.texi(,1769) @node going further
+../tar_texi/tar.texi(,1770) @section Going Further Ahead in this Manual
+../tar_texi/tar.texi(,1771)
+../tar_texi/tar.texi(FIXME,1773) @allow-recursion
+../tar_texi/tar.texi(FIXME,1773) @quote-arg
+../tar_texi/tar.texi(FIXME,1773)
+../tar_texi/tar.texi(,1774)
+../tar_texi/tar.texi(,1775) @node tar invocation
+../tar_texi/tar.texi(GNUTAR,1776) @chapter Invoking
../tar_texi/tar.texi(GNUTAR,1776) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1776)
+../tar_texi/tar.texi(UNREVISED,1777) @quotation
+../tar_texi/tar.texi(UNREVISED,1777) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,1777) @end quotation
+../tar_texi/tar.texi(UNREVISED,1777)
+../tar_texi/tar.texi(,1778)
+../tar_texi/tar.texi(GNUTAR,1779) This chapter is about how one invokes the
../tar_texi/tar.texi(GNUTAR,1779) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1779)
+../tar_texi/tar.texi(,1780) command, from the command synopsis
(@pxref{Synopsis}). There are
+../tar_texi/tar.texi(,1781) numerous options, and many styles for writing
them. One mandatory
+../tar_texi/tar.texi(,1782) option specifies the operation @command{tar}
should perform
+../tar_texi/tar.texi(,1783) (@pxref{Operation Summary}), other options are
meant to detail how
+../tar_texi/tar.texi(,1784) this operation should be performed (@pxref{Option
Summary}).
+../tar_texi/tar.texi(,1785) Non-option arguments are not always interpreted
the same way,
+../tar_texi/tar.texi(,1786) depending on what the operation is.
+../tar_texi/tar.texi(,1787)
+../tar_texi/tar.texi(,1788) You will find in this chapter everything about
option styles and rules for
+../tar_texi/tar.texi(,1789) writing them (@pxref{Styles}). On the other hand,
operations and options
+../tar_texi/tar.texi(,1790) are fully described elsewhere, in other chapters.
Here, you will find
+../tar_texi/tar.texi(,1791) only synthetic descriptions for operations and
options, together with
+../tar_texi/tar.texi(,1792) pointers to other parts of the @command{tar}
manual.
+../tar_texi/tar.texi(,1793)
+../tar_texi/tar.texi(,1794) Some options are so special they are fully
described right in this
+../tar_texi/tar.texi(,1795) chapter. They have the effect of inhibiting the
normal operation of
+../tar_texi/tar.texi(,1796) @command{tar} or else, they globally alter the
amount of feedback the user
+../tar_texi/tar.texi(,1797) receives about what is going on. These are the
@option{--help} and
+../tar_texi/tar.texi(,1798) @option{--version} (@pxref{help}),
@option{--verbose} (@pxref{verbose})
+../tar_texi/tar.texi(,1799) and @option{--interactive} options
(@pxref{interactive}).
+../tar_texi/tar.texi(,1800)
+../tar_texi/tar.texi(,1801) @menu
+../tar_texi/tar.texi(,1802) * Synopsis::
+../tar_texi/tar.texi(,1803) * using tar options::
+../tar_texi/tar.texi(,1804) * Styles::
+../tar_texi/tar.texi(,1805) * All Options::
+../tar_texi/tar.texi(,1806) * help::
+../tar_texi/tar.texi(,1807) * defaults::
+../tar_texi/tar.texi(,1808) * verbose::
+../tar_texi/tar.texi(,1809) * interactive::
+../tar_texi/tar.texi(,1810) @end menu
+../tar_texi/tar.texi(,1811)
+../tar_texi/tar.texi(,1812) @node Synopsis
+../tar_texi/tar.texi(,1813) @section General Synopsis of @command{tar}
+../tar_texi/tar.texi(,1814)
+../tar_texi/tar.texi(GNUTAR,1815) The ../tar_texi/tar.texi(GNUTAR,1815)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,1815) program is
invoked as either one of:
+../tar_texi/tar.texi(,1816)
+../tar_texi/tar.texi(,1817) @smallexample
+../tar_texi/tar.texi(,1818) @kbd{tar @address@hidden address@hidden@dots{}}
+../tar_texi/tar.texi(,1819) @kbd{tar @address@hidden address@hidden@dots{}
address@hidden@dots{} address@hidden@dots{}}
+../tar_texi/tar.texi(,1820) @end smallexample
+../tar_texi/tar.texi(,1821)
+../tar_texi/tar.texi(,1822) The second form is for when old options are being
used.
+../tar_texi/tar.texi(,1823)
+../tar_texi/tar.texi(,1824) You can use @command{tar} to store files in an
archive, to extract them from
+../tar_texi/tar.texi(,1825) an archive, and to do other types of archive
manipulation. The primary
+../tar_texi/tar.texi(,1826) argument to @command{tar}, which is called the
@dfn{operation}, specifies
+../tar_texi/tar.texi(,1827) which action to take. The other arguments to
@command{tar} are either
+../tar_texi/tar.texi(,1828) @dfn{options}, which change the way @command{tar}
performs an operation,
+../tar_texi/tar.texi(,1829) or file names or archive members, which specify
the files or members
+../tar_texi/tar.texi(,1830) @command{tar} is to act on.
+../tar_texi/tar.texi(,1831)
+../tar_texi/tar.texi(,1832) You can actually type in arguments in any order,
even if in this manual
+../tar_texi/tar.texi(,1833) the options always precede the other arguments, to
make examples easier
+../tar_texi/tar.texi(,1834) to understand. Further, the option stating the
main operation mode
+../tar_texi/tar.texi(,1835) (the @command{tar} main command) is usually given
first.
+../tar_texi/tar.texi(,1836)
+../tar_texi/tar.texi(,1837) Each @var{name} in the synopsis above is
interpreted as an archive member
+../tar_texi/tar.texi(,1838) name when the main command is one of
@option{--compare}
+../tar_texi/tar.texi(,1839) (@option{--diff}, @option{-d}), @option{--delete},
@option{--extract}
+../tar_texi/tar.texi(,1840) (@option{--get}, @option{-x}), @option{--list}
(@option{-t}) or
+../tar_texi/tar.texi(,1841) @option{--update} (@option{-u}). When naming
archive members, you
+../tar_texi/tar.texi(,1842) must give the exact name of the member in the
archive, as it is
+../tar_texi/tar.texi(,1843) printed by @option{--list}. For @option{--append}
(@option{-r}) and
+../tar_texi/tar.texi(,1844) @option{--create} (@option{-c}), these @var{name}
arguments specify
+../tar_texi/tar.texi(,1845) the names of either files or directory hierarchies
to place in the archive.
+../tar_texi/tar.texi(,1846) These files or hierarchies should already exist in
the file system,
+../tar_texi/tar.texi(,1847) prior to the execution of the @command{tar}
command.
+../tar_texi/tar.texi(,1848)
+../tar_texi/tar.texi(,1849) @command{tar} interprets relative file names as
being relative to the
+../tar_texi/tar.texi(,1850) working directory. @command{tar} will make all
file names relative
+../tar_texi/tar.texi(,1851) (by removing leading slashes when archiving or
restoring files),
+../tar_texi/tar.texi(,1852) unless you specify otherwise (using the
@option{--absolute-names}
+../tar_texi/tar.texi(,1853) option). @xref{absolute}, for more information
about
+../tar_texi/tar.texi(,1854) @option{--absolute-names}.
+../tar_texi/tar.texi(,1855)
+../tar_texi/tar.texi(,1856) If you give the name of a directory as either a
file name or a member
+../tar_texi/tar.texi(,1857) name, then @command{tar} acts recursively on all
the files and directories
+../tar_texi/tar.texi(,1858) beneath that directory. For example, the name
@file{/} identifies all
+../tar_texi/tar.texi(,1859) the files in the file system to @command{tar}.
+../tar_texi/tar.texi(,1860)
+../tar_texi/tar.texi(,1861) The distinction between file names and archive
member names is especially
+../tar_texi/tar.texi(,1862) important when shell globbing is used, and
sometimes a source of confusion
+../tar_texi/tar.texi(,1863) for newcomers. @xref{wildcards}, for more
information about globbing.
+../tar_texi/tar.texi(,1864) The problem is that shells may only glob using
existing files in the
+../tar_texi/tar.texi(,1865) file system. Only @command{tar} itself may glob
on archive members, so when
+../tar_texi/tar.texi(,1866) needed, you must ensure that wildcard characters
reach @command{tar} without
+../tar_texi/tar.texi(,1867) being interpreted by the shell first. Using a
backslash before @samp{*}
+../tar_texi/tar.texi(,1868) or @samp{?}, or putting the whole argument between
quotes, is usually
+../tar_texi/tar.texi(,1869) sufficient for this.
+../tar_texi/tar.texi(,1870)
+../tar_texi/tar.texi(,1871) Even if @var{name}s are often specified on the
command line, they
+../tar_texi/tar.texi(,1872) can also be read from a text file in the file
system, using the
+../tar_texi/tar.texi(,1873) @address@hidden (@option{-T @var{file-of-names}})
option.
+../tar_texi/tar.texi(,1874)
+../tar_texi/tar.texi(,1875) If you don't use any file name arguments,
@option{--append} (@option{-r}),
+../tar_texi/tar.texi(,1876) @option{--delete} and @option{--concatenate}
(@option{--catenate},
+../tar_texi/tar.texi(,1877) @option{-A}) will do nothing, while
@option{--create} (@option{-c})
+../tar_texi/tar.texi(,1878) will usually yield a diagnostic and inhibit
@command{tar} execution.
+../tar_texi/tar.texi(,1879) The other operations of @command{tar}
(@option{--list},
+../tar_texi/tar.texi(,1880) @option{--extract}, @option{--compare}, and
@option{--update})
+../tar_texi/tar.texi(,1881) will act on the entire contents of the archive.
+../tar_texi/tar.texi(,1882)
+../tar_texi/tar.texi(,1883) @cindex exit status
+../tar_texi/tar.texi(,1884) @cindex return status
+../tar_texi/tar.texi(GNUTAR,1885) Besides successful exits,
../tar_texi/tar.texi(GNUTAR,1885) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1885) may fail for
+../tar_texi/tar.texi(,1886) many reasons. Some reasons correspond to bad
usage, that is, when the
+../tar_texi/tar.texi(,1887) @command{tar} command is improperly written.
Errors may be
+../tar_texi/tar.texi(,1888) encountered later, while encountering an error
processing the archive
+../tar_texi/tar.texi(,1889) or the files. Some errors are recoverable, in
which case the failure
+../tar_texi/tar.texi(,1890) is delayed until @command{tar} has completed all
its work. Some
+../tar_texi/tar.texi(,1891) errors are such that it would not meaningful, or
at least risky, to
+../tar_texi/tar.texi(,1892) continue processing: @command{tar} then aborts
processing immediately.
+../tar_texi/tar.texi(,1893) All abnormal exits, whether immediate or delayed,
should always be
+../tar_texi/tar.texi(,1894) clearly diagnosed on @code{stderr}, after a line
stating the nature of
+../tar_texi/tar.texi(,1895) the error.
+../tar_texi/tar.texi(,1896)
+../tar_texi/tar.texi(GNUTAR,1897) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1897) returns only a few exit
statuses. I'm really
+../tar_texi/tar.texi(,1898) aiming simplicity in that area, for now. If you
are not using the
+../tar_texi/tar.texi(,1899) @option{--compare} @option{--diff}, @option{-d})
option, zero means
+../tar_texi/tar.texi(,1900) that everything went well, besides maybe innocuous
warnings. Nonzero
+../tar_texi/tar.texi(,1901) means that something went wrong. Right now, as of
today, ``nonzero''
+../tar_texi/tar.texi(,1902) is almost always 2, except for remote operations,
where it may be
+../tar_texi/tar.texi(,1903) 128.
+../tar_texi/tar.texi(,1904)
+../tar_texi/tar.texi(,1905) @node using tar options
+../tar_texi/tar.texi(,1906) @section Using @command{tar} Options
+../tar_texi/tar.texi(,1907)
+../tar_texi/tar.texi(GNUTAR,1908) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,1908) has a total of eight operating
modes which
+../tar_texi/tar.texi(,1909) allow you to perform a variety of tasks. You are
required to choose
+../tar_texi/tar.texi(,1910) one operating mode each time you employ the
@command{tar} program by
+../tar_texi/tar.texi(,1911) specifying one, and only one operation as an
argument to the
+../tar_texi/tar.texi(,1912) @command{tar} command (two lists of four
operations each may be found
+../tar_texi/tar.texi(,1913) at @ref{frequent operations} and
@ref{Operations}). Depending on
+../tar_texi/tar.texi(,1914) circumstances, you may also wish to customize how
the chosen operating
+../tar_texi/tar.texi(,1915) mode behaves. For example, you may wish to change
the way the output
+../tar_texi/tar.texi(,1916) looks, or the format of the files that you wish to
archive may require
+../tar_texi/tar.texi(,1917) you to do something special in order to make the
archive look right.
+../tar_texi/tar.texi(,1918)
+../tar_texi/tar.texi(,1919) You can customize and control @command{tar}'s
performance by running
+../tar_texi/tar.texi(,1920) @command{tar} with one or more options (such as
@option{--verbose}
+../tar_texi/tar.texi(,1921) (@option{-v}), which we used in the tutorial). As
we said in the
+../tar_texi/tar.texi(,1922) tutorial, @dfn{options} are arguments to
@command{tar} which are (as
+../tar_texi/tar.texi(,1923) their name suggests) optional. Depending on the
operating mode, you
+../tar_texi/tar.texi(,1924) may specify one or more options. Different options
will have different
+../tar_texi/tar.texi(,1925) effects, but in general they all change details of
the operation, such
+../tar_texi/tar.texi(,1926) as archive format, archive name, or level of user
interaction. Some
+../tar_texi/tar.texi(,1927) options make sense with all operating modes, while
others are
+../tar_texi/tar.texi(,1928) meaningful only with particular modes. You will
likely use some
+../tar_texi/tar.texi(,1929) options frequently, while you will only use others
infrequently, or
+../tar_texi/tar.texi(,1930) not at all. (A full list of options is available
in @pxref{All Options}.)
+../tar_texi/tar.texi(,1931)
+../tar_texi/tar.texi(,1932) @vrindex TAR_OPTIONS, environment variable
+../tar_texi/tar.texi(,1933) @anchor{TAR_OPTIONS}
+../tar_texi/tar.texi(,1934) The @env{TAR_OPTIONS} environment variable
specifies default options to
+../tar_texi/tar.texi(,1935) be placed in front of any explicit options. For
example, if
+../tar_texi/tar.texi(,1936) @code{TAR_OPTIONS} is @samp{-v --unlink-first},
@command{tar} behaves as
+../tar_texi/tar.texi(,1937) if the two options @option{-v} and
@option{--unlink-first} had been
+../tar_texi/tar.texi(,1938) specified before any explicit options. Option
specifications are
+../tar_texi/tar.texi(,1939) separated by whitespace. A backslash escapes the
next character, so it
+../tar_texi/tar.texi(,1940) can be used to specify an option containing
whitespace or a backslash.
+../tar_texi/tar.texi(,1941)
+../tar_texi/tar.texi(,1942) Note that @command{tar} options are case
sensitive. For example, the
+../tar_texi/tar.texi(,1943) options @option{-T} and @option{-t} are different;
the first requires an
+../tar_texi/tar.texi(,1944) argument for stating the name of a file providing
a list of @var{name}s,
+../tar_texi/tar.texi(,1945) while the second does not require an argument and
is another way to
+../tar_texi/tar.texi(,1946) write @option{--list} (@option{-t}).
+../tar_texi/tar.texi(,1947)
+../tar_texi/tar.texi(,1948) In addition to the eight operations, there are
many options to
+../tar_texi/tar.texi(,1949) @command{tar}, and three different styles for
writing both: long (mnemonic)
+../tar_texi/tar.texi(,1950) form, short form, and old style. These styles are
discussed below.
+../tar_texi/tar.texi(,1951) Both the options and the operations can be written
in any of these three
+../tar_texi/tar.texi(,1952) styles.
+../tar_texi/tar.texi(,1953)
+../tar_texi/tar.texi(FIXME,1956) @allow-recursion
+../tar_texi/tar.texi(FIXME,1956) @quote-arg
+../tar_texi/tar.texi(FIXME,1956)
+../tar_texi/tar.texi(,1957)
+../tar_texi/tar.texi(,1958) @node Styles
+../tar_texi/tar.texi(,1959) @section The Three Option Styles
+../tar_texi/tar.texi(,1960)
+../tar_texi/tar.texi(,1961) There are three styles for writing operations and
options to the command
+../tar_texi/tar.texi(,1962) line invoking @command{tar}. The different styles
were developed at
+../tar_texi/tar.texi(,1963) different times during the history of
@command{tar}. These styles will be
+../tar_texi/tar.texi(,1964) presented below, from the most recent to the
oldest.
+../tar_texi/tar.texi(,1965)
+../tar_texi/tar.texi(,1966) Some options must take an argument. (For example,
@option{--file}
+../tar_texi/tar.texi(,1967) (@option{-f})) takes the name of an archive file
as an argument. If
+../tar_texi/tar.texi(,1968) you do not supply an archive file name,
@command{tar} will use a
+../tar_texi/tar.texi(,1969) default, but this can be confusing; thus, we
recommend that you always
+../tar_texi/tar.texi(,1970) supply a specific archive file name.) Where you
@emph{place} the
+../tar_texi/tar.texi(,1971) arguments generally depends on which style of
options you choose. We
+../tar_texi/tar.texi(,1972) will detail specific information relevant to each
option style in the
+../tar_texi/tar.texi(,1973) sections on the different option styles, below.
The differences are
+../tar_texi/tar.texi(,1974) subtle, yet can often be very important; incorrect
option placement
+../tar_texi/tar.texi(,1975) can cause you to overwrite a number of important
files. We urge you
+../tar_texi/tar.texi(,1976) to note these differences, and only use the option
style(s) which
+../tar_texi/tar.texi(,1977) makes the most sense to you until you feel
comfortable with the others.
+../tar_texi/tar.texi(,1978)
+../tar_texi/tar.texi(,1979) Some options @emph{may} take an argument. Such
options may have at
+../tar_texi/tar.texi(,1980) most long and short forms, they do not have old
style equivalent. The
+../tar_texi/tar.texi(,1981) rules for specifying an argument for such options
are stricter than
+../tar_texi/tar.texi(,1982) those for specifying mandatory arguments. Please,
pay special
+../tar_texi/tar.texi(,1983) attention to them.
+../tar_texi/tar.texi(,1984)
+../tar_texi/tar.texi(,1985) @menu
+../tar_texi/tar.texi(,1986) * Long Options:: Long Option Style
+../tar_texi/tar.texi(,1987) * Short Options:: Short Option Style
+../tar_texi/tar.texi(,1988) * Old Options:: Old Option Style
+../tar_texi/tar.texi(,1989) * Mixing:: Mixing Option
Styles
+../tar_texi/tar.texi(,1990) @end menu
+../tar_texi/tar.texi(,1991)
+../tar_texi/tar.texi(,1992) @node Long Options
+../tar_texi/tar.texi(,1993) @subsection Long Option Style
+../tar_texi/tar.texi(,1994)
+../tar_texi/tar.texi(,1995) Each option has at least one @dfn{long} (or
@dfn{mnemonic}) name starting with two
+../tar_texi/tar.texi(,1996) dashes in a row, e.g., @option{--list}. The long
names are more clear than
+../tar_texi/tar.texi(,1997) their corresponding short or old names. It
sometimes happens that a
+../tar_texi/tar.texi(,1998) single long option has many different different
names which are
+../tar_texi/tar.texi(,1999) synonymous, such as @option{--compare} and
@option{--diff}. In addition,
+../tar_texi/tar.texi(,2000) long option names can be given unique
abbreviations. For example,
+../tar_texi/tar.texi(,2001) @option{--cre} can be used in place of
@option{--create} because there is no
+../tar_texi/tar.texi(,2002) other long option which begins with @samp{cre}.
(One way to find
+../tar_texi/tar.texi(,2003) this out is by trying it and seeing what happens;
if a particular
+../tar_texi/tar.texi(,2004) abbreviation could represent more than one option,
@command{tar} will tell
+../tar_texi/tar.texi(,2005) you that that abbreviation is ambiguous and you'll
know that that
+../tar_texi/tar.texi(,2006) abbreviation won't work. You may also choose to
run @samp{tar --help}
+../tar_texi/tar.texi(,2007) to see a list of options. Be aware that if you
run @command{tar} with a
+../tar_texi/tar.texi(,2008) unique abbreviation for the long name of an option
you didn't want to
+../tar_texi/tar.texi(,2009) use, you are stuck; @command{tar} will perform the
command as ordered.)
+../tar_texi/tar.texi(,2010)
+../tar_texi/tar.texi(,2011) Long options are meant to be obvious and easy to
remember, and their
+../tar_texi/tar.texi(,2012) meanings are generally easier to discern than
those of their
+../tar_texi/tar.texi(,2013) corresponding short options (see below). For
example:
+../tar_texi/tar.texi(,2014)
+../tar_texi/tar.texi(,2015) @smallexample
+../tar_texi/tar.texi(,2016) $ @kbd{tar --create --verbose --blocking-factor=20
--file=/dev/rmt0}
+../tar_texi/tar.texi(,2017) @end smallexample
+../tar_texi/tar.texi(,2018)
+../tar_texi/tar.texi(,2019) @noindent
+../tar_texi/tar.texi(,2020) gives a fairly good set of hints about what the
command does, even
+../tar_texi/tar.texi(,2021) for those not fully acquainted with @command{tar}.
+../tar_texi/tar.texi(,2022)
+../tar_texi/tar.texi(,2023) Long options which require arguments take those
arguments
+../tar_texi/tar.texi(,2024) immediately following the option name. There are
two ways of
+../tar_texi/tar.texi(,2025) specifying a mandatory argument. It can be
separated from the
+../tar_texi/tar.texi(,2026) option name either by an equal sign, or by any
amount of
+../tar_texi/tar.texi(,2027) white space characters. For example, the
@option{--file} option (which
+../tar_texi/tar.texi(,2028) tells the name of the @command{tar} archive) is
given a file such as
+../tar_texi/tar.texi(,2029) @file{archive.tar} as argument by using any of the
following notations:
+../tar_texi/tar.texi(,2030) @option{--file=archive.tar} or @option{--file
archive.tar}.
+../tar_texi/tar.texi(,2031)
+../tar_texi/tar.texi(,2032) In contrast, optional arguments must always be
introduced using
+../tar_texi/tar.texi(,2033) an equal sign. For example, the @option{--backup}
option takes
+../tar_texi/tar.texi(,2034) an optional argument specifying backup type. It
must be used
+../tar_texi/tar.texi(,2035) as @address@hidden
+../tar_texi/tar.texi(,2036)
+../tar_texi/tar.texi(,2037) @node Short Options
+../tar_texi/tar.texi(,2038) @subsection Short Option Style
+../tar_texi/tar.texi(,2039)
+../tar_texi/tar.texi(,2040) Most options also have a @dfn{short option} name.
Short options start with
+../tar_texi/tar.texi(,2041) a single dash, and are followed by a single
character, e.g., @option{-t}
+../tar_texi/tar.texi(,2042) (which is equivalent to @option{--list}). The
forms are absolutely
+../tar_texi/tar.texi(,2043) identical in function; they are interchangeable.
+../tar_texi/tar.texi(,2044)
+../tar_texi/tar.texi(,2045) The short option names are faster to type than
long option names.
+../tar_texi/tar.texi(,2046)
+../tar_texi/tar.texi(,2047) Short options which require arguments take their
arguments immediately
+../tar_texi/tar.texi(,2048) following the option, usually separated by white
space. It is also
+../tar_texi/tar.texi(,2049) possible to stick the argument right after the
short option name, using
+../tar_texi/tar.texi(,2050) no intervening space. For example, you might
write @address@hidden
+../tar_texi/tar.texi(,2051) archive.tar}} or @option{-farchive.tar} instead of
using
+../tar_texi/tar.texi(,2052) @option{--file=archive.tar}. Both @address@hidden
and
+../tar_texi/tar.texi(,2053) @address@hidden @var{archive-name}}} denote the
option which indicates a
+../tar_texi/tar.texi(,2054) specific archive, here named @file{archive.tar}.
+../tar_texi/tar.texi(,2055)
+../tar_texi/tar.texi(,2056) Short options which take optional arguments take
their arguments
+../tar_texi/tar.texi(,2057) immediately following the option letter,
@emph{without any intervening
+../tar_texi/tar.texi(,2058) white space characters}.
+../tar_texi/tar.texi(,2059)
+../tar_texi/tar.texi(,2060) Short options' letters may be clumped together,
but you are not
+../tar_texi/tar.texi(,2061) required to do this (as compared to old options;
see below). When
+../tar_texi/tar.texi(,2062) short options are clumped as a set, use one
(single) dash for them
+../tar_texi/tar.texi(,2063) all, e.g., @address@hidden@command{tar} -cvf}}.
Only the last option in
+../tar_texi/tar.texi(,2064) such a set is allowed to have an address@hidden
many
+../tar_texi/tar.texi(,2065) options, the last of which has an argument, is a
rather opaque way to
+../tar_texi/tar.texi(,2066) write options. Some wonder if @acronym{GNU}
@code{getopt} should not
+../tar_texi/tar.texi(,2067) even be made helpful enough for considering such
usages as invalid.}.
+../tar_texi/tar.texi(,2068)
+../tar_texi/tar.texi(,2069) When the options are separated, the argument for
each option which requires
+../tar_texi/tar.texi(,2070) an argument directly follows that option, as is
usual for Unix programs.
+../tar_texi/tar.texi(,2071) For example:
+../tar_texi/tar.texi(,2072)
+../tar_texi/tar.texi(,2073) @smallexample
+../tar_texi/tar.texi(,2074) $ @kbd{tar -c -v -b 20 -f /dev/rmt0}
+../tar_texi/tar.texi(,2075) @end smallexample
+../tar_texi/tar.texi(,2076)
+../tar_texi/tar.texi(,2077) If you reorder short options' locations, be sure
to move any arguments
+../tar_texi/tar.texi(,2078) that belong to them. If you do not move the
arguments properly, you may
+../tar_texi/tar.texi(,2079) end up overwriting files.
+../tar_texi/tar.texi(,2080)
+../tar_texi/tar.texi(,2081) @node Old Options
+../tar_texi/tar.texi(,2082) @subsection Old Option Style
+../tar_texi/tar.texi(UNREVISED,2083) @quotation
+../tar_texi/tar.texi(UNREVISED,2083) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,2083) @end quotation
+../tar_texi/tar.texi(UNREVISED,2083)
+../tar_texi/tar.texi(,2084)
+../tar_texi/tar.texi(,2085) Like short options, @dfn{old options} are single
letters. However, old options
+../tar_texi/tar.texi(,2086) must be written together as a single clumped set,
without spaces separating
+../tar_texi/tar.texi(,2087) them or dashes preceding address@hidden that if
you precede options
+../tar_texi/tar.texi(,2088) with a dash, you are announcing the short option
style instead of the
+../tar_texi/tar.texi(,2089) old option style; short options are decoded
differently.}. This set
+../tar_texi/tar.texi(,2090) of letters must be the first to appear on the
command line, after the
+../tar_texi/tar.texi(,2091) @command{tar} program name and some white space;
old options cannot appear
+../tar_texi/tar.texi(,2092) anywhere else. The letter of an old option is
exactly the same letter as
+../tar_texi/tar.texi(,2093) the corresponding short option. For example, the
old option @samp{t} is
+../tar_texi/tar.texi(,2094) the same as the short option @option{-t}, and
consequently, the same as the
+../tar_texi/tar.texi(,2095) long option @option{--list}. So for example, the
command @address@hidden
+../tar_texi/tar.texi(,2096) cv}} specifies the option @option{-v} in addition
to the operation @option{-c}.
+../tar_texi/tar.texi(,2097)
+../tar_texi/tar.texi(,2098) When options that need arguments are given
together with the command,
+../tar_texi/tar.texi(,2099) all the associated arguments follow, in the same
order as the options.
+../tar_texi/tar.texi(,2100) Thus, the example given previously could also be
written in the old
+../tar_texi/tar.texi(,2101) style as follows:
+../tar_texi/tar.texi(,2102)
+../tar_texi/tar.texi(,2103) @smallexample
+../tar_texi/tar.texi(,2104) $ @kbd{tar cvbf 20 /dev/rmt0}
+../tar_texi/tar.texi(,2105) @end smallexample
+../tar_texi/tar.texi(,2106)
+../tar_texi/tar.texi(,2107) @noindent
+../tar_texi/tar.texi(,2108) Here, @samp{20} is the argument of @option{-b} and
@samp{/dev/rmt0} is
+../tar_texi/tar.texi(,2109) the argument of @option{-f}.
+../tar_texi/tar.texi(,2110)
+../tar_texi/tar.texi(,2111) On the other hand, this old style syntax makes it
difficult to match
+../tar_texi/tar.texi(,2112) option letters with their corresponding arguments,
and is often
+../tar_texi/tar.texi(,2113) confusing. In the command @address@hidden cvbf 20
/dev/rmt0}}, for example,
+../tar_texi/tar.texi(,2114) @samp{20} is the argument for @option{-b},
@samp{/dev/rmt0} is the
+../tar_texi/tar.texi(,2115) argument for @option{-f}, and @option{-v} does not
have a corresponding
+../tar_texi/tar.texi(,2116) argument. Even using short options like in
@address@hidden -c -v -b 20 -f
+../tar_texi/tar.texi(,2117) /dev/rmt0}} is clearer, putting all arguments next
to the option they
+../tar_texi/tar.texi(,2118) pertain to.
+../tar_texi/tar.texi(,2119)
+../tar_texi/tar.texi(,2120) If you want to reorder the letters in the old
option argument, be
+../tar_texi/tar.texi(,2121) sure to reorder any corresponding argument
appropriately.
+../tar_texi/tar.texi(,2122)
+../tar_texi/tar.texi(,2123) This old way of writing @command{tar} options can
surprise even experienced
+../tar_texi/tar.texi(,2124) users. For example, the two commands:
+../tar_texi/tar.texi(,2125)
+../tar_texi/tar.texi(,2126) @smallexample
+../tar_texi/tar.texi(,2127) @kbd{tar cfz archive.tar.gz file}
+../tar_texi/tar.texi(,2128) @kbd{tar -cfz archive.tar.gz file}
+../tar_texi/tar.texi(,2129) @end smallexample
+../tar_texi/tar.texi(,2130)
+../tar_texi/tar.texi(,2131) @noindent
+../tar_texi/tar.texi(,2132) are quite different. The first example uses
@file{archive.tar.gz} as
+../tar_texi/tar.texi(,2133) the value for option @samp{f} and recognizes the
option @samp{z}. The
+../tar_texi/tar.texi(,2134) second example, however, uses @file{z} as the
value for option
+../tar_texi/tar.texi(,2135) @samp{f} --- probably not what was intended.
+../tar_texi/tar.texi(,2136)
+../tar_texi/tar.texi(,2137) Old options are kept for compatibility with old
versions of @command{tar}.
+../tar_texi/tar.texi(,2138)
+../tar_texi/tar.texi(,2139) This second example could be corrected in many
ways, among which the
+../tar_texi/tar.texi(,2140) following are equivalent:
+../tar_texi/tar.texi(,2141)
+../tar_texi/tar.texi(,2142) @smallexample
+../tar_texi/tar.texi(,2143) @kbd{tar -czf archive.tar.gz file}
+../tar_texi/tar.texi(,2144) @kbd{tar -cf archive.tar.gz -z file}
+../tar_texi/tar.texi(,2145) @kbd{tar cf archive.tar.gz -z file}
+../tar_texi/tar.texi(,2146) @end smallexample
+../tar_texi/tar.texi(,2147)
+../tar_texi/tar.texi(,2148) @cindex option syntax, traditional
+../tar_texi/tar.texi(,2149) As far as we know, all @command{tar} programs,
@acronym{GNU} and
+../tar_texi/tar.texi(GNUTAR,2150) address@hidden, support old options.
../tar_texi/tar.texi(GNUTAR,2150) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,2150)
+../tar_texi/tar.texi(,2151) supports them not only for historical reasons, but
also because many
+../tar_texi/tar.texi(,2152) people are used to them. For compatibility with
Unix @command{tar},
+../tar_texi/tar.texi(,2153) the first argument is always treated as containing
command and option
+../tar_texi/tar.texi(,2154) letters even if it doesn't start with @samp{-}.
Thus, @samp{tar c} is
+../tar_texi/tar.texi(,2155) equivalent to @address@hidden -c}:} both of them
specify the
+../tar_texi/tar.texi(,2156) @option{--create} (@option{-c}) command to create
an archive.
+../tar_texi/tar.texi(,2157)
+../tar_texi/tar.texi(,2158) @node Mixing
+../tar_texi/tar.texi(,2159) @subsection Mixing Option Styles
+../tar_texi/tar.texi(,2160)
+../tar_texi/tar.texi(,2161) All three styles may be intermixed in a single
@command{tar} command,
+../tar_texi/tar.texi(,2162) so long as the rules for each style are fully
+../tar_texi/tar.texi(GNUTAR,2163) address@hidden @acronym{GNU} @command{tar}
version 1.11.6,
+../tar_texi/tar.texi(,2164) a bug prevented intermixing old style options with
long options in
+../tar_texi/tar.texi(,2165) some cases.}. Old style options and either of the
modern styles of
+../tar_texi/tar.texi(,2166) options may be mixed within a single @command{tar}
command. However,
+../tar_texi/tar.texi(,2167) old style options must be introduced as the first
arguments only,
+../tar_texi/tar.texi(,2168) following the rule for old options (old options
must appear directly
+../tar_texi/tar.texi(,2169) after the @command{tar} command and some white
space). Modern options
+../tar_texi/tar.texi(,2170) may be given only after all arguments to the old
options have been
+../tar_texi/tar.texi(,2171) collected. If this rule is not respected, a
modern option might be
+../tar_texi/tar.texi(,2172) falsely interpreted as the value of the argument
to one of the old
+../tar_texi/tar.texi(,2173) style options.
+../tar_texi/tar.texi(,2174)
+../tar_texi/tar.texi(,2175) For example, all the following commands are wholly
equivalent, and
+../tar_texi/tar.texi(,2176) illustrate the many combinations and orderings of
option styles.
+../tar_texi/tar.texi(,2177)
+../tar_texi/tar.texi(,2178) @smallexample
+../tar_texi/tar.texi(,2179) @kbd{tar --create --file=archive.tar}
+../tar_texi/tar.texi(,2180) @kbd{tar --create -f archive.tar}
+../tar_texi/tar.texi(,2181) @kbd{tar --create -farchive.tar}
+../tar_texi/tar.texi(,2182) @kbd{tar --file=archive.tar --create}
+../tar_texi/tar.texi(,2183) @kbd{tar --file=archive.tar -c}
+../tar_texi/tar.texi(,2184) @kbd{tar -c --file=archive.tar}
+../tar_texi/tar.texi(,2185) @kbd{tar -c -f archive.tar}
+../tar_texi/tar.texi(,2186) @kbd{tar -c -farchive.tar}
+../tar_texi/tar.texi(,2187) @kbd{tar -cf archive.tar}
+../tar_texi/tar.texi(,2188) @kbd{tar -cfarchive.tar}
+../tar_texi/tar.texi(,2189) @kbd{tar -f archive.tar --create}
+../tar_texi/tar.texi(,2190) @kbd{tar -f archive.tar -c}
+../tar_texi/tar.texi(,2191) @kbd{tar -farchive.tar --create}
+../tar_texi/tar.texi(,2192) @kbd{tar -farchive.tar -c}
+../tar_texi/tar.texi(,2193) @kbd{tar c --file=archive.tar}
+../tar_texi/tar.texi(,2194) @kbd{tar c -f archive.tar}
+../tar_texi/tar.texi(,2195) @kbd{tar c -farchive.tar}
+../tar_texi/tar.texi(,2196) @kbd{tar cf archive.tar}
+../tar_texi/tar.texi(,2197) @kbd{tar f archive.tar --create}
+../tar_texi/tar.texi(,2198) @kbd{tar f archive.tar -c}
+../tar_texi/tar.texi(,2199) @kbd{tar fc archive.tar}
+../tar_texi/tar.texi(,2200) @end smallexample
+../tar_texi/tar.texi(,2201)
+../tar_texi/tar.texi(,2202) On the other hand, the following commands are
@emph{not} equivalent to
+../tar_texi/tar.texi(,2203) the previous set:
+../tar_texi/tar.texi(,2204)
+../tar_texi/tar.texi(,2205) @smallexample
+../tar_texi/tar.texi(,2206) @kbd{tar -f -c archive.tar}
+../tar_texi/tar.texi(,2207) @kbd{tar -fc archive.tar}
+../tar_texi/tar.texi(,2208) @kbd{tar -fcarchive.tar}
+../tar_texi/tar.texi(,2209) @kbd{tar -farchive.tarc}
+../tar_texi/tar.texi(,2210) @kbd{tar cfarchive.tar}
+../tar_texi/tar.texi(,2211) @end smallexample
+../tar_texi/tar.texi(,2212)
+../tar_texi/tar.texi(,2213) @noindent
+../tar_texi/tar.texi(,2214) These last examples mean something completely
different from what the
+../tar_texi/tar.texi(,2215) user intended (judging based on the example in the
previous set which
+../tar_texi/tar.texi(,2216) uses long options, whose intent is therefore very
clear). The first
+../tar_texi/tar.texi(,2217) four specify that the @command{tar} archive would
be a file named
+../tar_texi/tar.texi(,2218) @option{-c}, @samp{c}, @samp{carchive.tar} or
@samp{archive.tarc},
+../tar_texi/tar.texi(,2219) respectively. The first two examples also specify
a single non-option,
+../tar_texi/tar.texi(,2220) @var{name} argument having the value
@samp{archive.tar}. The last
+../tar_texi/tar.texi(,2221) example contains only old style option letters
(repeating option
+../tar_texi/tar.texi(,2222) @samp{c} twice), not all of which are meaningful
(eg., @samp{.},
+../tar_texi/tar.texi(FIXME,2224) @samp{h}, or @samp{i}), with no argument
value. ../tar_texi/tar.texi(FIXME,2224) @allow-recursion
+../tar_texi/tar.texi(FIXME,2224) @quote-arg
+../tar_texi/tar.texi(FIXME,2224)
+../tar_texi/tar.texi(,2225)
+../tar_texi/tar.texi(,2226) @node All Options
+../tar_texi/tar.texi(,2227) @section All @command{tar} Options
+../tar_texi/tar.texi(,2228)
+../tar_texi/tar.texi(,2229) The coming manual sections contain an alphabetical
listing of all
+../tar_texi/tar.texi(,2230) @command{tar} operations and options, with brief
descriptions and cross
+../tar_texi/tar.texi(,2231) references to more in-depth explanations in the
body of the manual.
+../tar_texi/tar.texi(,2232) They also contain an alphabetically arranged table
of the short option
+../tar_texi/tar.texi(,2233) forms with their corresponding long option. You
can use this table as
+../tar_texi/tar.texi(,2234) a reference for deciphering @command{tar} commands
in scripts.
+../tar_texi/tar.texi(,2235)
+../tar_texi/tar.texi(,2236) @menu
+../tar_texi/tar.texi(,2237) * Operation Summary::
+../tar_texi/tar.texi(,2238) * Option Summary::
+../tar_texi/tar.texi(,2239) * Short Option Summary::
+../tar_texi/tar.texi(,2240) @end menu
+../tar_texi/tar.texi(,2241)
+../tar_texi/tar.texi(,2242) @node Operation Summary
+../tar_texi/tar.texi(,2243) @subsection Operations
+../tar_texi/tar.texi(,2244)
+../tar_texi/tar.texi(,2245) @table @option
+../tar_texi/tar.texi(,2246)
+../tar_texi/tar.texi(opsummary,2247) @anchor{--append}
+../tar_texi/tar.texi(opsummary,2247) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2247)
+../tar_texi/tar.texi(,2248) @item --append
+../tar_texi/tar.texi(,2249) @itemx -r
+../tar_texi/tar.texi(,2250)
+../tar_texi/tar.texi(,2251) Appends files to the end of the archive.
@xref{append}.
+../tar_texi/tar.texi(,2252)
+../tar_texi/tar.texi(opsummary,2253) @anchor{--catenate}
+../tar_texi/tar.texi(opsummary,2253) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2253)
+../tar_texi/tar.texi(,2254) @item --catenate
+../tar_texi/tar.texi(,2255) @itemx -A
+../tar_texi/tar.texi(,2256)
+../tar_texi/tar.texi(,2257) Same as @option{--concatenate}.
@xref{concatenate}.
+../tar_texi/tar.texi(,2258)
+../tar_texi/tar.texi(opsummary,2259) @anchor{--compare}
+../tar_texi/tar.texi(opsummary,2259) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2259)
+../tar_texi/tar.texi(,2260) @item --compare
+../tar_texi/tar.texi(,2261) @itemx -d
+../tar_texi/tar.texi(,2262)
+../tar_texi/tar.texi(,2263) Compares archive members with their counterparts
in the file
+../tar_texi/tar.texi(,2264) system, and reports differences in file size,
mode, owner,
+../tar_texi/tar.texi(,2265) modification date and contents. @xref{compare}.
+../tar_texi/tar.texi(,2266)
+../tar_texi/tar.texi(opsummary,2267) @anchor{--concatenate}
+../tar_texi/tar.texi(opsummary,2267) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2267)
+../tar_texi/tar.texi(,2268) @item --concatenate
+../tar_texi/tar.texi(,2269) @itemx -A
+../tar_texi/tar.texi(,2270)
+../tar_texi/tar.texi(,2271) Appends other @command{tar} archives to the end of
the archive.
+../tar_texi/tar.texi(,2272) @xref{concatenate}.
+../tar_texi/tar.texi(,2273)
+../tar_texi/tar.texi(opsummary,2274) @anchor{--create}
+../tar_texi/tar.texi(opsummary,2274) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2274)
+../tar_texi/tar.texi(,2275) @item --create
+../tar_texi/tar.texi(,2276) @itemx -c
+../tar_texi/tar.texi(,2277)
+../tar_texi/tar.texi(,2278) Creates a new @command{tar} archive.
@xref{create}.
+../tar_texi/tar.texi(,2279)
+../tar_texi/tar.texi(opsummary,2280) @anchor{--delete}
+../tar_texi/tar.texi(opsummary,2280) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2280)
+../tar_texi/tar.texi(,2281) @item --delete
+../tar_texi/tar.texi(,2282)
+../tar_texi/tar.texi(,2283) Deletes members from the archive. Don't try this
on a archive on a
+../tar_texi/tar.texi(,2284) tape! @xref{delete}.
+../tar_texi/tar.texi(,2285)
+../tar_texi/tar.texi(opsummary,2286) @anchor{--diff}
+../tar_texi/tar.texi(opsummary,2286) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2286)
+../tar_texi/tar.texi(,2287) @item --diff
+../tar_texi/tar.texi(,2288) @itemx -d
+../tar_texi/tar.texi(,2289)
+../tar_texi/tar.texi(,2290) Same @option{--compare}. @xref{compare}.
+../tar_texi/tar.texi(,2291)
+../tar_texi/tar.texi(opsummary,2292) @anchor{--extract}
+../tar_texi/tar.texi(opsummary,2292) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2292)
+../tar_texi/tar.texi(,2293) @item --extract
+../tar_texi/tar.texi(,2294) @itemx -x
+../tar_texi/tar.texi(,2295)
+../tar_texi/tar.texi(,2296) Extracts members from the archive into the file
system. @xref{extract}.
+../tar_texi/tar.texi(,2297)
+../tar_texi/tar.texi(opsummary,2298) @anchor{--get}
+../tar_texi/tar.texi(opsummary,2298) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2298)
+../tar_texi/tar.texi(,2299) @item --get
+../tar_texi/tar.texi(,2300) @itemx -x
+../tar_texi/tar.texi(,2301)
+../tar_texi/tar.texi(,2302) Same as @option{--extract}. @xref{extract}.
+../tar_texi/tar.texi(,2303)
+../tar_texi/tar.texi(opsummary,2304) @anchor{--list}
+../tar_texi/tar.texi(opsummary,2304) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2304)
+../tar_texi/tar.texi(,2305) @item --list
+../tar_texi/tar.texi(,2306) @itemx -t
+../tar_texi/tar.texi(,2307)
+../tar_texi/tar.texi(,2308) Lists the members in an archive. @xref{list}.
+../tar_texi/tar.texi(,2309)
+../tar_texi/tar.texi(opsummary,2310) @anchor{--update}
+../tar_texi/tar.texi(opsummary,2310) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2310)
+../tar_texi/tar.texi(,2311) @item --update
+../tar_texi/tar.texi(,2312) @itemx -u
+../tar_texi/tar.texi(,2313)
+../tar_texi/tar.texi(,2314) Adds files to the end of the archive, but only if
they are newer than
+../tar_texi/tar.texi(,2315) their counterparts already in the archive, or if
they do not already
+../tar_texi/tar.texi(,2316) exist in the archive. @xref{update}.
+../tar_texi/tar.texi(,2317)
+../tar_texi/tar.texi(,2318) @end table
+../tar_texi/tar.texi(,2319)
+../tar_texi/tar.texi(,2320) @node Option Summary
+../tar_texi/tar.texi(,2321) @subsection @command{tar} Options
+../tar_texi/tar.texi(,2322)
+../tar_texi/tar.texi(,2323) @table @option
+../tar_texi/tar.texi(,2324)
+../tar_texi/tar.texi(opsummary,2325) @anchor{--absolute-names}
+../tar_texi/tar.texi(opsummary,2325) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2325)
+../tar_texi/tar.texi(,2326) @item --absolute-names
+../tar_texi/tar.texi(,2327) @itemx -P
+../tar_texi/tar.texi(,2328)
+../tar_texi/tar.texi(,2329) Normally when creating an archive, @command{tar}
strips an initial
+../tar_texi/tar.texi(,2330) @samp{/} from member names. This option disables
that behavior.
+../tar_texi/tar.texi(,2331) @xref{absolute}.
+../tar_texi/tar.texi(,2332)
+../tar_texi/tar.texi(opsummary,2333) @anchor{--after-date}
+../tar_texi/tar.texi(opsummary,2333) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2333)
+../tar_texi/tar.texi(,2334) @item --after-date
+../tar_texi/tar.texi(,2335)
+../tar_texi/tar.texi(,2336) (See @option{--newer}, @pxref{after})
+../tar_texi/tar.texi(,2337)
+../tar_texi/tar.texi(opsummary,2338) @anchor{--anchored}
+../tar_texi/tar.texi(opsummary,2338) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2338)
+../tar_texi/tar.texi(,2339) @item --anchored
+../tar_texi/tar.texi(,2340) A pattern must match an initial subsequence of the
name's components.
+../tar_texi/tar.texi(,2341) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2342)
+../tar_texi/tar.texi(opsummary,2343) @anchor{--atime-preserve}
+../tar_texi/tar.texi(opsummary,2343) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2343)
+../tar_texi/tar.texi(,2344) @item --atime-preserve
+../tar_texi/tar.texi(,2345) @itemx --atime-preserve=replace
+../tar_texi/tar.texi(,2346) @itemx --atime-preserve=system
+../tar_texi/tar.texi(,2347)
+../tar_texi/tar.texi(,2348) Attempt to preserve the access time of files when
reading them. This
+../tar_texi/tar.texi(,2349) option currently is effective only on files that
you own, unless you
+../tar_texi/tar.texi(,2350) have superuser privileges.
+../tar_texi/tar.texi(,2351)
+../tar_texi/tar.texi(,2352) @option{--atime-preserve=replace} remembers the
access time of a file
+../tar_texi/tar.texi(,2353) before reading it, and then restores the access
time afterwards. This
+../tar_texi/tar.texi(,2354) may cause problems if other programs are reading
the file at the same
+../tar_texi/tar.texi(,2355) time, as the times of their accesses will be lost.
On most platforms
+../tar_texi/tar.texi(,2356) restoring the access time also requires
@command{tar} to restore the
+../tar_texi/tar.texi(,2357) data modification time too, so this option may
also cause problems if
+../tar_texi/tar.texi(,2358) other programs are writing the file at the same
time. (Tar attempts
+../tar_texi/tar.texi(,2359) to detect this situation, but cannot do so
reliably due to race
+../tar_texi/tar.texi(,2360) conditions.) Worse, on most platforms restoring
the access time also
+../tar_texi/tar.texi(,2361) updates the status change time, which means that
this option is
+../tar_texi/tar.texi(,2362) incompatible with incremental backups.
+../tar_texi/tar.texi(,2363)
+../tar_texi/tar.texi(,2364) @option{--atime-preserve=system} avoids changing
time stamps on files,
+../tar_texi/tar.texi(,2365) without interfering with time stamp updates
+../tar_texi/tar.texi(,2366) caused by other programs, so it works better with
incremental backups.
+../tar_texi/tar.texi(,2367) However, it requires a special @code{O_NOATIME}
option from the
+../tar_texi/tar.texi(,2368) underlying operating and file system
implementation, and it also requires
+../tar_texi/tar.texi(,2369) that searching directories does not update their
access times. As of
+../tar_texi/tar.texi(,2370) this writing (November 2005) this works only with
Linux, and only with
+../tar_texi/tar.texi(,2371) Linux kernels 2.6.8 and later. Worse, there is
currently no reliable
+../tar_texi/tar.texi(,2372) way to know whether this feature actually works.
Sometimes
+../tar_texi/tar.texi(,2373) @command{tar} knows that it does not work, and if
you use
+../tar_texi/tar.texi(,2374) @option{--atime-preserve=system} then
@command{tar} complains and
+../tar_texi/tar.texi(,2375) exits right away. But other times @command{tar}
might think that the
+../tar_texi/tar.texi(,2376) option works when it actually does not.
+../tar_texi/tar.texi(,2377)
+../tar_texi/tar.texi(,2378) Currently @option{--atime-preserve} with no
operand defaults to
+../tar_texi/tar.texi(,2379) @option{--atime-preserve=replace}, but this may
change in the future
+../tar_texi/tar.texi(,2380) as support for @option{--atime-preserve=system}
improves.
+../tar_texi/tar.texi(,2381)
+../tar_texi/tar.texi(,2382) If your operating system does not support
+../tar_texi/tar.texi(,2383) @address@hidden, you might be able to preserve
access
+../tar_texi/tar.texi(,2384) times reliably by by using the @command{mount}
command. For example,
+../tar_texi/tar.texi(,2385) you can mount the file system read-only, or access
the file system via
+../tar_texi/tar.texi(,2386) a read-only loopback mount, or use the
@samp{noatime} mount option
+../tar_texi/tar.texi(,2387) available on some systems. However, mounting
typically requires
+../tar_texi/tar.texi(,2388) superuser privileges and can be a pain to manage.
+../tar_texi/tar.texi(,2389)
+../tar_texi/tar.texi(opsummary,2390) @anchor{--backup}
+../tar_texi/tar.texi(opsummary,2390) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2390)
+../tar_texi/tar.texi(,2391) @item address@hidden
+../tar_texi/tar.texi(,2392)
+../tar_texi/tar.texi(,2393) Rather than deleting files from the file system,
@command{tar} will
+../tar_texi/tar.texi(,2394) back them up using simple or numbered backups,
depending upon
+../tar_texi/tar.texi(,2395) @var{backup-type}. @xref{backup}.
+../tar_texi/tar.texi(,2396)
+../tar_texi/tar.texi(opsummary,2397) @anchor{--block-number}
+../tar_texi/tar.texi(opsummary,2397) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2397)
+../tar_texi/tar.texi(,2398) @item --block-number
+../tar_texi/tar.texi(,2399) @itemx -R
+../tar_texi/tar.texi(,2400)
+../tar_texi/tar.texi(,2401) With this option present, @command{tar} prints
error messages for read errors
+../tar_texi/tar.texi(,2402) with the block number in the archive file.
@xref{block-number}.
+../tar_texi/tar.texi(,2403)
+../tar_texi/tar.texi(opsummary,2404) @anchor{--blocking-factor}
+../tar_texi/tar.texi(opsummary,2404) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2404)
+../tar_texi/tar.texi(,2405) @item address@hidden
+../tar_texi/tar.texi(,2406) @itemx -b @var{blocking}
+../tar_texi/tar.texi(,2407)
+../tar_texi/tar.texi(,2408) Sets the blocking factor @command{tar} uses to
@var{blocking} x 512 bytes per
+../tar_texi/tar.texi(,2409) record. @xref{Blocking Factor}.
+../tar_texi/tar.texi(,2410)
+../tar_texi/tar.texi(opsummary,2411) @anchor{--bzip2}
+../tar_texi/tar.texi(opsummary,2411) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2411)
+../tar_texi/tar.texi(,2412) @item --bzip2
+../tar_texi/tar.texi(,2413) @itemx -j
+../tar_texi/tar.texi(,2414)
+../tar_texi/tar.texi(,2415) This option tells @command{tar} to read or write
archives through
+../tar_texi/tar.texi(,2416) @code{bzip2}. @xref{gzip}.
+../tar_texi/tar.texi(,2417)
+../tar_texi/tar.texi(opsummary,2418) @anchor{--checkpoint}
+../tar_texi/tar.texi(opsummary,2418) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2418)
+../tar_texi/tar.texi(,2419) @item address@hidden
+../tar_texi/tar.texi(,2420)
+../tar_texi/tar.texi(,2421) This option directs @command{tar} to print
periodic checkpoint
+../tar_texi/tar.texi(,2422) messages as it reads through the archive. It is
intended for when you
+../tar_texi/tar.texi(,2423) want a visual indication that @command{tar} is
still running, but
+../tar_texi/tar.texi(,2424) don't want to see @option{--verbose} output. For
a detailed
+../tar_texi/tar.texi(,2425) description, see @ref{Progress information}.
+../tar_texi/tar.texi(,2426)
+../tar_texi/tar.texi(opsummary,2427) @anchor{--check-links}
+../tar_texi/tar.texi(opsummary,2427) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2427)
+../tar_texi/tar.texi(,2428) @item --check-links
+../tar_texi/tar.texi(,2429) @itemx -l
+../tar_texi/tar.texi(,2430) If this option was given, @command{tar} will check
the number of links
+../tar_texi/tar.texi(,2431) dumped for each processed file. If this number
does not match the
+../tar_texi/tar.texi(,2432) total number of hard links for the file, a warning
message will be
+../tar_texi/tar.texi(GNUTAR,2433) output @footnote{Earlier versions of
@acronym{GNU} @command{tar} understood @option{-l} as a
+../tar_texi/tar.texi(,2434) synonym for @option{--one-file-system}. The
current semantics, which
+../tar_texi/tar.texi(,2435) complies to UNIX98, was introduced with version
+../tar_texi/tar.texi(,2436) 1.15.91. @xref{Changes}, for more information.}.
+../tar_texi/tar.texi(,2437)
+../tar_texi/tar.texi(opsummary,2438) @anchor{--compress}
+../tar_texi/tar.texi(opsummary,2438) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2438)
+../tar_texi/tar.texi(opsummary,2439) @anchor{--uncompress}
+../tar_texi/tar.texi(opsummary,2439) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2439)
+../tar_texi/tar.texi(,2440) @item --compress
+../tar_texi/tar.texi(,2441) @itemx --uncompress
+../tar_texi/tar.texi(,2442) @itemx -Z
+../tar_texi/tar.texi(,2443)
+../tar_texi/tar.texi(,2444) @command{tar} will use the @command{compress}
program when reading or
+../tar_texi/tar.texi(,2445) writing the archive. This allows you to directly
act on archives
+../tar_texi/tar.texi(,2446) while saving space. @xref{gzip}.
+../tar_texi/tar.texi(,2447)
+../tar_texi/tar.texi(opsummary,2448) @anchor{--confirmation}
+../tar_texi/tar.texi(opsummary,2448) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2448)
+../tar_texi/tar.texi(,2449) @item --confirmation
+../tar_texi/tar.texi(,2450)
+../tar_texi/tar.texi(,2451) (See @option{--interactive}.) @xref{interactive}.
+../tar_texi/tar.texi(,2452)
+../tar_texi/tar.texi(opsummary,2453) @anchor{--delay-directory-restore}
+../tar_texi/tar.texi(opsummary,2453) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2453)
+../tar_texi/tar.texi(,2454) @item --delay-directory-restore
+../tar_texi/tar.texi(,2455)
+../tar_texi/tar.texi(,2456) Delay setting modification times and permissions
of extracted
+../tar_texi/tar.texi(,2457) directories until the end of extraction.
@xref{Directory Modification Times and Permissions}.
+../tar_texi/tar.texi(,2458)
+../tar_texi/tar.texi(opsummary,2459) @anchor{--dereference}
+../tar_texi/tar.texi(opsummary,2459) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2459)
+../tar_texi/tar.texi(,2460) @item --dereference
+../tar_texi/tar.texi(,2461) @itemx -h
+../tar_texi/tar.texi(,2462)
+../tar_texi/tar.texi(,2463) When creating a @command{tar} archive,
@command{tar} will archive the
+../tar_texi/tar.texi(,2464) file that a symbolic link points to, rather than
archiving the
+../tar_texi/tar.texi(,2465) symlink. @xref{dereference}.
+../tar_texi/tar.texi(,2466)
+../tar_texi/tar.texi(opsummary,2467) @anchor{--directory}
+../tar_texi/tar.texi(opsummary,2467) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2467)
+../tar_texi/tar.texi(,2468) @item address@hidden
+../tar_texi/tar.texi(,2469) @itemx -C @var{dir}
+../tar_texi/tar.texi(,2470)
+../tar_texi/tar.texi(,2471) When this option is specified, @command{tar} will
change its current directory
+../tar_texi/tar.texi(,2472) to @var{dir} before performing any operations.
When this option is used
+../tar_texi/tar.texi(,2473) during archive creation, it is order sensitive.
@xref{directory}.
+../tar_texi/tar.texi(,2474)
+../tar_texi/tar.texi(opsummary,2475) @anchor{--exclude}
+../tar_texi/tar.texi(opsummary,2475) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2475)
+../tar_texi/tar.texi(,2476) @item address@hidden
+../tar_texi/tar.texi(,2477)
+../tar_texi/tar.texi(,2478) When performing operations, @command{tar} will
skip files that match
+../tar_texi/tar.texi(,2479) @var{pattern}. @xref{exclude}.
+../tar_texi/tar.texi(,2480)
+../tar_texi/tar.texi(opsummary,2481) @anchor{--exclude-from}
+../tar_texi/tar.texi(opsummary,2481) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2481)
+../tar_texi/tar.texi(,2482) @item address@hidden
+../tar_texi/tar.texi(,2483) @itemx -X @var{file}
+../tar_texi/tar.texi(,2484)
+../tar_texi/tar.texi(,2485) Similar to @option{--exclude}, except
@command{tar} will use the list of
+../tar_texi/tar.texi(,2486) patterns in the file @var{file}. @xref{exclude}.
+../tar_texi/tar.texi(,2487)
+../tar_texi/tar.texi(opsummary,2488) @anchor{--exclude-caches}
+../tar_texi/tar.texi(opsummary,2488) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2488)
+../tar_texi/tar.texi(,2489) @item --exclude-caches
+../tar_texi/tar.texi(,2490)
+../tar_texi/tar.texi(,2491) Automatically excludes all directories
+../tar_texi/tar.texi(,2492) containing a cache directory tag. @xref{exclude}.
+../tar_texi/tar.texi(,2493)
+../tar_texi/tar.texi(opsummary,2494) @anchor{--file}
+../tar_texi/tar.texi(opsummary,2494) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2494)
+../tar_texi/tar.texi(,2495) @item address@hidden
+../tar_texi/tar.texi(,2496) @itemx -f @var{archive}
+../tar_texi/tar.texi(,2497)
+../tar_texi/tar.texi(,2498) @command{tar} will use the file @var{archive} as
the @command{tar} archive it
+../tar_texi/tar.texi(,2499) performs operations on, rather than
@command{tar}'s compilation dependent
+../tar_texi/tar.texi(,2500) default. @xref{file tutorial}.
+../tar_texi/tar.texi(,2501)
+../tar_texi/tar.texi(opsummary,2502) @anchor{--files-from}
+../tar_texi/tar.texi(opsummary,2502) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2502)
+../tar_texi/tar.texi(,2503) @item address@hidden
+../tar_texi/tar.texi(,2504) @itemx -T @var{file}
+../tar_texi/tar.texi(,2505)
+../tar_texi/tar.texi(,2506) @command{tar} will use the contents of @var{file}
as a list of archive members
+../tar_texi/tar.texi(,2507) or files to operate on, in addition to those
specified on the
+../tar_texi/tar.texi(,2508) command-line. @xref{files}.
+../tar_texi/tar.texi(,2509)
+../tar_texi/tar.texi(opsummary,2510) @anchor{--force-local}
+../tar_texi/tar.texi(opsummary,2510) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2510)
+../tar_texi/tar.texi(,2511) @item --force-local
+../tar_texi/tar.texi(,2512)
+../tar_texi/tar.texi(,2513) Forces @command{tar} to interpret the filename
given to @option{--file}
+../tar_texi/tar.texi(,2514) as a local file, even if it looks like a remote
tape drive name.
+../tar_texi/tar.texi(,2515) @xref{local and remote archives}.
+../tar_texi/tar.texi(,2516)
+../tar_texi/tar.texi(opsummary,2517) @anchor{--format}
+../tar_texi/tar.texi(opsummary,2517) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2517)
+../tar_texi/tar.texi(,2518) @item address@hidden
+../tar_texi/tar.texi(,2519) @itemx -H @var{format}
+../tar_texi/tar.texi(,2520)
+../tar_texi/tar.texi(,2521) Selects output archive format. @var{Format} may
be one of the
+../tar_texi/tar.texi(,2522) following:
+../tar_texi/tar.texi(,2523)
+../tar_texi/tar.texi(,2524) @table @samp
+../tar_texi/tar.texi(,2525) @item v7
+../tar_texi/tar.texi(,2526) Creates an archive that is compatible with Unix V7
@command{tar}.
+../tar_texi/tar.texi(,2527)
+../tar_texi/tar.texi(,2528) @item oldgnu
+../tar_texi/tar.texi(,2529) Creates an archive that is compatible with GNU
@command{tar} version
+../tar_texi/tar.texi(,2530) 1.12 or earlier.
+../tar_texi/tar.texi(,2531)
+../tar_texi/tar.texi(,2532) @item gnu
+../tar_texi/tar.texi(,2533) Creates archive in GNU tar 1.13 format. Basically
it is the same as
+../tar_texi/tar.texi(,2534) @samp{oldgnu} with the only difference in the way
it handles long
+../tar_texi/tar.texi(,2535) numeric fields.
+../tar_texi/tar.texi(,2536)
+../tar_texi/tar.texi(,2537) @item ustar
+../tar_texi/tar.texi(,2538) Creates a @acronym{POSIX.1-1988} compatible
archive.
+../tar_texi/tar.texi(,2539)
+../tar_texi/tar.texi(,2540) @item posix
+../tar_texi/tar.texi(,2541) Creates a @acronym{POSIX.1-2001 archive}.
+../tar_texi/tar.texi(,2542)
+../tar_texi/tar.texi(,2543) @end table
+../tar_texi/tar.texi(,2544)
+../tar_texi/tar.texi(,2545) @xref{Formats}, for a detailed discussion of these
formats.
+../tar_texi/tar.texi(,2546)
+../tar_texi/tar.texi(opsummary,2547) @anchor{--group}
+../tar_texi/tar.texi(opsummary,2547) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2547)
+../tar_texi/tar.texi(,2548) @item address@hidden
+../tar_texi/tar.texi(,2549)
+../tar_texi/tar.texi(,2550) Files added to the @command{tar} archive will have
a group id of @var{group},
+../tar_texi/tar.texi(,2551) rather than the group from the source file.
@var{group} is first decoded
+../tar_texi/tar.texi(,2552) as a group symbolic name, but if this
interpretation fails, it has to be
+../tar_texi/tar.texi(,2553) a decimal numeric group ID. @xref{override}.
+../tar_texi/tar.texi(,2554)
+../tar_texi/tar.texi(,2555) Also see the comments for the @address@hidden
option.
+../tar_texi/tar.texi(,2556)
+../tar_texi/tar.texi(opsummary,2557) @anchor{--gzip}
+../tar_texi/tar.texi(opsummary,2557) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2557)
+../tar_texi/tar.texi(opsummary,2558) @anchor{--gunzip}
+../tar_texi/tar.texi(opsummary,2558) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2558)
+../tar_texi/tar.texi(opsummary,2559) @anchor{--ungzip}
+../tar_texi/tar.texi(opsummary,2559) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2559)
+../tar_texi/tar.texi(,2560) @item --gzip
+../tar_texi/tar.texi(,2561) @itemx --gunzip
+../tar_texi/tar.texi(,2562) @itemx --ungzip
+../tar_texi/tar.texi(,2563) @itemx -z
+../tar_texi/tar.texi(,2564)
+../tar_texi/tar.texi(,2565) This option tells @command{tar} to read or write
archives through
+../tar_texi/tar.texi(,2566) @command{gzip}, allowing @command{tar} to directly
operate on several
+../tar_texi/tar.texi(,2567) kinds of compressed archives transparently.
@xref{gzip}.
+../tar_texi/tar.texi(,2568)
+../tar_texi/tar.texi(opsummary,2569) @anchor{--help}
+../tar_texi/tar.texi(opsummary,2569) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2569)
+../tar_texi/tar.texi(,2570) @item --help
+../tar_texi/tar.texi(,2571) @itemx -?
+../tar_texi/tar.texi(,2572)
+../tar_texi/tar.texi(,2573) @command{tar} will print out a short message
summarizing the operations and
+../tar_texi/tar.texi(,2574) options to @command{tar} and exit. @xref{help}.
+../tar_texi/tar.texi(,2575)
+../tar_texi/tar.texi(opsummary,2576) @anchor{--ignore-case}
+../tar_texi/tar.texi(opsummary,2576) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2576)
+../tar_texi/tar.texi(,2577) @item --ignore-case
+../tar_texi/tar.texi(,2578) Ignore case when matching member or file names with
+../tar_texi/tar.texi(,2579) patterns. @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2580)
+../tar_texi/tar.texi(opsummary,2581) @anchor{--ignore-command-error}
+../tar_texi/tar.texi(opsummary,2581) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2581)
+../tar_texi/tar.texi(,2582) @item --ignore-command-error
+../tar_texi/tar.texi(,2583) Ignore exit codes of subprocesses. @xref{Writing
to an External Program}.
+../tar_texi/tar.texi(,2584)
+../tar_texi/tar.texi(opsummary,2585) @anchor{--ignore-failed-read}
+../tar_texi/tar.texi(opsummary,2585) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2585)
+../tar_texi/tar.texi(,2586) @item --ignore-failed-read
+../tar_texi/tar.texi(,2587)
+../tar_texi/tar.texi(,2588) Do not exit unsuccessfully merely because an
unreadable file was encountered.
+../tar_texi/tar.texi(,2589) @xref{Reading}.
+../tar_texi/tar.texi(,2590)
+../tar_texi/tar.texi(opsummary,2591) @anchor{--ignore-zeros}
+../tar_texi/tar.texi(opsummary,2591) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2591)
+../tar_texi/tar.texi(,2592) @item --ignore-zeros
+../tar_texi/tar.texi(,2593) @itemx -i
+../tar_texi/tar.texi(,2594)
+../tar_texi/tar.texi(,2595) With this option, @command{tar} will ignore zeroed
blocks in the
+../tar_texi/tar.texi(,2596) archive, which normally signals EOF.
@xref{Reading}.
+../tar_texi/tar.texi(,2597)
+../tar_texi/tar.texi(opsummary,2598) @anchor{--incremental}
+../tar_texi/tar.texi(opsummary,2598) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2598)
+../tar_texi/tar.texi(,2599) @item --incremental
+../tar_texi/tar.texi(,2600) @itemx -G
+../tar_texi/tar.texi(,2601)
+../tar_texi/tar.texi(,2602) Used to inform @command{tar} that it is working
with an old
+../tar_texi/tar.texi(,2603) @acronym{GNU}-format incremental backup archive.
It is intended
+../tar_texi/tar.texi(,2604) primarily for backwards compatibility only.
@xref{Incremental Dumps},
+../tar_texi/tar.texi(,2605) for a detailed discussion of incremental archives.
+../tar_texi/tar.texi(,2606)
+../tar_texi/tar.texi(opsummary,2607) @anchor{--index-file}
+../tar_texi/tar.texi(opsummary,2607) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2607)
+../tar_texi/tar.texi(,2608) @item address@hidden
+../tar_texi/tar.texi(,2609)
+../tar_texi/tar.texi(,2610) Send verbose output to @var{file} instead of to
standard output.
+../tar_texi/tar.texi(,2611)
+../tar_texi/tar.texi(opsummary,2612) @anchor{--info-script}
+../tar_texi/tar.texi(opsummary,2612) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2612)
+../tar_texi/tar.texi(opsummary,2613) @anchor{--new-volume-script}
+../tar_texi/tar.texi(opsummary,2613) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2613)
+../tar_texi/tar.texi(,2614) @item address@hidden
+../tar_texi/tar.texi(,2615) @itemx address@hidden
+../tar_texi/tar.texi(,2616) @itemx -F @var{script-file}
+../tar_texi/tar.texi(,2617)
+../tar_texi/tar.texi(,2618) When @command{tar} is performing multi-tape
backups, @var{script-file} is run
+../tar_texi/tar.texi(,2619) at the end of each tape. If @var{script-file}
exits with nonzero status,
+../tar_texi/tar.texi(,2620) @command{tar} fails immediately.
@xref{info-script}, for a detailed
+../tar_texi/tar.texi(,2621) discussion of @var{script-file}.
+../tar_texi/tar.texi(,2622)
+../tar_texi/tar.texi(opsummary,2623) @anchor{--interactive}
+../tar_texi/tar.texi(opsummary,2623) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2623)
+../tar_texi/tar.texi(,2624) @item --interactive
+../tar_texi/tar.texi(,2625) @itemx --confirmation
+../tar_texi/tar.texi(,2626) @itemx -w
+../tar_texi/tar.texi(,2627)
+../tar_texi/tar.texi(,2628) Specifies that @command{tar} should ask the user
for confirmation before
+../tar_texi/tar.texi(,2629) performing potentially destructive options, such
as overwriting files.
+../tar_texi/tar.texi(,2630) @xref{interactive}.
+../tar_texi/tar.texi(,2631)
+../tar_texi/tar.texi(opsummary,2632) @anchor{--keep-newer-files}
+../tar_texi/tar.texi(opsummary,2632) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2632)
+../tar_texi/tar.texi(,2633) @item --keep-newer-files
+../tar_texi/tar.texi(,2634)
+../tar_texi/tar.texi(,2635) Do not replace existing files that are newer than
their archive copies
+../tar_texi/tar.texi(,2636) when extracting files from an archive.
+../tar_texi/tar.texi(,2637)
+../tar_texi/tar.texi(opsummary,2638) @anchor{--keep-old-files}
+../tar_texi/tar.texi(opsummary,2638) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2638)
+../tar_texi/tar.texi(,2639) @item --keep-old-files
+../tar_texi/tar.texi(,2640) @itemx -k
+../tar_texi/tar.texi(,2641)
+../tar_texi/tar.texi(,2642) Do not overwrite existing files when extracting
files from an archive.
+../tar_texi/tar.texi(,2643) @xref{Keep Old Files}.
+../tar_texi/tar.texi(,2644)
+../tar_texi/tar.texi(opsummary,2645) @anchor{--label}
+../tar_texi/tar.texi(opsummary,2645) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2645)
+../tar_texi/tar.texi(,2646) @item address@hidden
+../tar_texi/tar.texi(,2647) @itemx -V @var{name}
+../tar_texi/tar.texi(,2648)
+../tar_texi/tar.texi(,2649) When creating an archive, instructs @command{tar}
to write @var{name}
+../tar_texi/tar.texi(,2650) as a name record in the archive. When extracting
or listing archives,
+../tar_texi/tar.texi(,2651) @command{tar} will only operate on archives that
have a label matching
+../tar_texi/tar.texi(,2652) the pattern specified in @var{name}. @xref{Tape
Files}.
+../tar_texi/tar.texi(,2653)
+../tar_texi/tar.texi(opsummary,2654) @anchor{--listed-incremental}
+../tar_texi/tar.texi(opsummary,2654) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2654)
+../tar_texi/tar.texi(,2655) @item address@hidden
+../tar_texi/tar.texi(,2656) @itemx -g @var{snapshot-file}
+../tar_texi/tar.texi(,2657)
+../tar_texi/tar.texi(,2658) During a @option{--create} operation, specifies
that the archive that
+../tar_texi/tar.texi(,2659) @command{tar} creates is a new
@acronym{GNU}-format incremental
+../tar_texi/tar.texi(,2660) backup, using @var{snapshot-file} to determine
which files to backup.
+../tar_texi/tar.texi(,2661) With other operations, informs @command{tar} that
the archive is in
+../tar_texi/tar.texi(,2662) incremental format. @xref{Incremental Dumps}.
+../tar_texi/tar.texi(,2663)
+../tar_texi/tar.texi(opsummary,2664) @anchor{--mode}
+../tar_texi/tar.texi(opsummary,2664) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2664)
+../tar_texi/tar.texi(,2665) @item address@hidden
+../tar_texi/tar.texi(,2666)
+../tar_texi/tar.texi(,2667) When adding files to an archive, @command{tar}
will use
+../tar_texi/tar.texi(,2668) @var{permissions} for the archive members, rather
than the permissions
+../tar_texi/tar.texi(,2669) from the files. @var{permissions} can be
specified either as an octal
+../tar_texi/tar.texi(,2670) number or as symbolic permissions, like with
+../tar_texi/tar.texi(,2671) @command{chmod}. @xref{override}.
+../tar_texi/tar.texi(,2672)
+../tar_texi/tar.texi(opsummary,2673) @anchor{--mtime}
+../tar_texi/tar.texi(opsummary,2673) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2673)
+../tar_texi/tar.texi(,2674) @item address@hidden
+../tar_texi/tar.texi(,2675)
+../tar_texi/tar.texi(,2676) When adding files to an archive, @command{tar}
will use @var{date} as
+../tar_texi/tar.texi(,2677) the modification time of members when creating
archives, instead of
+../tar_texi/tar.texi(,2678) their actual modification times. The value of
@var{date} can be
+../tar_texi/tar.texi(,2679) either a textual date representation (@pxref{Date
input formats}) or a
+../tar_texi/tar.texi(,2680) name of the existing file, starting with @samp{/}
or @samp{.}. In the
+../tar_texi/tar.texi(,2681) latter case, the modification time of that file is
used. @xref{override}.
+../tar_texi/tar.texi(,2682)
+../tar_texi/tar.texi(opsummary,2683) @anchor{--multi-volume}
+../tar_texi/tar.texi(opsummary,2683) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2683)
+../tar_texi/tar.texi(,2684) @item --multi-volume
+../tar_texi/tar.texi(,2685) @itemx -M
+../tar_texi/tar.texi(,2686)
+../tar_texi/tar.texi(,2687) Informs @command{tar} that it should create or
otherwise operate on a
+../tar_texi/tar.texi(,2688) multi-volume @command{tar} archive. @xref{Using
Multiple Tapes}.
+../tar_texi/tar.texi(,2689)
+../tar_texi/tar.texi(opsummary,2690) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2690)
+../tar_texi/tar.texi(,2691) @item --new-volume-script
+../tar_texi/tar.texi(,2692)
+../tar_texi/tar.texi(,2693) (see --info-script)
+../tar_texi/tar.texi(,2694)
+../tar_texi/tar.texi(opsummary,2695) @anchor{--seek}
+../tar_texi/tar.texi(opsummary,2695) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2695)
+../tar_texi/tar.texi(,2696) @item --seek
+../tar_texi/tar.texi(,2697) @itemx -n
+../tar_texi/tar.texi(,2698)
+../tar_texi/tar.texi(,2699) Assume that the archive media supports seeks to
arbitrary
+../tar_texi/tar.texi(,2700) locations. Usually @command{tar} determines
automatically whether
+../tar_texi/tar.texi(,2701) the archive can be seeked or not. This option is
intended for use
+../tar_texi/tar.texi(,2702) in cases when such recognition fails.
+../tar_texi/tar.texi(,2703)
+../tar_texi/tar.texi(opsummary,2704) @anchor{--newer}
+../tar_texi/tar.texi(opsummary,2704) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2704)
+../tar_texi/tar.texi(,2705) @item address@hidden
+../tar_texi/tar.texi(,2706) @itemx address@hidden
+../tar_texi/tar.texi(,2707) @itemx -N
+../tar_texi/tar.texi(,2708)
+../tar_texi/tar.texi(,2709) When creating an archive, @command{tar} will only
add files that have changed
+../tar_texi/tar.texi(,2710) since @var{date}. If @var{date} begins with
@samp{/} or @samp{.}, it
+../tar_texi/tar.texi(,2711) is taken to be the name of a file whose data
modification time specifies
+../tar_texi/tar.texi(,2712) the date. @xref{after}.
+../tar_texi/tar.texi(,2713)
+../tar_texi/tar.texi(opsummary,2714) @anchor{--newer-mtime}
+../tar_texi/tar.texi(opsummary,2714) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2714)
+../tar_texi/tar.texi(,2715) @item address@hidden
+../tar_texi/tar.texi(,2716)
+../tar_texi/tar.texi(,2717) Like @option{--newer}, but add only files whose
+../tar_texi/tar.texi(,2718) contents have changed (as opposed to just
@option{--newer}, which will
+../tar_texi/tar.texi(,2719) also back up files for which any status
information has
+../tar_texi/tar.texi(,2720) changed). @xref{after}.
+../tar_texi/tar.texi(,2721)
+../tar_texi/tar.texi(opsummary,2722) @anchor{--no-anchored}
+../tar_texi/tar.texi(opsummary,2722) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2722)
+../tar_texi/tar.texi(,2723) @item --no-anchored
+../tar_texi/tar.texi(,2724) An exclude pattern can match any subsequence of
the name's components.
+../tar_texi/tar.texi(,2725) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2726)
+../tar_texi/tar.texi(opsummary,2727) @anchor{--no-delay-directory-restore}
+../tar_texi/tar.texi(opsummary,2727) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2727)
+../tar_texi/tar.texi(,2728) @item --no-delay-directory-restore
+../tar_texi/tar.texi(,2729)
+../tar_texi/tar.texi(,2730) Setting modification times and permissions of
extracted
+../tar_texi/tar.texi(,2731) directories when all files from this directory has
been
+../tar_texi/tar.texi(,2732) extracted. This is the default. @xref{Directory
Modification Times and Permissions}.
+../tar_texi/tar.texi(,2733)
+../tar_texi/tar.texi(opsummary,2734) @anchor{--no-ignore-case}
+../tar_texi/tar.texi(opsummary,2734) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2734)
+../tar_texi/tar.texi(,2735) @item --no-ignore-case
+../tar_texi/tar.texi(,2736) Use case-sensitive matching.
+../tar_texi/tar.texi(,2737) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2738)
+../tar_texi/tar.texi(opsummary,2739) @anchor{--no-ignore-command-error}
+../tar_texi/tar.texi(opsummary,2739) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2739)
+../tar_texi/tar.texi(,2740) @item --no-ignore-command-error
+../tar_texi/tar.texi(,2741) Print warnings about subprocesses terminated with
a non-zero exit
+../tar_texi/tar.texi(,2742) code. @xref{Writing to an External Program}.
+../tar_texi/tar.texi(,2743)
+../tar_texi/tar.texi(opsummary,2744) @anchor{--no-overwrite-dir}
+../tar_texi/tar.texi(opsummary,2744) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2744)
+../tar_texi/tar.texi(,2745) @item --no-overwrite-dir
+../tar_texi/tar.texi(,2746)
+../tar_texi/tar.texi(,2747) Preserve metadata of existing directories when
extracting files
+../tar_texi/tar.texi(,2748) from an archive. @xref{Overwrite Old Files}.
+../tar_texi/tar.texi(,2749)
+../tar_texi/tar.texi(opsummary,2750) @anchor{--no-quote-chars}
+../tar_texi/tar.texi(opsummary,2750) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2750)
+../tar_texi/tar.texi(,2751) @item address@hidden
+../tar_texi/tar.texi(,2752) Remove characters listed in @var{string} from the
list of quoted
+../tar_texi/tar.texi(,2753) characters set by the previous
@option{--quote-chars} option
+../tar_texi/tar.texi(,2754) (@pxref{quoting styles}).
+../tar_texi/tar.texi(,2755)
+../tar_texi/tar.texi(opsummary,2756) @anchor{--no-recursion}
+../tar_texi/tar.texi(opsummary,2756) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2756)
+../tar_texi/tar.texi(,2757) @item --no-recursion
+../tar_texi/tar.texi(,2758)
+../tar_texi/tar.texi(,2759) With this option, @command{tar} will not recurse
into directories.
+../tar_texi/tar.texi(,2760) @xref{recurse}.
+../tar_texi/tar.texi(,2761)
+../tar_texi/tar.texi(opsummary,2762) @anchor{--no-same-owner}
+../tar_texi/tar.texi(opsummary,2762) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2762)
+../tar_texi/tar.texi(,2763) @item --no-same-owner
+../tar_texi/tar.texi(,2764) @itemx -o
+../tar_texi/tar.texi(,2765)
+../tar_texi/tar.texi(,2766) When extracting an archive, do not attempt to
preserve the owner
+../tar_texi/tar.texi(,2767) specified in the @command{tar} archive. This the
default behavior
+../tar_texi/tar.texi(,2768) for ordinary users.
+../tar_texi/tar.texi(,2769)
+../tar_texi/tar.texi(opsummary,2770) @anchor{--no-same-permissions}
+../tar_texi/tar.texi(opsummary,2770) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2770)
+../tar_texi/tar.texi(,2771) @item --no-same-permissions
+../tar_texi/tar.texi(,2772)
+../tar_texi/tar.texi(,2773) When extracting an archive, subtract the user's
umask from files from
+../tar_texi/tar.texi(,2774) the permissions specified in the archive. This is
the default behavior
+../tar_texi/tar.texi(,2775) for ordinary users.
+../tar_texi/tar.texi(,2776)
+../tar_texi/tar.texi(opsummary,2777) @anchor{--no-unquote}
+../tar_texi/tar.texi(opsummary,2777) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2777)
+../tar_texi/tar.texi(,2778) @item --no-unquote
+../tar_texi/tar.texi(,2779) Treat all input file or member names literally, do
not interpret
+../tar_texi/tar.texi(,2780) escape sequences. @xref{input name quoting}.
+../tar_texi/tar.texi(,2781)
+../tar_texi/tar.texi(opsummary,2782) @anchor{--no-wildcards}
+../tar_texi/tar.texi(opsummary,2782) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2782)
+../tar_texi/tar.texi(,2783) @item --no-wildcards
+../tar_texi/tar.texi(,2784) Do not use wildcards.
+../tar_texi/tar.texi(,2785) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2786)
+../tar_texi/tar.texi(opsummary,2787) @anchor{--no-wildcards-match-slash}
+../tar_texi/tar.texi(opsummary,2787) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2787)
+../tar_texi/tar.texi(,2788) @item --no-wildcards-match-slash
+../tar_texi/tar.texi(,2789) Wildcards do not match @samp{/}.
+../tar_texi/tar.texi(,2790) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,2791)
+../tar_texi/tar.texi(opsummary,2792) @anchor{--null}
+../tar_texi/tar.texi(opsummary,2792) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2792)
+../tar_texi/tar.texi(,2793) @item --null
+../tar_texi/tar.texi(,2794)
+../tar_texi/tar.texi(,2795) When @command{tar} is using the
@option{--files-from} option, this option
+../tar_texi/tar.texi(,2796) instructs @command{tar} to expect filenames
terminated with @option{NUL}, so
+../tar_texi/tar.texi(,2797) @command{tar} can correctly work with file names
that contain newlines.
+../tar_texi/tar.texi(,2798) @xref{nul}.
+../tar_texi/tar.texi(,2799)
+../tar_texi/tar.texi(opsummary,2800) @anchor{--numeric-owner}
+../tar_texi/tar.texi(opsummary,2800) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2800)
+../tar_texi/tar.texi(,2801) @item --numeric-owner
+../tar_texi/tar.texi(,2802)
+../tar_texi/tar.texi(,2803) This option will notify @command{tar} that it
should use numeric user
+../tar_texi/tar.texi(,2804) and group IDs when creating a @command{tar} file,
rather than names.
+../tar_texi/tar.texi(,2805) @xref{Attributes}.
+../tar_texi/tar.texi(,2806)
+../tar_texi/tar.texi(,2807) @item -o
+../tar_texi/tar.texi(,2808) The function of this option depends on the action
@command{tar} is
+../tar_texi/tar.texi(,2809) performing. When extracting files, @option{-o} is
a synonym for
+../tar_texi/tar.texi(,2810) @option{--no-same-owner}, i.e. it prevents
@command{tar} from
+../tar_texi/tar.texi(,2811) restoring ownership of files being extracted.
+../tar_texi/tar.texi(,2812)
+../tar_texi/tar.texi(,2813) When creating an archive, it is a synonym for
+../tar_texi/tar.texi(,2814) @option{--old-archive}. This behavior is for
compatibility
+../tar_texi/tar.texi(GNUTAR,2815) with previous versions of
../tar_texi/tar.texi(GNUTAR,2815) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,2815) , and will be
+../tar_texi/tar.texi(,2816) removed in the future releases.
+../tar_texi/tar.texi(,2817)
+../tar_texi/tar.texi(,2818) @xref{Changes}, for more information.
+../tar_texi/tar.texi(,2819)
+../tar_texi/tar.texi(opsummary,2820) @anchor{--occurrence}
+../tar_texi/tar.texi(opsummary,2820) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2820)
+../tar_texi/tar.texi(,2821) @item address@hidden
+../tar_texi/tar.texi(,2822)
+../tar_texi/tar.texi(,2823) This option can be used in conjunction with one of
the subcommands
+../tar_texi/tar.texi(,2824) @option{--delete}, @option{--diff},
@option{--extract} or
+../tar_texi/tar.texi(,2825) @option{--list} when a list of files is given
either on the command
+../tar_texi/tar.texi(,2826) line or via @option{-T} option.
+../tar_texi/tar.texi(,2827)
+../tar_texi/tar.texi(,2828) This option instructs @command{tar} to process
only the @var{number}th
+../tar_texi/tar.texi(,2829) occurrence of each named file. @var{Number}
defaults to 1, so
+../tar_texi/tar.texi(,2830)
+../tar_texi/tar.texi(,2831) @smallexample
+../tar_texi/tar.texi(,2832) tar -x -f archive.tar --occurrence filename
+../tar_texi/tar.texi(,2833) @end smallexample
+../tar_texi/tar.texi(,2834)
+../tar_texi/tar.texi(,2835) @noindent
+../tar_texi/tar.texi(,2836) will extract the first occurrence of the member
@file{filename} from @file{archive.tar}
+../tar_texi/tar.texi(,2837) and will terminate without scanning to the end of
the archive.
+../tar_texi/tar.texi(,2838)
+../tar_texi/tar.texi(opsummary,2839) @anchor{--old-archive}
+../tar_texi/tar.texi(opsummary,2839) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2839)
+../tar_texi/tar.texi(,2840) @item --old-archive
+../tar_texi/tar.texi(,2841) Synonym for @option{--format=v7}.
+../tar_texi/tar.texi(,2842)
+../tar_texi/tar.texi(opsummary,2843) @anchor{--one-file-system}
+../tar_texi/tar.texi(opsummary,2843) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2843)
+../tar_texi/tar.texi(,2844) @item --one-file-system
+../tar_texi/tar.texi(,2845) Used when creating an archive. Prevents
@command{tar} from recursing into
+../tar_texi/tar.texi(,2846) directories that are on different file systems
from the current
+../tar_texi/tar.texi(GNUTAR,2847) directory @footnote{Earlier versions of
@acronym{GNU} @command{tar} understood @option{-l} as a
+../tar_texi/tar.texi(,2848) synonym for @option{--one-file-system}. This has
changed in version
+../tar_texi/tar.texi(,2849) 1.15.91. @xref{Changes}, for more information.}.
+../tar_texi/tar.texi(,2850)
+../tar_texi/tar.texi(opsummary,2851) @anchor{--overwrite}
+../tar_texi/tar.texi(opsummary,2851) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2851)
+../tar_texi/tar.texi(,2852) @item --overwrite
+../tar_texi/tar.texi(,2853)
+../tar_texi/tar.texi(,2854) Overwrite existing files and directory metadata
when extracting files
+../tar_texi/tar.texi(,2855) from an archive. @xref{Overwrite Old Files}.
+../tar_texi/tar.texi(,2856)
+../tar_texi/tar.texi(opsummary,2857) @anchor{--overwrite-dir}
+../tar_texi/tar.texi(opsummary,2857) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2857)
+../tar_texi/tar.texi(,2858) @item --overwrite-dir
+../tar_texi/tar.texi(,2859)
+../tar_texi/tar.texi(,2860) Overwrite the metadata of existing directories
when extracting files
+../tar_texi/tar.texi(,2861) from an archive. @xref{Overwrite Old Files}.
+../tar_texi/tar.texi(,2862)
+../tar_texi/tar.texi(opsummary,2863) @anchor{--owner}
+../tar_texi/tar.texi(opsummary,2863) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2863)
+../tar_texi/tar.texi(,2864) @item address@hidden
+../tar_texi/tar.texi(,2865)
+../tar_texi/tar.texi(,2866) Specifies that @command{tar} should use @var{user}
as the owner of members
+../tar_texi/tar.texi(,2867) when creating archives, instead of the user
associated with the source
+../tar_texi/tar.texi(,2868) file. @var{user} is first decoded as a user
symbolic name, but if
+../tar_texi/tar.texi(,2869) this interpretation fails, it has to be a decimal
numeric user ID.
+../tar_texi/tar.texi(,2870) @xref{override}.
+../tar_texi/tar.texi(,2871)
+../tar_texi/tar.texi(,2872) This option does not affect extraction from
archives.
+../tar_texi/tar.texi(,2873)
+../tar_texi/tar.texi(opsummary,2874) @anchor{--transform}
+../tar_texi/tar.texi(opsummary,2874) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2874)
+../tar_texi/tar.texi(,2875) @item address@hidden
+../tar_texi/tar.texi(,2876)
+../tar_texi/tar.texi(,2877) Transform file or member names using @command{sed}
replacement expression
+../tar_texi/tar.texi(,2878) @var{sed-expr}. For example,
+../tar_texi/tar.texi(,2879)
+../tar_texi/tar.texi(,2880) @smallexample
+../tar_texi/tar.texi(,2881) $ @kbd{tar cf archive.tar --transform
's,^\./,usr/,' .}
+../tar_texi/tar.texi(,2882) @end smallexample
+../tar_texi/tar.texi(,2883)
+../tar_texi/tar.texi(,2884) @noindent
+../tar_texi/tar.texi(,2885) will add to @file{archive} files from the current
working directory,
+../tar_texi/tar.texi(,2886) replacing initial @samp{./} prefix with
@samp{usr/}. For the detailed
+../tar_texi/tar.texi(,2887) discussion, @xref{transform}.
+../tar_texi/tar.texi(,2888)
+../tar_texi/tar.texi(,2889) To see transformed member names in verbose
listings, use
+../tar_texi/tar.texi(,2890) @option{--show-transformed-names} option
+../tar_texi/tar.texi(,2891) (@pxref{show-transformed-names}).
+../tar_texi/tar.texi(,2892)
+../tar_texi/tar.texi(opsummary,2893) @anchor{--quote-chars}
+../tar_texi/tar.texi(opsummary,2893) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2893)
+../tar_texi/tar.texi(,2894) @item address@hidden
+../tar_texi/tar.texi(,2895) Always quote characters from @var{string}, even if
the selected
+../tar_texi/tar.texi(,2896) quoting style would not quote them (@pxref{quoting
styles}).
+../tar_texi/tar.texi(,2897)
+../tar_texi/tar.texi(opsummary,2898) @anchor{--quoting-style}
+../tar_texi/tar.texi(opsummary,2898) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2898)
+../tar_texi/tar.texi(,2899) @item address@hidden
+../tar_texi/tar.texi(,2900) Set quoting style to use when printing member and
file names
+../tar_texi/tar.texi(,2901) (@pxref{quoting styles}). Valid @var{style} values
are:
+../tar_texi/tar.texi(,2902) @code{literal}, @code{shell}, @code{shell-always},
@code{c},
+../tar_texi/tar.texi(,2903) @code{escape}, @code{locale}, and @code{clocale}.
Default quoting
+../tar_texi/tar.texi(,2904) style is @code{escape}, unless overridden while
configuring the
+../tar_texi/tar.texi(,2905) package.
+../tar_texi/tar.texi(,2906)
+../tar_texi/tar.texi(opsummary,2907) @anchor{--pax-option}
+../tar_texi/tar.texi(opsummary,2907) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2907)
+../tar_texi/tar.texi(,2908) @item address@hidden
+../tar_texi/tar.texi(,2909) This option is meaningful only with
@acronym{POSIX.1-2001} archives
+../tar_texi/tar.texi(,2910) (@pxref{posix}). It modifies the way
@command{tar} handles the
+../tar_texi/tar.texi(,2911) extended header keywords. @var{Keyword-list} is a
comma-separated
+../tar_texi/tar.texi(,2912) list of keyword options. @xref{PAX keywords}, for
a detailed
+../tar_texi/tar.texi(,2913) discussion.
+../tar_texi/tar.texi(,2914)
+../tar_texi/tar.texi(opsummary,2915) @anchor{--portability}
+../tar_texi/tar.texi(opsummary,2915) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2915)
+../tar_texi/tar.texi(,2916) @item --portability
+../tar_texi/tar.texi(,2917) @itemx --old-archive
+../tar_texi/tar.texi(,2918) Synonym for @option{--format=v7}.
+../tar_texi/tar.texi(,2919)
+../tar_texi/tar.texi(opsummary,2920) @anchor{--posix}
+../tar_texi/tar.texi(opsummary,2920) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2920)
+../tar_texi/tar.texi(,2921) @item --posix
+../tar_texi/tar.texi(,2922) Same as @option{--format=posix}.
+../tar_texi/tar.texi(,2923)
+../tar_texi/tar.texi(opsummary,2924) @anchor{--preserve}
+../tar_texi/tar.texi(opsummary,2924) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2924)
+../tar_texi/tar.texi(,2925) @item --preserve
+../tar_texi/tar.texi(,2926)
+../tar_texi/tar.texi(,2927) Synonymous with specifying both
@option{--preserve-permissions} and
+../tar_texi/tar.texi(,2928) @option{--same-order}. @xref{Setting Access
Permissions}.
+../tar_texi/tar.texi(,2929)
+../tar_texi/tar.texi(opsummary,2930) @anchor{--preserve-order}
+../tar_texi/tar.texi(opsummary,2930) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2930)
+../tar_texi/tar.texi(,2931) @item --preserve-order
+../tar_texi/tar.texi(,2932)
+../tar_texi/tar.texi(,2933) (See @option{--same-order}; @pxref{Reading}.)
+../tar_texi/tar.texi(,2934)
+../tar_texi/tar.texi(opsummary,2935) @anchor{--preserve-permissions}
+../tar_texi/tar.texi(opsummary,2935) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2935)
+../tar_texi/tar.texi(opsummary,2936) @anchor{--same-permissions}
+../tar_texi/tar.texi(opsummary,2936) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2936)
+../tar_texi/tar.texi(,2937) @item --preserve-permissions
+../tar_texi/tar.texi(,2938) @itemx --same-permissions
+../tar_texi/tar.texi(,2939) @itemx -p
+../tar_texi/tar.texi(,2940)
+../tar_texi/tar.texi(,2941) When @command{tar} is extracting an archive, it
normally subtracts the
+../tar_texi/tar.texi(,2942) users' umask from the permissions specified in the
archive and uses
+../tar_texi/tar.texi(,2943) that number as the permissions to create the
destination file.
+../tar_texi/tar.texi(,2944) Specifying this option instructs @command{tar}
that it should use the
+../tar_texi/tar.texi(,2945) permissions directly from the archive.
@xref{Setting Access Permissions}.
+../tar_texi/tar.texi(,2946)
+../tar_texi/tar.texi(opsummary,2947) @anchor{--read-full-records}
+../tar_texi/tar.texi(opsummary,2947) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2947)
+../tar_texi/tar.texi(,2948) @item --read-full-records
+../tar_texi/tar.texi(,2949) @itemx -B
+../tar_texi/tar.texi(,2950)
+../tar_texi/tar.texi(,2951) Specifies that @command{tar} should reblock its
input, for reading
+../tar_texi/tar.texi(,2952) from pipes on systems with buggy implementations.
@xref{Reading}.
+../tar_texi/tar.texi(,2953)
+../tar_texi/tar.texi(opsummary,2954) @anchor{--record-size}
+../tar_texi/tar.texi(opsummary,2954) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2954)
+../tar_texi/tar.texi(,2955) @item address@hidden
+../tar_texi/tar.texi(,2956)
+../tar_texi/tar.texi(,2957) Instructs @command{tar} to use @var{size} bytes
per record when accessing the
+../tar_texi/tar.texi(,2958) archive. @xref{Blocking Factor}.
+../tar_texi/tar.texi(,2959)
+../tar_texi/tar.texi(opsummary,2960) @anchor{--recursion}
+../tar_texi/tar.texi(opsummary,2960) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2960)
+../tar_texi/tar.texi(,2961) @item --recursion
+../tar_texi/tar.texi(,2962)
+../tar_texi/tar.texi(,2963) With this option, @command{tar} recurses into
directories.
+../tar_texi/tar.texi(,2964) @xref{recurse}.
+../tar_texi/tar.texi(,2965)
+../tar_texi/tar.texi(opsummary,2966) @anchor{--recursive-unlink}
+../tar_texi/tar.texi(opsummary,2966) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2966)
+../tar_texi/tar.texi(,2967) @item --recursive-unlink
+../tar_texi/tar.texi(,2968)
+../tar_texi/tar.texi(,2969) Remove existing
+../tar_texi/tar.texi(,2970) directory hierarchies before extracting
directories of the same name
+../tar_texi/tar.texi(,2971) from the archive. @xref{Recursive Unlink}.
+../tar_texi/tar.texi(,2972)
+../tar_texi/tar.texi(opsummary,2973) @anchor{--remove-files}
+../tar_texi/tar.texi(opsummary,2973) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2973)
+../tar_texi/tar.texi(,2974) @item --remove-files
+../tar_texi/tar.texi(,2975)
+../tar_texi/tar.texi(,2976) Directs @command{tar} to remove the source file
from the file system after
+../tar_texi/tar.texi(,2977) appending it to an archive. @xref{remove files}.
+../tar_texi/tar.texi(,2978)
+../tar_texi/tar.texi(opsummary,2979) @anchor{--restrict}
+../tar_texi/tar.texi(opsummary,2979) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2979)
+../tar_texi/tar.texi(,2980) @item --restrict
+../tar_texi/tar.texi(,2981)
+../tar_texi/tar.texi(,2982) Disable use of some potentially harmful
@command{tar} options.
+../tar_texi/tar.texi(,2983) Currently this option disables shell invocaton
from multi-volume menu
+../tar_texi/tar.texi(,2984) (@pxref{Using Multiple Tapes}).
+../tar_texi/tar.texi(,2985)
+../tar_texi/tar.texi(opsummary,2986) @anchor{--rmt-command}
+../tar_texi/tar.texi(opsummary,2986) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2986)
+../tar_texi/tar.texi(,2987) @item address@hidden
+../tar_texi/tar.texi(,2988)
+../tar_texi/tar.texi(,2989) Notifies @command{tar} that it should use
@var{cmd} instead of
+../tar_texi/tar.texi(,2990) the default @file{/usr/libexec/rmt} (@pxref{Remote
Tape Server}).
+../tar_texi/tar.texi(,2991)
+../tar_texi/tar.texi(opsummary,2992) @anchor{--rsh-command}
+../tar_texi/tar.texi(opsummary,2992) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2992)
+../tar_texi/tar.texi(,2993) @item address@hidden
+../tar_texi/tar.texi(,2994)
+../tar_texi/tar.texi(,2995) Notifies @command{tar} that is should use
@var{cmd} to communicate with remote
+../tar_texi/tar.texi(,2996) devices. @xref{Device}.
+../tar_texi/tar.texi(,2997)
+../tar_texi/tar.texi(opsummary,2998) @anchor{--same-order}
+../tar_texi/tar.texi(opsummary,2998) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,2998)
+../tar_texi/tar.texi(,2999) @item --same-order
+../tar_texi/tar.texi(,3000) @itemx --preserve-order
+../tar_texi/tar.texi(,3001) @itemx -s
+../tar_texi/tar.texi(,3002)
+../tar_texi/tar.texi(,3003) This option is an optimization for @command{tar}
when running on machines with
+../tar_texi/tar.texi(,3004) small amounts of memory. It informs @command{tar}
that the list of file
+../tar_texi/tar.texi(,3005) arguments has already been sorted to match the
order of files in the
+../tar_texi/tar.texi(,3006) archive. @xref{Reading}.
+../tar_texi/tar.texi(,3007)
+../tar_texi/tar.texi(opsummary,3008) @anchor{--same-owner}
+../tar_texi/tar.texi(opsummary,3008) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3008)
+../tar_texi/tar.texi(,3009) @item --same-owner
+../tar_texi/tar.texi(,3010)
+../tar_texi/tar.texi(,3011) When extracting an archive, @command{tar} will
attempt to preserve the owner
+../tar_texi/tar.texi(,3012) specified in the @command{tar} archive with this
option present.
+../tar_texi/tar.texi(,3013) This is the default behavior for the superuser;
this option has an
+../tar_texi/tar.texi(,3014) effect only for ordinary users. @xref{Attributes}.
+../tar_texi/tar.texi(,3015)
+../tar_texi/tar.texi(opsummary,3016) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3016)
+../tar_texi/tar.texi(,3017) @item --same-permissions
+../tar_texi/tar.texi(,3018)
+../tar_texi/tar.texi(,3019) (See @option{--preserve-permissions};
@pxref{Setting Access Permissions}.)
+../tar_texi/tar.texi(,3020)
+../tar_texi/tar.texi(opsummary,3021) @anchor{--show-defaults}
+../tar_texi/tar.texi(opsummary,3021) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3021)
+../tar_texi/tar.texi(,3022) @item --show-defaults
+../tar_texi/tar.texi(,3023)
+../tar_texi/tar.texi(,3024) Displays the default options used by @command{tar}
and exits
+../tar_texi/tar.texi(,3025) successfully. This option is intended for use in
shell scripts.
+../tar_texi/tar.texi(,3026) Here is an example of what you can see using this
option:
+../tar_texi/tar.texi(,3027)
+../tar_texi/tar.texi(,3028) @smallexample
+../tar_texi/tar.texi(,3029) $ tar --show-defaults
+../tar_texi/tar.texi(,3030) --format=gnu -f- -b20 --quoting-style=escape \
+../tar_texi/tar.texi(,3031) --rmt-command=/usr/libexec/rmt
--rsh-command=/usr/bin/rsh
+../tar_texi/tar.texi(,3032) @end smallexample
+../tar_texi/tar.texi(,3033)
+../tar_texi/tar.texi(opsummary,3034) @anchor{--show-omitted-dirs}
+../tar_texi/tar.texi(opsummary,3034) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3034)
+../tar_texi/tar.texi(,3035) @item --show-omitted-dirs
+../tar_texi/tar.texi(,3036)
+../tar_texi/tar.texi(,3037) Instructs @command{tar} to mention directories its
skipping over when
+../tar_texi/tar.texi(,3038) operating on a @command{tar} archive.
@xref{show-omitted-dirs}.
+../tar_texi/tar.texi(,3039)
+../tar_texi/tar.texi(opsummary,3040) @anchor{--show-transformed-names}
+../tar_texi/tar.texi(opsummary,3040) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3040)
+../tar_texi/tar.texi(opsummary,3041) @anchor{--show-stored-names}
+../tar_texi/tar.texi(opsummary,3041) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3041)
+../tar_texi/tar.texi(,3042) @item --show-transformed-names
+../tar_texi/tar.texi(,3043) @itemx --show-stored-names
+../tar_texi/tar.texi(,3044)
+../tar_texi/tar.texi(,3045) Display file or member names after applying any
transformations
+../tar_texi/tar.texi(,3046) (@pxref{transform}). In particular, when used in
conjunction with one of
+../tar_texi/tar.texi(,3047) archive creation operations it instructs tar to
list the member names
+../tar_texi/tar.texi(,3048) stored in the archive, as opposed to the actual
file
+../tar_texi/tar.texi(,3049) names. @xref{listing member and file names}.
+../tar_texi/tar.texi(,3050)
+../tar_texi/tar.texi(opsummary,3051) @anchor{--sparse}
+../tar_texi/tar.texi(opsummary,3051) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3051)
+../tar_texi/tar.texi(,3052) @item --sparse
+../tar_texi/tar.texi(,3053) @itemx -S
+../tar_texi/tar.texi(,3054)
+../tar_texi/tar.texi(,3055) Invokes a @acronym{GNU} extension when adding
files to an archive that handles
+../tar_texi/tar.texi(,3056) sparse files efficiently. @xref{sparse}.
+../tar_texi/tar.texi(,3057)
+../tar_texi/tar.texi(opsummary,3058) @anchor{--sparse-version}
+../tar_texi/tar.texi(opsummary,3058) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3058)
+../tar_texi/tar.texi(,3059) @item address@hidden
+../tar_texi/tar.texi(,3060)
+../tar_texi/tar.texi(,3061) Specified the @dfn{format version} to use when
archiving sparse
+../tar_texi/tar.texi(,3062) files. Implies @option{--sparse}. @xref{sparse}.
For the description
+../tar_texi/tar.texi(,3063) of the supported sparse formats, @xref{Sparse
Formats}.
+../tar_texi/tar.texi(,3064)
+../tar_texi/tar.texi(opsummary,3065) @anchor{--starting-file}
+../tar_texi/tar.texi(opsummary,3065) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3065)
+../tar_texi/tar.texi(,3066) @item address@hidden
+../tar_texi/tar.texi(,3067) @itemx -K @var{name}
+../tar_texi/tar.texi(,3068)
+../tar_texi/tar.texi(,3069) This option affects extraction only; @command{tar}
will skip extracting
+../tar_texi/tar.texi(,3070) files in the archive until it finds one that
matches @var{name}.
+../tar_texi/tar.texi(,3071) @xref{Scarce}.
+../tar_texi/tar.texi(,3072)
+../tar_texi/tar.texi(opsummary,3073) @anchor{--strip-components}
+../tar_texi/tar.texi(opsummary,3073) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3073)
+../tar_texi/tar.texi(,3074) @item address@hidden
+../tar_texi/tar.texi(,3075) Strip given @var{number} of leading components
from file names before
+../tar_texi/tar.texi(,3076) address@hidden option was called
@option{--strip-path} in
+../tar_texi/tar.texi(,3077) version 1.14.} For example, if archive
@file{archive.tar} contained
+../tar_texi/tar.texi(,3078) @file{/some/file/name}, then running
+../tar_texi/tar.texi(,3079)
+../tar_texi/tar.texi(,3080) @smallexample
+../tar_texi/tar.texi(,3081) tar --extract --file archive.tar
--strip-components=2
+../tar_texi/tar.texi(,3082) @end smallexample
+../tar_texi/tar.texi(,3083)
+../tar_texi/tar.texi(,3084) @noindent
+../tar_texi/tar.texi(,3085) would extract this file to file @file{name}.
+../tar_texi/tar.texi(,3086)
+../tar_texi/tar.texi(opsummary,3087) @anchor{--suffix}
+../tar_texi/tar.texi(opsummary,3087) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3087) , summary
+../tar_texi/tar.texi(,3088) @item address@hidden
+../tar_texi/tar.texi(,3089)
+../tar_texi/tar.texi(,3090) Alters the suffix @command{tar} uses when backing
up files from the default
+../tar_texi/tar.texi(,3091) @samp{~}. @xref{backup}.
+../tar_texi/tar.texi(,3092)
+../tar_texi/tar.texi(opsummary,3093) @anchor{--tape-length}
+../tar_texi/tar.texi(opsummary,3093) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3093)
+../tar_texi/tar.texi(,3094) @item address@hidden
+../tar_texi/tar.texi(,3095) @itemx -L @var{num}
+../tar_texi/tar.texi(,3096)
+../tar_texi/tar.texi(,3097) Specifies the length of tapes that @command{tar}
is writing as being
+../tar_texi/tar.texi(,3098) @address@hidden x 1024} bytes long. @xref{Using
Multiple Tapes}.
+../tar_texi/tar.texi(,3099)
+../tar_texi/tar.texi(opsummary,3100) @anchor{--test-label}
+../tar_texi/tar.texi(opsummary,3100) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3100)
+../tar_texi/tar.texi(,3101) @item --test-label
+../tar_texi/tar.texi(,3102)
+../tar_texi/tar.texi(,3103) Reads the volume label. If an argument is
specified, test whether it
+../tar_texi/tar.texi(,3104) matches the volume label. @xref{--test-label
option}.
+../tar_texi/tar.texi(,3105)
+../tar_texi/tar.texi(opsummary,3106) @anchor{--to-command}
+../tar_texi/tar.texi(opsummary,3106) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3106)
+../tar_texi/tar.texi(,3107) @item address@hidden
+../tar_texi/tar.texi(,3108)
+../tar_texi/tar.texi(,3109) During extraction @command{tar} will pipe
extracted files to the
+../tar_texi/tar.texi(,3110) standard input of @var{command}. @xref{Writing to
an External Program}.
+../tar_texi/tar.texi(,3111)
+../tar_texi/tar.texi(opsummary,3112) @anchor{--to-stdout}
+../tar_texi/tar.texi(opsummary,3112) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3112)
+../tar_texi/tar.texi(,3113) @item --to-stdout
+../tar_texi/tar.texi(,3114) @itemx -O
+../tar_texi/tar.texi(,3115)
+../tar_texi/tar.texi(,3116) During extraction, @command{tar} will extract
files to stdout rather
+../tar_texi/tar.texi(,3117) than to the file system. @xref{Writing to
Standard Output}.
+../tar_texi/tar.texi(,3118)
+../tar_texi/tar.texi(opsummary,3119) @anchor{--totals}
+../tar_texi/tar.texi(opsummary,3119) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3119)
+../tar_texi/tar.texi(,3120) @item address@hidden
+../tar_texi/tar.texi(,3121)
+../tar_texi/tar.texi(,3122) Displays the total number of bytes transferred
when processing an
+../tar_texi/tar.texi(,3123) archive. If an argument is given, these data are
displayed on
+../tar_texi/tar.texi(,3124) request, when signal @var{signo} is delivered to
@command{tar}.
+../tar_texi/tar.texi(,3125) @xref{totals}.
+../tar_texi/tar.texi(,3126)
+../tar_texi/tar.texi(opsummary,3127) @anchor{--touch}
+../tar_texi/tar.texi(opsummary,3127) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3127)
+../tar_texi/tar.texi(,3128) @item --touch
+../tar_texi/tar.texi(,3129) @itemx -m
+../tar_texi/tar.texi(,3130)
+../tar_texi/tar.texi(,3131) Sets the data modification time of extracted files
to the extraction time,
+../tar_texi/tar.texi(,3132) rather than the data modification time stored in
the archive.
+../tar_texi/tar.texi(,3133) @xref{Data Modification Times}.
+../tar_texi/tar.texi(,3134)
+../tar_texi/tar.texi(opsummary,3135) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3135)
+../tar_texi/tar.texi(,3136) @item --uncompress
+../tar_texi/tar.texi(,3137)
+../tar_texi/tar.texi(,3138) (See @option{--compress}. @pxref{gzip})
+../tar_texi/tar.texi(,3139)
+../tar_texi/tar.texi(opsummary,3140) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3140)
+../tar_texi/tar.texi(,3141) @item --ungzip
+../tar_texi/tar.texi(,3142)
+../tar_texi/tar.texi(,3143) (See @option{--gzip}. @pxref{gzip})
+../tar_texi/tar.texi(,3144)
+../tar_texi/tar.texi(opsummary,3145) @anchor{--unlink-first}
+../tar_texi/tar.texi(opsummary,3145) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3145)
+../tar_texi/tar.texi(,3146) @item --unlink-first
+../tar_texi/tar.texi(,3147) @itemx -U
+../tar_texi/tar.texi(,3148)
+../tar_texi/tar.texi(,3149) Directs @command{tar} to remove the corresponding
file from the file
+../tar_texi/tar.texi(,3150) system before extracting it from the archive.
@xref{Unlink First}.
+../tar_texi/tar.texi(,3151)
+../tar_texi/tar.texi(opsummary,3152) @anchor{--unquote}
+../tar_texi/tar.texi(opsummary,3152) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3152)
+../tar_texi/tar.texi(,3153) @item --unquote
+../tar_texi/tar.texi(,3154) Enable unquoting input file or member names
(default). @xref{input
+../tar_texi/tar.texi(,3155) name quoting}.
+../tar_texi/tar.texi(,3156)
+../tar_texi/tar.texi(opsummary,3157) @anchor{--use-compress-program}
+../tar_texi/tar.texi(opsummary,3157) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3157)
+../tar_texi/tar.texi(,3158) @item address@hidden
+../tar_texi/tar.texi(,3159)
+../tar_texi/tar.texi(,3160) Instructs @command{tar} to access the archive
through @var{prog}, which is
+../tar_texi/tar.texi(,3161) presumed to be a compression program of some sort.
@xref{gzip}.
+../tar_texi/tar.texi(,3162)
+../tar_texi/tar.texi(opsummary,3163) @anchor{--utc}
+../tar_texi/tar.texi(opsummary,3163) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3163)
+../tar_texi/tar.texi(,3164) @item --utc
+../tar_texi/tar.texi(,3165)
+../tar_texi/tar.texi(,3166) Display file modification dates in @acronym{UTC}.
This option implies
+../tar_texi/tar.texi(,3167) @option{--verbose}.
+../tar_texi/tar.texi(,3168)
+../tar_texi/tar.texi(opsummary,3169) @anchor{--verbose}
+../tar_texi/tar.texi(opsummary,3169) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3169)
+../tar_texi/tar.texi(,3170) @item --verbose
+../tar_texi/tar.texi(,3171) @itemx -v
+../tar_texi/tar.texi(,3172)
+../tar_texi/tar.texi(,3173) Specifies that @command{tar} should be more
verbose about the operations its
+../tar_texi/tar.texi(,3174) performing. This option can be specified multiple
times for some
+../tar_texi/tar.texi(,3175) operations to increase the amount of information
displayed.
+../tar_texi/tar.texi(,3176) @xref{verbose}.
+../tar_texi/tar.texi(,3177)
+../tar_texi/tar.texi(opsummary,3178) @anchor{--verify}
+../tar_texi/tar.texi(opsummary,3178) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3178)
+../tar_texi/tar.texi(,3179) @item --verify
+../tar_texi/tar.texi(,3180) @itemx -W
+../tar_texi/tar.texi(,3181)
+../tar_texi/tar.texi(,3182) Verifies that the archive was correctly written
when creating an
+../tar_texi/tar.texi(,3183) archive. @xref{verify}.
+../tar_texi/tar.texi(,3184)
+../tar_texi/tar.texi(opsummary,3185) @anchor{--version}
+../tar_texi/tar.texi(opsummary,3185) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3185)
+../tar_texi/tar.texi(,3186) @item --version
+../tar_texi/tar.texi(,3187)
+../tar_texi/tar.texi(,3188) Print information about the program's name,
version, origin and legal
+../tar_texi/tar.texi(,3189) status, all on standard output, and then exit
successfully.
+../tar_texi/tar.texi(,3190) @xref{help}.
+../tar_texi/tar.texi(,3191)
+../tar_texi/tar.texi(opsummary,3192) @anchor{--volno-file}
+../tar_texi/tar.texi(opsummary,3192) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3192)
+../tar_texi/tar.texi(,3193) @item address@hidden
+../tar_texi/tar.texi(,3194)
+../tar_texi/tar.texi(,3195) Used in conjunction with @option{--multi-volume}.
@command{tar} will
+../tar_texi/tar.texi(,3196) keep track of which volume of a multi-volume
archive its working in
+../tar_texi/tar.texi(,3197) @var{file}. @xref{volno-file}.
+../tar_texi/tar.texi(,3198)
+../tar_texi/tar.texi(opsummary,3199) @anchor{--wildcards}
+../tar_texi/tar.texi(opsummary,3199) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3199)
+../tar_texi/tar.texi(,3200) @item --wildcards
+../tar_texi/tar.texi(,3201) Use wildcards when matching member names with
patterns.
+../tar_texi/tar.texi(,3202) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,3203)
+../tar_texi/tar.texi(opsummary,3204) @anchor{--wildcards-match-slash}
+../tar_texi/tar.texi(opsummary,3204) @opindex address@hidden,
summary}../tar_texi/tar.texi(opsummary,3204)
+../tar_texi/tar.texi(,3205) @item --wildcards-match-slash
+../tar_texi/tar.texi(,3206) Wildcards match @samp{/}.
+../tar_texi/tar.texi(,3207) @xref{controlling pattern-matching}.
+../tar_texi/tar.texi(,3208) @end table
+../tar_texi/tar.texi(,3209)
+../tar_texi/tar.texi(,3210) @node Short Option Summary
+../tar_texi/tar.texi(,3211) @subsection Short Options Cross Reference
+../tar_texi/tar.texi(,3212)
+../tar_texi/tar.texi(,3213) Here is an alphabetized list of all of the short
option forms, matching
+../tar_texi/tar.texi(,3214) them with the equivalent long option.
+../tar_texi/tar.texi(,3215)
+../tar_texi/tar.texi(,3216) @multitable @columnfractions 0.20 0.80
+../tar_texi/tar.texi(,3217) @headitem Short Option @tab Reference
+../tar_texi/tar.texi(,3218)
+../tar_texi/tar.texi(,3219) @item -A @tab @ref{--concatenate}.
+../tar_texi/tar.texi(,3220)
+../tar_texi/tar.texi(,3221) @item -B @tab @ref{--read-full-records}.
+../tar_texi/tar.texi(,3222)
+../tar_texi/tar.texi(,3223) @item -C @tab @ref{--directory}.
+../tar_texi/tar.texi(,3224)
+../tar_texi/tar.texi(,3225) @item -F @tab @ref{--info-script}.
+../tar_texi/tar.texi(,3226)
+../tar_texi/tar.texi(,3227) @item -G @tab @ref{--incremental}.
+../tar_texi/tar.texi(,3228)
+../tar_texi/tar.texi(,3229) @item -K @tab @ref{--starting-file}.
+../tar_texi/tar.texi(,3230)
+../tar_texi/tar.texi(,3231) @item -L @tab @ref{--tape-length}.
+../tar_texi/tar.texi(,3232)
+../tar_texi/tar.texi(,3233) @item -M @tab @ref{--multi-volume}.
+../tar_texi/tar.texi(,3234)
+../tar_texi/tar.texi(,3235) @item -N @tab @ref{--newer}.
+../tar_texi/tar.texi(,3236)
+../tar_texi/tar.texi(,3237) @item -O @tab @ref{--to-stdout}.
+../tar_texi/tar.texi(,3238)
+../tar_texi/tar.texi(,3239) @item -P @tab @ref{--absolute-names}.
+../tar_texi/tar.texi(,3240)
+../tar_texi/tar.texi(,3241) @item -R @tab @ref{--block-number}.
+../tar_texi/tar.texi(,3242)
+../tar_texi/tar.texi(,3243) @item -S @tab @ref{--sparse}.
+../tar_texi/tar.texi(,3244)
+../tar_texi/tar.texi(,3245) @item -T @tab @ref{--files-from}.
+../tar_texi/tar.texi(,3246)
+../tar_texi/tar.texi(,3247) @item -U @tab @ref{--unlink-first}.
+../tar_texi/tar.texi(,3248)
+../tar_texi/tar.texi(,3249) @item -V @tab @ref{--label}.
+../tar_texi/tar.texi(,3250)
+../tar_texi/tar.texi(,3251) @item -W @tab @ref{--verify}.
+../tar_texi/tar.texi(,3252)
+../tar_texi/tar.texi(,3253) @item -X @tab @ref{--exclude-from}.
+../tar_texi/tar.texi(,3254)
+../tar_texi/tar.texi(,3255) @item -Z @tab @ref{--compress}.
+../tar_texi/tar.texi(,3256)
+../tar_texi/tar.texi(,3257) @item -b @tab @ref{--blocking-factor}.
+../tar_texi/tar.texi(,3258)
+../tar_texi/tar.texi(,3259) @item -c @tab @ref{--create}.
+../tar_texi/tar.texi(,3260)
+../tar_texi/tar.texi(,3261) @item -d @tab @ref{--compare}.
+../tar_texi/tar.texi(,3262)
+../tar_texi/tar.texi(,3263) @item -f @tab @ref{--file}.
+../tar_texi/tar.texi(,3264)
+../tar_texi/tar.texi(,3265) @item -g @tab @ref{--listed-incremental}.
+../tar_texi/tar.texi(,3266)
+../tar_texi/tar.texi(,3267) @item -h @tab @ref{--dereference}.
+../tar_texi/tar.texi(,3268)
+../tar_texi/tar.texi(,3269) @item -i @tab @ref{--ignore-zeros}.
+../tar_texi/tar.texi(,3270)
+../tar_texi/tar.texi(,3271) @item -j @tab @ref{--bzip2}.
+../tar_texi/tar.texi(,3272)
+../tar_texi/tar.texi(,3273) @item -k @tab @ref{--keep-old-files}.
+../tar_texi/tar.texi(,3274)
+../tar_texi/tar.texi(,3275) @item -l @tab @ref{--check-links}.
+../tar_texi/tar.texi(,3276)
+../tar_texi/tar.texi(,3277) @item -m @tab @ref{--touch}.
+../tar_texi/tar.texi(,3278)
+../tar_texi/tar.texi(,3279) @item -o @tab When creating,
@ref{--no-same-owner}, when extracting ---
+../tar_texi/tar.texi(,3280) @ref{--portability}.
+../tar_texi/tar.texi(,3281)
+../tar_texi/tar.texi(,3282) The later usage is deprecated. It is retained for
compatibility with
+../tar_texi/tar.texi(GNUTAR,3283) the earlier versions of
../tar_texi/tar.texi(GNUTAR,3283) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3283) . In the future releases
+../tar_texi/tar.texi(,3284) @option{-o} will be equivalent to
@option{--no-same-owner} only.
+../tar_texi/tar.texi(,3285)
+../tar_texi/tar.texi(,3286) @item -p @tab @ref{--preserve-permissions}.
+../tar_texi/tar.texi(,3287)
+../tar_texi/tar.texi(,3288) @item -r @tab @ref{--append}.
+../tar_texi/tar.texi(,3289)
+../tar_texi/tar.texi(,3290) @item -s @tab @ref{--same-order}.
+../tar_texi/tar.texi(,3291)
+../tar_texi/tar.texi(,3292) @item -t @tab @ref{--list}.
+../tar_texi/tar.texi(,3293)
+../tar_texi/tar.texi(,3294) @item -u @tab @ref{--update}.
+../tar_texi/tar.texi(,3295)
+../tar_texi/tar.texi(,3296) @item -v @tab @ref{--verbose}.
+../tar_texi/tar.texi(,3297)
+../tar_texi/tar.texi(,3298) @item -w @tab @ref{--interactive}.
+../tar_texi/tar.texi(,3299)
+../tar_texi/tar.texi(,3300) @item -x @tab @ref{--extract}.
+../tar_texi/tar.texi(,3301)
+../tar_texi/tar.texi(,3302) @item -z @tab @ref{--gzip}.
+../tar_texi/tar.texi(,3303)
+../tar_texi/tar.texi(,3304) @end multitable
+../tar_texi/tar.texi(,3305)
+../tar_texi/tar.texi(,3306) @node help
+../tar_texi/tar.texi(GNUTAR,3307) @section ../tar_texi/tar.texi(GNUTAR,3307)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,3307) documentation
+../tar_texi/tar.texi(,3308)
+../tar_texi/tar.texi(,3309) @cindex Getting program version number
+../tar_texi/tar.texi(,3310) @opindex version
+../tar_texi/tar.texi(,3311) @cindex Version of the @command{tar} program
+../tar_texi/tar.texi(,3312) Being careful, the first thing is really checking
that you are using
+../tar_texi/tar.texi(GNUTAR,3313) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3313) , indeed. The
@option{--version} option
+../tar_texi/tar.texi(,3314) causes @command{tar} to print information about
its name, version,
+../tar_texi/tar.texi(,3315) origin and legal status, all on standard output,
and then exit
+../tar_texi/tar.texi(,3316) successfully. For example, @address@hidden
--version}} might print:
+../tar_texi/tar.texi(,3317)
+../tar_texi/tar.texi(,3318) @smallexample
+../tar_texi/tar.texi(,3319) tar (GNU tar) 1.15.92
+../tar_texi/tar.texi(,3320) Copyright (C) 2006 Free Software Foundation, Inc.
+../tar_texi/tar.texi(,3321) This is free software. You may redistribute
copies of it under the terms
+../tar_texi/tar.texi(,3322) of the GNU General Public License
<http://www.gnu.org/licenses/gpl.html>.
+../tar_texi/tar.texi(,3323) There is NO WARRANTY, to the extent permitted by
law.
+../tar_texi/tar.texi(,3324)
+../tar_texi/tar.texi(,3325) Written by John Gilmore and Jay Fenlason.
+../tar_texi/tar.texi(,3326) @end smallexample
+../tar_texi/tar.texi(,3327)
+../tar_texi/tar.texi(,3328) @noindent
+../tar_texi/tar.texi(,3329) The first occurrence of @samp{tar} in the result
above is the program
+../tar_texi/tar.texi(,3330) name in the package (for example, @command{rmt} is
another program),
+../tar_texi/tar.texi(,3331) while the second occurrence of @samp{tar} is the
name of the package
+../tar_texi/tar.texi(,3332) itself, containing possibly many programs. The
package is currently
+../tar_texi/tar.texi(,3333) named @samp{tar}, after the name of the main
program it
+../tar_texi/tar.texi(,3334) address@hidden are plans to merge the
@command{cpio} and
+../tar_texi/tar.texi(,3335) @command{tar} packages into a single one which
would be called
+../tar_texi/tar.texi(,3336) @code{paxutils}. So, who knows if, one of this
days, the
+../tar_texi/tar.texi(,3337) @option{--version} would not output
@address@hidden (@acronym{GNU}
+../tar_texi/tar.texi(,3338) paxutils) 3.2}}}.
+../tar_texi/tar.texi(,3339)
+../tar_texi/tar.texi(,3340) @cindex Obtaining help
+../tar_texi/tar.texi(,3341) @cindex Listing all @command{tar} options
+../tar_texi/tar.texi(xopindex,3342) @opindex address@hidden,
introduction}../tar_texi/tar.texi(xopindex,3342)
+../tar_texi/tar.texi(,3343) Another thing you might want to do is checking the
spelling or meaning
+../tar_texi/tar.texi(,3344) of some particular @command{tar} option, without
resorting to this
+../tar_texi/tar.texi(GNUTAR,3345) manual, for once you have carefully read it.
../tar_texi/tar.texi(GNUTAR,3345) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3345)
+../tar_texi/tar.texi(,3346) has a short help feature, triggerable through the
+../tar_texi/tar.texi(,3347) @option{--help} option. By using this option,
@command{tar} will
+../tar_texi/tar.texi(,3348) print a usage message listing all available
options on standard
+../tar_texi/tar.texi(,3349) output, then exit successfully, without doing
anything else and
+../tar_texi/tar.texi(,3350) ignoring all other options. Even if this is only
a brief summary, it
+../tar_texi/tar.texi(,3351) may be several screens long. So, if you are not
using some kind of
+../tar_texi/tar.texi(,3352) scrollable window, you might prefer to use
something like:
+../tar_texi/tar.texi(,3353)
+../tar_texi/tar.texi(,3354) @smallexample
+../tar_texi/tar.texi(,3355) $ @kbd{tar --help | less}
+../tar_texi/tar.texi(,3356) @end smallexample
+../tar_texi/tar.texi(,3357)
+../tar_texi/tar.texi(,3358) @noindent
+../tar_texi/tar.texi(,3359) presuming, here, that you like using
@command{less} for a pager. Other
+../tar_texi/tar.texi(,3360) popular pagers are @command{more} and
@command{pg}. If you know about some
+../tar_texi/tar.texi(,3361) @var{keyword} which interests you and do not want
to read all the
+../tar_texi/tar.texi(,3362) @option{--help} output, another common idiom is
doing:
+../tar_texi/tar.texi(,3363)
+../tar_texi/tar.texi(,3364) @smallexample
+../tar_texi/tar.texi(,3365) tar --help | grep @var{keyword}
+../tar_texi/tar.texi(,3366) @end smallexample
+../tar_texi/tar.texi(,3367)
+../tar_texi/tar.texi(,3368) @noindent
+../tar_texi/tar.texi(,3369) for getting only the pertinent lines. Notice,
however, that some
+../tar_texi/tar.texi(,3370) @command{tar} options have long description lines
and the above
+../tar_texi/tar.texi(,3371) command will list only the first of them.
+../tar_texi/tar.texi(,3372)
+../tar_texi/tar.texi(,3373) The exact look of the option summary displayed by
@kbd{tar --help} is
+../tar_texi/tar.texi(,3374) configurable. @xref{Configuring Help Summary}, for
a detailed description.
+../tar_texi/tar.texi(,3375)
+../tar_texi/tar.texi(,3376) @opindex usage
+../tar_texi/tar.texi(,3377) If you only wish to check the spelling of an
option, running @kbd{tar
+../tar_texi/tar.texi(,3378) --usage} may be a better choice. This will
display a terse list of
+../tar_texi/tar.texi(,3379) @command{tar} option without accompanying
explanations.
+../tar_texi/tar.texi(,3380)
+../tar_texi/tar.texi(,3381) The short help output is quite succinct, and you
might have to get
+../tar_texi/tar.texi(,3382) back to the full documentation for precise points.
If you are reading
+../tar_texi/tar.texi(,3383) this paragraph, you already have the @command{tar}
manual in some
+../tar_texi/tar.texi(,3384) form. This manual is available in a variety of
forms from
+../tar_texi/tar.texi(GNUTAR,3385)
@url{http://www.gnu.org/software/tar/manual}. It may be printed out of the
../tar_texi/tar.texi(GNUTAR,3385) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3385)
+../tar_texi/tar.texi(,3386) distribution, provided you have @TeX{} already
installed somewhere,
+../tar_texi/tar.texi(,3387) and a laser printer around. Just configure the
distribution, execute
+../tar_texi/tar.texi(,3388) the command @address@hidden dvi}}, then print
@file{doc/tar.dvi} the
+../tar_texi/tar.texi(GNUTAR,3389) usual way (contact your local guru to know
how). If ../tar_texi/tar.texi(GNUTAR,3389) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3389)
+../tar_texi/tar.texi(,3390) has been conveniently installed at your place, this
+../tar_texi/tar.texi(,3391) manual is also available in interactive,
hypertextual form as an Info
+../tar_texi/tar.texi(,3392) file. Just call @address@hidden tar}} or, if you
do not have the
+../tar_texi/tar.texi(,3393) @command{info} program handy, use the Info reader
provided within
+../tar_texi/tar.texi(,3394) @acronym{GNU} Emacs, calling @samp{tar} from the
main Info menu.
+../tar_texi/tar.texi(,3395)
+../tar_texi/tar.texi(GNUTAR,3396) There is currently no @code{man} page for
../tar_texi/tar.texi(GNUTAR,3396) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3396) .
+../tar_texi/tar.texi(,3397) If you observe such a @code{man} page on the
system you are running,
+../tar_texi/tar.texi(GNUTAR,3398) either it does not belong to
../tar_texi/tar.texi(GNUTAR,3398) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3398) , or it has not
+../tar_texi/tar.texi(,3399) been produced by @acronym{GNU}. Some package
maintainers convert
+../tar_texi/tar.texi(,3400) @kbd{tar --help} output to a man page, using
@command{help2man}. In
+../tar_texi/tar.texi(,3401) any case, please bear in mind that the
authoritative source of
+../tar_texi/tar.texi(GNUTAR,3402) information about
../tar_texi/tar.texi(GNUTAR,3402) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3402) is this Texinfo documentation.
+../tar_texi/tar.texi(,3403)
+../tar_texi/tar.texi(,3404) @node defaults
+../tar_texi/tar.texi(GNUTAR,3405) @section Obtaining
../tar_texi/tar.texi(GNUTAR,3405) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3405) default values
+../tar_texi/tar.texi(,3406)
+../tar_texi/tar.texi(,3407) @opindex show-defaults
+../tar_texi/tar.texi(GNUTAR,3408) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3408) has some predefined defaults
that are used when you do not
+../tar_texi/tar.texi(,3409) explicitely specify another values. To obtain a
list of such
+../tar_texi/tar.texi(,3410) defaults, use @option{--show-defaults} option.
This will output the
+../tar_texi/tar.texi(,3411) values in the form of @command{tar} command line
options:
+../tar_texi/tar.texi(,3412)
+../tar_texi/tar.texi(,3413) @smallexample
+../tar_texi/tar.texi(,3414) @group
+../tar_texi/tar.texi(,3415) @kbd{tar --show-defaults}
+../tar_texi/tar.texi(,3416) --format=gnu -f- -b20 --quoting-style=escape
+../tar_texi/tar.texi(,3417) --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
+../tar_texi/tar.texi(,3418) @end group
+../tar_texi/tar.texi(,3419) @end smallexample
+../tar_texi/tar.texi(,3420)
+../tar_texi/tar.texi(,3421) @noindent
+../tar_texi/tar.texi(,3422) Notice, that this option outputs only one line.
The example output above
+../tar_texi/tar.texi(,3423) has been split to fit page boundaries.
+../tar_texi/tar.texi(,3424)
+../tar_texi/tar.texi(,3425) @noindent
+../tar_texi/tar.texi(GNUTAR,3426) The above output shows that this version of
../tar_texi/tar.texi(GNUTAR,3426) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3426) defaults to
+../tar_texi/tar.texi(,3427) using @samp{gnu} archive format (@pxref{Formats}),
it uses standard
+../tar_texi/tar.texi(,3428) output as the archive, if no @option{--file}
option has been given
+../tar_texi/tar.texi(,3429) (@pxref{file tutorial}), the default blocking
factor is 20
+../tar_texi/tar.texi(,3430) (@pxref{Blocking Factor}). It also shows the
default locations where
+../tar_texi/tar.texi(,3431) @command{tar} will look for @command{rmt} and
@command{rsh} binaries.
+../tar_texi/tar.texi(,3432)
+../tar_texi/tar.texi(,3433) @node verbose
+../tar_texi/tar.texi(,3434) @section Checking @command{tar} progress
+../tar_texi/tar.texi(,3435)
+../tar_texi/tar.texi(,3436) Typically, @command{tar} performs most operations
without reporting any
+../tar_texi/tar.texi(,3437) information to the user except error messages.
When using @command{tar}
+../tar_texi/tar.texi(,3438) with many options, particularly ones with
complicated or
+../tar_texi/tar.texi(,3439) difficult-to-predict behavior, it is possible to
make serious mistakes.
+../tar_texi/tar.texi(,3440) @command{tar} provides several options that make
observing @command{tar}
+../tar_texi/tar.texi(,3441) easier. These options cause @command{tar} to
print information as it
+../tar_texi/tar.texi(,3442) progresses in its job, and you might want to use
them just for being
+../tar_texi/tar.texi(,3443) more careful about what is going on, or merely for
entertaining
+../tar_texi/tar.texi(,3444) yourself. If you have encountered a problem when
operating on an
+../tar_texi/tar.texi(,3445) archive, however, you may need more information
than just an error
+../tar_texi/tar.texi(,3446) message in order to solve the problem. The
following options can be
+../tar_texi/tar.texi(,3447) helpful diagnostic tools.
+../tar_texi/tar.texi(,3448)
+../tar_texi/tar.texi(,3449) @cindex Verbose operation
+../tar_texi/tar.texi(,3450) @opindex verbose
+../tar_texi/tar.texi(,3451) Normally, the @option{--list} (@option{-t})
command to list an archive
+../tar_texi/tar.texi(,3452) prints just the file names (one per line) and the
other commands are
+../tar_texi/tar.texi(,3453) silent. When used with most operations, the
@option{--verbose}
+../tar_texi/tar.texi(,3454) (@option{-v}) option causes @command{tar} to print
the name of each
+../tar_texi/tar.texi(,3455) file or archive member as it is processed. This
and the other options
+../tar_texi/tar.texi(,3456) which make @command{tar} print status information
can be useful in
+../tar_texi/tar.texi(,3457) monitoring @command{tar}.
+../tar_texi/tar.texi(,3458)
+../tar_texi/tar.texi(,3459) With @option{--create} or @option{--extract},
@option{--verbose} used
+../tar_texi/tar.texi(,3460) once just prints the names of the files or members
as they are processed.
+../tar_texi/tar.texi(,3461) Using it twice causes @command{tar} to print a
longer listing
+../tar_texi/tar.texi(,3462) (@xref{verbose member listing}, for the
description) for each member.
+../tar_texi/tar.texi(,3463) Since @option{--list} already prints the names of
the members,
+../tar_texi/tar.texi(,3464) @option{--verbose} used once with @option{--list}
causes @command{tar}
+../tar_texi/tar.texi(,3465) to print an @samp{ls -l} type listing of the files
in the archive.
+../tar_texi/tar.texi(,3466) The following examples both extract members with
long list output:
+../tar_texi/tar.texi(,3467)
+../tar_texi/tar.texi(,3468) @smallexample
+../tar_texi/tar.texi(,3469) $ @kbd{tar --extract --file=archive.tar --verbose
--verbose}
+../tar_texi/tar.texi(,3470) $ @kbd{tar xvvf archive.tar}
+../tar_texi/tar.texi(,3471) @end smallexample
+../tar_texi/tar.texi(,3472)
+../tar_texi/tar.texi(,3473) Verbose output appears on the standard output
except when an archive is
+../tar_texi/tar.texi(,3474) being written to the standard output, as with
@samp{tar --create
+../tar_texi/tar.texi(,3475) --file=- --verbose} (@samp{tar cfv -}, or even
@samp{tar cv}---if the
+../tar_texi/tar.texi(,3476) installer let standard output be the default
archive). In that case
+../tar_texi/tar.texi(,3477) @command{tar} writes verbose output to the
standard error stream.
+../tar_texi/tar.texi(,3478)
+../tar_texi/tar.texi(,3479) If @address@hidden is specified, @command{tar}
sends
+../tar_texi/tar.texi(,3480) verbose output to @var{file} rather than to
standard output or standard
+../tar_texi/tar.texi(,3481) error.
+../tar_texi/tar.texi(,3482)
+../tar_texi/tar.texi(,3483) @anchor{totals}
+../tar_texi/tar.texi(,3484) @cindex Obtaining total status information
+../tar_texi/tar.texi(,3485) @opindex totals
+../tar_texi/tar.texi(,3486) The @option{--totals} option causes @command{tar}
to print on the
+../tar_texi/tar.texi(,3487) standard error the total amount of bytes
transferred when processing
+../tar_texi/tar.texi(,3488) an archive. When creating or appending to an
archive, this option
+../tar_texi/tar.texi(,3489) prints the number of bytes written to the archive
and the average
+../tar_texi/tar.texi(,3490) speed at which they have been written, e.g.:
+../tar_texi/tar.texi(,3491)
+../tar_texi/tar.texi(,3492) @smallexample
+../tar_texi/tar.texi(,3493) @group
+../tar_texi/tar.texi(,3494) $ @kbd{tar -c -f archive.tar --totals /home}
+../tar_texi/tar.texi(,3495) Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
+../tar_texi/tar.texi(,3496) @end group
+../tar_texi/tar.texi(,3497) @end smallexample
+../tar_texi/tar.texi(,3498)
+../tar_texi/tar.texi(,3499) When reading an archive, this option displays the
number of bytes
+../tar_texi/tar.texi(,3500) read:
+../tar_texi/tar.texi(,3501)
+../tar_texi/tar.texi(,3502) @smallexample
+../tar_texi/tar.texi(,3503) @group
+../tar_texi/tar.texi(,3504) $ @kbd{tar -x -f archive.tar --totals}
+../tar_texi/tar.texi(,3505) Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
+../tar_texi/tar.texi(,3506) @end group
+../tar_texi/tar.texi(,3507) @end smallexample
+../tar_texi/tar.texi(,3508)
+../tar_texi/tar.texi(,3509) Finally, when deleting from an archive, the
@option{--totals} option
+../tar_texi/tar.texi(,3510) displays both numbers plus number of bytes removed
from the archive:
+../tar_texi/tar.texi(,3511)
+../tar_texi/tar.texi(,3512) @smallexample
+../tar_texi/tar.texi(,3513) @group
+../tar_texi/tar.texi(,3514) $ @kbd{tar --delete -f foo.tar --totals
--wildcards '*~'}
+../tar_texi/tar.texi(,3515) Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+../tar_texi/tar.texi(,3516) Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+../tar_texi/tar.texi(,3517) Total bytes deleted: 1474048
+../tar_texi/tar.texi(,3518) @end group
+../tar_texi/tar.texi(,3519) @end smallexample
+../tar_texi/tar.texi(,3520)
+../tar_texi/tar.texi(,3521) You can also obtain this information on request.
When
+../tar_texi/tar.texi(,3522) @option{--totals} is used with an argument, this
argument is
+../tar_texi/tar.texi(,3523) interpreted as a symbolic name of a signal, upon
delivery of which the
+../tar_texi/tar.texi(,3524) statistics is to be printed:
+../tar_texi/tar.texi(,3525)
+../tar_texi/tar.texi(,3526) @table @option
+../tar_texi/tar.texi(,3527) @item address@hidden
+../tar_texi/tar.texi(,3528) Print statistics upon delivery of signal
@var{signo}. Valid arguments
+../tar_texi/tar.texi(,3529) are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT},
@code{SIGUSR1} and
+../tar_texi/tar.texi(,3530) @code{SIGUSR2}. Shortened names without
@samp{SIG} prefix are also
+../tar_texi/tar.texi(,3531) accepted.
+../tar_texi/tar.texi(,3532) @end table
+../tar_texi/tar.texi(,3533)
+../tar_texi/tar.texi(,3534) Both forms of @option{--totals} option can be used
simultaneously.
+../tar_texi/tar.texi(,3535) Thus, @kbd{tar -x --totals --totals=USR1}
instructs @command{tar} to
+../tar_texi/tar.texi(,3536) extract all members from its default archive and
print statistics
+../tar_texi/tar.texi(,3537) after finishing the extraction, as well as when
receiving signal
+../tar_texi/tar.texi(,3538) @code{SIGUSR1}.
+../tar_texi/tar.texi(,3539)
+../tar_texi/tar.texi(,3540) @anchor{Progress information}
+../tar_texi/tar.texi(,3541) @cindex Progress information
+../tar_texi/tar.texi(,3542) @opindex checkpoint
+../tar_texi/tar.texi(,3543) The @option{--checkpoint} option prints an
occasional message
+../tar_texi/tar.texi(,3544) as @command{tar} reads or writes the archive. It
is designed for
+../tar_texi/tar.texi(,3545) those who don't need the more detailed (and
voluminous) output of
+../tar_texi/tar.texi(,3546) @option{--block-number} (@option{-R}), but do want
visual confirmation
+../tar_texi/tar.texi(,3547) that @command{tar} is actually making forward
progress. By default it
+../tar_texi/tar.texi(,3548) prints a message each 10 records read or written.
This can be changed
+../tar_texi/tar.texi(,3549) by giving it a numeric argument after an equal
sign:
+../tar_texi/tar.texi(,3550)
+../tar_texi/tar.texi(,3551) @smallexample
+../tar_texi/tar.texi(,3552) $ @kbd{tar -c --checkpoint=1000} /var
+../tar_texi/tar.texi(,3553) tar: Write checkpoint 1000
+../tar_texi/tar.texi(,3554) tar: Write checkpoint 2000
+../tar_texi/tar.texi(,3555) tar: Write checkpoint 3000
+../tar_texi/tar.texi(,3556) @end smallexample
+../tar_texi/tar.texi(,3557)
+../tar_texi/tar.texi(,3558) This example shows the default checkpoint message
used by
+../tar_texi/tar.texi(,3559) @command{tar}. If you place a dot immediately
after the equal
+../tar_texi/tar.texi(,3560) sign, it will print a @samp{.} at each checkpoint.
For example:
+../tar_texi/tar.texi(,3561)
+../tar_texi/tar.texi(,3562) @smallexample
+../tar_texi/tar.texi(,3563) $ @kbd{tar -c --checkpoint=.1000} /var
+../tar_texi/tar.texi(,3564) ...
+../tar_texi/tar.texi(,3565) @end smallexample
+../tar_texi/tar.texi(,3566)
+../tar_texi/tar.texi(,3567) @opindex show-omitted-dirs
+../tar_texi/tar.texi(,3568) @anchor{show-omitted-dirs}
+../tar_texi/tar.texi(,3569) The @option{--show-omitted-dirs} option, when
reading an archive---with
+../tar_texi/tar.texi(,3570) @option{--list} or @option{--extract}, for
example---causes a message
+../tar_texi/tar.texi(,3571) to be printed for each directory in the archive
which is skipped.
+../tar_texi/tar.texi(,3572) This happens regardless of the reason for
skipping: the directory might
+../tar_texi/tar.texi(,3573) not have been named on the command line
(implicitly or explicitly),
+../tar_texi/tar.texi(,3574) it might be excluded by the use of the
+../tar_texi/tar.texi(,3575) @address@hidden option, or some other reason.
+../tar_texi/tar.texi(,3576)
+../tar_texi/tar.texi(,3577) @opindex block-number
+../tar_texi/tar.texi(,3578) @cindex Block number where error occurred
+../tar_texi/tar.texi(,3579) @anchor{block-number}
+../tar_texi/tar.texi(,3580) If @option{--block-number} (@option{-R}) is used,
@command{tar} prints, along with
+../tar_texi/tar.texi(,3581) every message it would normally produce, the block
number within the
+../tar_texi/tar.texi(,3582) archive where the message was triggered. Also,
supplementary messages
+../tar_texi/tar.texi(,3583) are triggered when reading blocks full of NULs, or
when hitting end of
+../tar_texi/tar.texi(,3584) file on the archive. As of now, if the archive if
properly terminated
+../tar_texi/tar.texi(,3585) with a NUL block, the reading of the file may stop
before end of file
+../tar_texi/tar.texi(,3586) is met, so the position of end of file will not
usually show when
+../tar_texi/tar.texi(GNUTAR,3587) @option{--block-number} (@option{-R}) is
used. Note that ../tar_texi/tar.texi(GNUTAR,3587) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3587)
+../tar_texi/tar.texi(,3588) drains the archive before exiting when reading the
+../tar_texi/tar.texi(,3589) archive from a pipe.
+../tar_texi/tar.texi(,3590)
+../tar_texi/tar.texi(,3591) @cindex Error message, block number of
+../tar_texi/tar.texi(,3592) This option is especially useful when reading
damaged archives, since
+../tar_texi/tar.texi(,3593) it helps pinpoint the damaged sections. It can
also be used with
+../tar_texi/tar.texi(,3594) @option{--list} (@option{-t}) when listing a
file-system backup tape, allowing you to
+../tar_texi/tar.texi(,3595) choose among several backup tapes when retrieving
a file later, in
+../tar_texi/tar.texi(,3596) favor of the tape where the file appears earliest
(closest to the
+../tar_texi/tar.texi(,3597) front of the tape). @xref{backup}.
+../tar_texi/tar.texi(,3598)
+../tar_texi/tar.texi(,3599) @node interactive
+../tar_texi/tar.texi(,3600) @section Asking for Confirmation During Operations
+../tar_texi/tar.texi(,3601) @cindex Interactive operation
+../tar_texi/tar.texi(,3602)
+../tar_texi/tar.texi(,3603) Typically, @command{tar} carries out a command
without stopping for
+../tar_texi/tar.texi(,3604) further instructions. In some situations however,
you may want to
+../tar_texi/tar.texi(,3605) exclude some files and archive members from the
operation (for instance
+../tar_texi/tar.texi(,3606) if disk or storage space is tight). You can do
this by excluding
+../tar_texi/tar.texi(,3607) certain files automatically (@pxref{Choosing}), or
by performing
+../tar_texi/tar.texi(,3608) an operation interactively, using the
@option{--interactive} (@option{-w}) option.
+../tar_texi/tar.texi(,3609) @command{tar} also accepts @option{--confirmation}
for this option.
+../tar_texi/tar.texi(,3610)
+../tar_texi/tar.texi(,3611) @opindex interactive
+../tar_texi/tar.texi(,3612) When the @option{--interactive} (@option{-w})
option is specified, before
+../tar_texi/tar.texi(,3613) reading, writing, or deleting files, @command{tar}
first prints a message
+../tar_texi/tar.texi(,3614) for each such file, telling what operation it
intends to take, then asks
+../tar_texi/tar.texi(,3615) for confirmation on the terminal. The actions
which require
+../tar_texi/tar.texi(,3616) confirmation include adding a file to the archive,
extracting a file
+../tar_texi/tar.texi(,3617) from the archive, deleting a file from the
archive, and deleting a file
+../tar_texi/tar.texi(,3618) from disk. To confirm the action, you must type a
line of input
+../tar_texi/tar.texi(,3619) beginning with @samp{y}. If your input line
begins with anything other
+../tar_texi/tar.texi(,3620) than @samp{y}, @command{tar} skips that file.
+../tar_texi/tar.texi(,3621)
+../tar_texi/tar.texi(,3622) If @command{tar} is reading the archive from the
standard input,
+../tar_texi/tar.texi(,3623) @command{tar} opens the file @file{/dev/tty} to
support the interactive
+../tar_texi/tar.texi(,3624) communications.
+../tar_texi/tar.texi(,3625)
+../tar_texi/tar.texi(,3626) Verbose output is normally sent to standard
output, separate from
+../tar_texi/tar.texi(,3627) other error messages. However, if the archive is
produced directly
+../tar_texi/tar.texi(,3628) on standard output, then verbose output is mixed
with errors on
+../tar_texi/tar.texi(,3629) @code{stderr}. Producing the archive on standard
output may be used
+../tar_texi/tar.texi(,3630) as a way to avoid using disk space, when the
archive is soon to be
+../tar_texi/tar.texi(,3631) consumed by another process reading it, say. Some
people felt the need
+../tar_texi/tar.texi(,3632) of producing an archive on stdout, still willing
to segregate between
+../tar_texi/tar.texi(,3633) verbose output and error output. A possible
approach would be using a
+../tar_texi/tar.texi(,3634) named pipe to receive the archive, and having the
consumer process to
+../tar_texi/tar.texi(,3635) read from that named pipe. This has the advantage
of letting standard
+../tar_texi/tar.texi(,3636) output free to receive verbose output, all
separate from errors.
+../tar_texi/tar.texi(,3637)
+../tar_texi/tar.texi(,3638) @node operations
+../tar_texi/tar.texi(GNUTAR,3639) @chapter ../tar_texi/tar.texi(GNUTAR,3639)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,3639) Operations
+../tar_texi/tar.texi(,3640)
+../tar_texi/tar.texi(,3641) @menu
+../tar_texi/tar.texi(,3642) * Basic tar::
+../tar_texi/tar.texi(,3643) * Advanced tar::
+../tar_texi/tar.texi(,3644) * create options::
+../tar_texi/tar.texi(,3645) * extract options::
+../tar_texi/tar.texi(,3646) * backup::
+../tar_texi/tar.texi(,3647) * Applications::
+../tar_texi/tar.texi(,3648) * looking ahead::
+../tar_texi/tar.texi(,3649) @end menu
+../tar_texi/tar.texi(,3650)
+../tar_texi/tar.texi(,3651) @node Basic tar
+../tar_texi/tar.texi(GNUTAR,3652) @section Basic
../tar_texi/tar.texi(GNUTAR,3652) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3652) Operations
+../tar_texi/tar.texi(,3653)
+../tar_texi/tar.texi(,3654) The basic @command{tar} operations,
@option{--create} (@option{-c}),
+../tar_texi/tar.texi(,3655) @option{--list} (@option{-t}) and
@option{--extract} (@option{--get},
+../tar_texi/tar.texi(,3656) @option{-x}), are currently presented and
described in the tutorial
+../tar_texi/tar.texi(,3657) chapter of this manual. This section provides
some complementary notes
+../tar_texi/tar.texi(,3658) for these operations.
+../tar_texi/tar.texi(,3659)
+../tar_texi/tar.texi(,3660) @table @option
+../tar_texi/tar.texi(xopindex,3661) @opindex address@hidden, complementary
notes}../tar_texi/tar.texi(xopindex,3661)
+../tar_texi/tar.texi(,3662) @item --create
+../tar_texi/tar.texi(,3663) @itemx -c
+../tar_texi/tar.texi(,3664)
+../tar_texi/tar.texi(,3665) Creating an empty archive would have some kind of
elegance. One can
+../tar_texi/tar.texi(,3666) initialize an empty archive and later use
@option{--append}
+../tar_texi/tar.texi(,3667) (@option{-r}) for adding all members. Some
applications would not
+../tar_texi/tar.texi(,3668) welcome making an exception in the way of adding
the first archive
+../tar_texi/tar.texi(,3669) member. On the other hand, many people reported
that it is
+../tar_texi/tar.texi(,3670) dangerously too easy for @command{tar} to destroy
a magnetic tape with
+../tar_texi/tar.texi(,3671) an empty address@hidden is well described in
@cite{Unix-haters
+../tar_texi/tar.texi(,3672) Handbook}, by Simson Garfinkel, Daniel Weise &
Steven Strassmann, IDG
+../tar_texi/tar.texi(,3673) Books, ISBN 1-56884-203-1.}. The two most common
errors are:
+../tar_texi/tar.texi(,3674)
+../tar_texi/tar.texi(,3675) @enumerate
+../tar_texi/tar.texi(,3676) @item
+../tar_texi/tar.texi(,3677) Mistakingly using @code{create} instead of
@code{extract}, when the
+../tar_texi/tar.texi(,3678) intent was to extract the full contents of an
archive. This error
+../tar_texi/tar.texi(,3679) is likely: keys @kbd{c} and @kbd{x} are right next
to each other on
+../tar_texi/tar.texi(,3680) the QWERTY keyboard. Instead of being unpacked,
the archive then
+../tar_texi/tar.texi(,3681) gets wholly destroyed. When users speak about
@dfn{exploding} an
+../tar_texi/tar.texi(,3682) archive, they usually mean something else :-).
+../tar_texi/tar.texi(,3683)
+../tar_texi/tar.texi(,3684) @item
+../tar_texi/tar.texi(,3685) Forgetting the argument to @code{file}, when the
intent was to create
+../tar_texi/tar.texi(,3686) an archive with a single file in it. This error
is likely because a
+../tar_texi/tar.texi(,3687) tired user can easily add the @kbd{f} key to the
cluster of option
+../tar_texi/tar.texi(,3688) letters, by the mere force of habit, without
realizing the full
+../tar_texi/tar.texi(,3689) consequence of doing so. The usual consequence is
that the single
+../tar_texi/tar.texi(,3690) file, which was meant to be saved, is rather
destroyed.
+../tar_texi/tar.texi(,3691) @end enumerate
+../tar_texi/tar.texi(,3692)
+../tar_texi/tar.texi(,3693) So, recognizing the likelihood and the
catastrophical nature of these
+../tar_texi/tar.texi(GNUTAR,3694) errors, ../tar_texi/tar.texi(GNUTAR,3694)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,3694) now takes some
distance from elegance, and
+../tar_texi/tar.texi(,3695) cowardly refuses to create an archive when
@option{--create} option is
+../tar_texi/tar.texi(,3696) given, there are no arguments besides options, and
+../tar_texi/tar.texi(,3697) @option{--files-from} (@option{-T}) option is
@emph{not} used. To get
+../tar_texi/tar.texi(GNUTAR,3698) around the cautiousness of
../tar_texi/tar.texi(GNUTAR,3698) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3698) and nevertheless create an
+../tar_texi/tar.texi(,3699) archive with nothing in it, one may still use, as
the value for the
+../tar_texi/tar.texi(,3700) @option{--files-from} option, a file with no names
in it, as shown in
+../tar_texi/tar.texi(,3701) the following commands:
+../tar_texi/tar.texi(,3702)
+../tar_texi/tar.texi(,3703) @smallexample
+../tar_texi/tar.texi(,3704) @kbd{tar --create --file=empty-archive.tar
--files-from=/dev/null}
+../tar_texi/tar.texi(,3705) @kbd{tar cfT empty-archive.tar /dev/null}
+../tar_texi/tar.texi(,3706) @end smallexample
+../tar_texi/tar.texi(,3707)
+../tar_texi/tar.texi(xopindex,3708) @opindex address@hidden, complementary
notes}../tar_texi/tar.texi(xopindex,3708)
+../tar_texi/tar.texi(,3709) @item --extract
+../tar_texi/tar.texi(,3710) @itemx --get
+../tar_texi/tar.texi(,3711) @itemx -x
+../tar_texi/tar.texi(,3712)
+../tar_texi/tar.texi(GNUTAR,3713) A socket is stored, within a
../tar_texi/tar.texi(GNUTAR,3713) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3713) archive, as a pipe.
+../tar_texi/tar.texi(,3714)
+../tar_texi/tar.texi(,3715) @item @option{--list} (@option{-t})
+../tar_texi/tar.texi(,3716)
+../tar_texi/tar.texi(GNUTAR,3717) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3717) now shows dates as
@samp{1996-08-30},
+../tar_texi/tar.texi(,3718) while it used to show them as @samp{Aug 30 1996}.
Preferably,
+../tar_texi/tar.texi(,3719) people should get used to ISO 8601 dates. Local
American dates should
+../tar_texi/tar.texi(,3720) be made available again with full date
localization support, once
+../tar_texi/tar.texi(,3721) ready. In the meantime, programs not being
localizable for dates
+../tar_texi/tar.texi(,3722) should prefer international dates, that's really
the way to go.
+../tar_texi/tar.texi(,3723)
+../tar_texi/tar.texi(,3724) Look up
@url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you
+../tar_texi/tar.texi(,3725) are curious, it contains a detailed explanation of
the ISO 8601 standard.
+../tar_texi/tar.texi(,3726)
+../tar_texi/tar.texi(,3727) @end table
+../tar_texi/tar.texi(,3728)
+../tar_texi/tar.texi(,3729) @node Advanced tar
+../tar_texi/tar.texi(GNUTAR,3730) @section Advanced
../tar_texi/tar.texi(GNUTAR,3730) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3730) Operations
+../tar_texi/tar.texi(,3731)
+../tar_texi/tar.texi(GNUTAR,3732) Now that you have learned the basics of
using ../tar_texi/tar.texi(GNUTAR,3732) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,3732) , you may want
+../tar_texi/tar.texi(,3733) to learn about further ways in which @command{tar}
can help you.
+../tar_texi/tar.texi(,3734)
+../tar_texi/tar.texi(,3735) This chapter presents five, more advanced
operations which you probably
+../tar_texi/tar.texi(,3736) won't use on a daily basis, but which serve more
specialized functions.
+../tar_texi/tar.texi(,3737) We also explain the different styles of options
and why you might want
+../tar_texi/tar.texi(,3738) to use one or another, or a combination of them in
your @command{tar}
+../tar_texi/tar.texi(,3739) commands. Additionally, this chapter includes
options which allow you to
+../tar_texi/tar.texi(,3740) define the output from @command{tar} more
carefully, and provide help and
+../tar_texi/tar.texi(,3741) error correction in special circumstances.
+../tar_texi/tar.texi(,3742)
+../tar_texi/tar.texi(FIXME,3744) @allow-recursion
+../tar_texi/tar.texi(FIXME,3744) @quote-arg
+../tar_texi/tar.texi(FIXME,3744)
+../tar_texi/tar.texi(,3745)
+../tar_texi/tar.texi(,3746) @menu
+../tar_texi/tar.texi(,3747) * Operations::
+../tar_texi/tar.texi(,3748) * append::
+../tar_texi/tar.texi(,3749) * update::
+../tar_texi/tar.texi(,3750) * concatenate::
+../tar_texi/tar.texi(,3751) * delete::
+../tar_texi/tar.texi(,3752) * compare::
+../tar_texi/tar.texi(,3753) @end menu
+../tar_texi/tar.texi(,3754)
+../tar_texi/tar.texi(,3755) @node Operations
+../tar_texi/tar.texi(,3756) @subsection The Five Advanced @command{tar}
Operations
+../tar_texi/tar.texi(UNREVISED,3757) @quotation
+../tar_texi/tar.texi(UNREVISED,3757) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,3757) @end quotation
+../tar_texi/tar.texi(UNREVISED,3757)
+../tar_texi/tar.texi(,3758)
+../tar_texi/tar.texi(,3759) In the last chapter, you learned about the first
three operations to
+../tar_texi/tar.texi(,3760) @command{tar}. This chapter presents the
remaining five operations to
+../tar_texi/tar.texi(,3761) @command{tar}: @option{--append},
@option{--update}, @option{--concatenate},
+../tar_texi/tar.texi(,3762) @option{--delete}, and @option{--compare}.
+../tar_texi/tar.texi(,3763)
+../tar_texi/tar.texi(,3764) You are not likely to use these operations as
frequently as those
+../tar_texi/tar.texi(,3765) covered in the last chapter; however, since they
perform specialized
+../tar_texi/tar.texi(,3766) functions, they are quite useful when you do need
to use them. We
+../tar_texi/tar.texi(,3767) will give examples using the same directory and
files that you created
+../tar_texi/tar.texi(,3768) in the last chapter. As you may recall, the
directory is called
+../tar_texi/tar.texi(,3769) @file{practice}, the files are @samp{jazz},
@samp{blues}, @samp{folk},
+../tar_texi/tar.texi(,3770) @samp{rock}, and the two archive files you created
are
+../tar_texi/tar.texi(,3771) @samp{collection.tar} and @samp{music.tar}.
+../tar_texi/tar.texi(,3772)
+../tar_texi/tar.texi(,3773) We will also use the archive files
@samp{afiles.tar} and
+../tar_texi/tar.texi(,3774) @samp{bfiles.tar}. The archive @samp{afiles.tar}
contains the members @samp{apple},
+../tar_texi/tar.texi(,3775) @samp{angst}, and @samp{aspic}; @samp{bfiles.tar}
contains the members
+../tar_texi/tar.texi(,3776) @samp{./birds}, @samp{baboon}, and @samp{./box}.
+../tar_texi/tar.texi(,3777)
+../tar_texi/tar.texi(,3778) Unless we state otherwise, all practicing you do
and examples you follow
+../tar_texi/tar.texi(,3779) in this chapter will take place in the
@file{practice} directory that
+../tar_texi/tar.texi(,3780) you created in the previous chapter; see
@ref{prepare for examples}.
+../tar_texi/tar.texi(,3781) (Below in this section, we will remind you of the
state of the examples
+../tar_texi/tar.texi(,3782) where the last chapter left them.)
+../tar_texi/tar.texi(,3783)
+../tar_texi/tar.texi(,3784) The five operations that we will cover in this
chapter are:
+../tar_texi/tar.texi(,3785)
+../tar_texi/tar.texi(,3786) @table @option
+../tar_texi/tar.texi(,3787) @item --append
+../tar_texi/tar.texi(,3788) @itemx -r
+../tar_texi/tar.texi(,3789) Add new entries to an archive that already exists.
+../tar_texi/tar.texi(,3790) @item --update
+../tar_texi/tar.texi(,3791) @itemx -r
+../tar_texi/tar.texi(,3792) Add more recent copies of archive members to the
end of an archive, if
+../tar_texi/tar.texi(,3793) they exist.
+../tar_texi/tar.texi(,3794) @item --concatenate
+../tar_texi/tar.texi(,3795) @itemx --catenate
+../tar_texi/tar.texi(,3796) @itemx -A
+../tar_texi/tar.texi(,3797) Add one or more pre-existing archives to the end
of another archive.
+../tar_texi/tar.texi(,3798) @item --delete
+../tar_texi/tar.texi(,3799) Delete items from an archive (does not work on
tapes).
+../tar_texi/tar.texi(,3800) @item --compare
+../tar_texi/tar.texi(,3801) @itemx --diff
+../tar_texi/tar.texi(,3802) @itemx -d
+../tar_texi/tar.texi(,3803) Compare archive members to their counterparts in
the file system.
+../tar_texi/tar.texi(,3804) @end table
+../tar_texi/tar.texi(,3805)
+../tar_texi/tar.texi(,3806) @node append
+../tar_texi/tar.texi(,3807) @subsection How to Add Files to Existing Archives:
@option{--append}
+../tar_texi/tar.texi(UNREVISED,3808) @quotation
+../tar_texi/tar.texi(UNREVISED,3808) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,3808) @end quotation
+../tar_texi/tar.texi(UNREVISED,3808)
+../tar_texi/tar.texi(,3809)
+../tar_texi/tar.texi(,3810) @opindex append
+../tar_texi/tar.texi(,3811) If you want to add files to an existing archive,
you don't need to
+../tar_texi/tar.texi(,3812) create a new archive; you can use
@option{--append} (@option{-r}).
+../tar_texi/tar.texi(,3813) The archive must already exist in order to use
@option{--append}. (A
+../tar_texi/tar.texi(,3814) related operation is the @option{--update}
operation; you can use this
+../tar_texi/tar.texi(,3815) to add newer versions of archive members to an
existing archive. To learn how to
+../tar_texi/tar.texi(,3816) do this with @option{--update}, @pxref{update}.)
+../tar_texi/tar.texi(,3817)
+../tar_texi/tar.texi(,3818) If you use @option{--append} to add a file that
has the same name as an
+../tar_texi/tar.texi(,3819) archive member to an archive containing that
archive member, then the
+../tar_texi/tar.texi(,3820) old member is not deleted. What does happen,
however, is somewhat
+../tar_texi/tar.texi(,3821) complex. @command{tar} @emph{allows} you to have
infinite number of files
+../tar_texi/tar.texi(,3822) with the same name. Some operations treat these
same-named members no
+../tar_texi/tar.texi(,3823) differently than any other set of archive members:
for example, if you
+../tar_texi/tar.texi(,3824) view an archive with @option{--list}
(@option{-t}), you will see all
+../tar_texi/tar.texi(,3825) of those members listed, with their data
modification times, owners, etc.
+../tar_texi/tar.texi(,3826)
+../tar_texi/tar.texi(,3827) Other operations don't deal with these members as
perfectly as you might
+../tar_texi/tar.texi(,3828) prefer; if you were to use @option{--extract} to
extract the archive,
+../tar_texi/tar.texi(,3829) only the most recently added copy of a member with
the same name as four
+../tar_texi/tar.texi(,3830) other members would end up in the working
directory. This is because
+../tar_texi/tar.texi(,3831) @option{--extract} extracts an archive in the
order the members appeared
+../tar_texi/tar.texi(,3832) in the archive; the most recently archived members
will be extracted
+../tar_texi/tar.texi(,3833) last. Additionally, an extracted member will
@emph{replace} a file of
+../tar_texi/tar.texi(,3834) the same name which existed in the directory
already, and @command{tar}
+../tar_texi/tar.texi(,3835) will not prompt you about address@hidden you give
it
+../tar_texi/tar.texi(,3836) @option{--keep-old-files} option, or the disk copy
is newer than the
+../tar_texi/tar.texi(,3837) the one in the archive and you invoke
@command{tar} with
+../tar_texi/tar.texi(,3838) @option{--keep-newer-files} option}. Thus, only
the most recently archived
+../tar_texi/tar.texi(,3839) member will end up being extracted, as it will
replace the one
+../tar_texi/tar.texi(,3840) extracted before it, and so on.
+../tar_texi/tar.texi(,3841)
+../tar_texi/tar.texi(,3842) There exists a special option that allows you to
get around this
+../tar_texi/tar.texi(,3843) behavior and extract (or list) only a particular
copy of the file.
+../tar_texi/tar.texi(,3844) This is @option{--occurrence} option. If you run
@command{tar} with
+../tar_texi/tar.texi(,3845) this option, it will extract only the first copy
of the file. You
+../tar_texi/tar.texi(,3846) may also give this option an argument specifying
the number of
+../tar_texi/tar.texi(,3847) copy to be extracted. Thus, for example if the
archive
+../tar_texi/tar.texi(,3848) @file{archive.tar} contained three copies of file
@file{myfile}, then
+../tar_texi/tar.texi(,3849) the command
+../tar_texi/tar.texi(,3850)
+../tar_texi/tar.texi(,3851) @smallexample
+../tar_texi/tar.texi(,3852) tar --extract --file archive.tar --occurrence=2
myfile
+../tar_texi/tar.texi(,3853) @end smallexample
+../tar_texi/tar.texi(,3854)
+../tar_texi/tar.texi(,3855) @noindent
+../tar_texi/tar.texi(,3856) would extract only the second copy. @xref{Option
+../tar_texi/tar.texi(,3857) Summary,---occurrence}, for the description of
@option{--occurrence}
+../tar_texi/tar.texi(,3858) option.
+../tar_texi/tar.texi(,3859)
+../tar_texi/tar.texi(FIXME,3864) @allow-recursion
+../tar_texi/tar.texi(FIXME,3864) @quote-arg
+../tar_texi/tar.texi(FIXME,3864)
+../tar_texi/tar.texi(,3865)
+../tar_texi/tar.texi(,3866) @cindex Members, replacing with other members
+../tar_texi/tar.texi(,3867) @cindex Replacing members with other members
+../tar_texi/tar.texi(,3868) If you want to replace an archive member, use
@option{--delete} to
+../tar_texi/tar.texi(,3869) delete the member you want to remove from the
archive, , and then use
+../tar_texi/tar.texi(,3870) @option{--append} to add the member you want to be
in the archive. Note
+../tar_texi/tar.texi(,3871) that you can not change the order of the archive;
the most recently
+../tar_texi/tar.texi(,3872) added member will still appear last. In this
sense, you cannot truly
+../tar_texi/tar.texi(,3873) ``replace'' one member with another. (Replacing
one member with another
+../tar_texi/tar.texi(,3874) will not work on certain types of media, such as
tapes; see @ref{delete}
+../tar_texi/tar.texi(,3875) and @ref{Media}, for more information.)
+../tar_texi/tar.texi(,3876)
+../tar_texi/tar.texi(,3877) @menu
+../tar_texi/tar.texi(,3878) * appending files:: Appending Files to
an Archive
+../tar_texi/tar.texi(,3879) * multiple::
+../tar_texi/tar.texi(,3880) @end menu
+../tar_texi/tar.texi(,3881)
+../tar_texi/tar.texi(,3882) @node appending files
+../tar_texi/tar.texi(,3883) @subsubsection Appending Files to an Archive
+../tar_texi/tar.texi(UNREVISED,3884) @quotation
+../tar_texi/tar.texi(UNREVISED,3884) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,3884) @end quotation
+../tar_texi/tar.texi(UNREVISED,3884)
+../tar_texi/tar.texi(,3885) @cindex Adding files to an Archive
+../tar_texi/tar.texi(,3886) @cindex Appending files to an Archive
+../tar_texi/tar.texi(,3887) @cindex Archives, Appending files to
+../tar_texi/tar.texi(,3888)
+../tar_texi/tar.texi(,3889) The simplest way to add a file to an already
existing archive is the
+../tar_texi/tar.texi(,3890) @option{--append} (@option{-r}) operation, which
writes specified
+../tar_texi/tar.texi(,3891) files into the archive whether or not they are
already among the
+../tar_texi/tar.texi(,3892) archived files.
+../tar_texi/tar.texi(,3893)
+../tar_texi/tar.texi(,3894) When you use @option{--append}, you @emph{must}
specify file name
+../tar_texi/tar.texi(,3895) arguments, as there is no default. If you specify
a file that already
+../tar_texi/tar.texi(,3896) exists in the archive, another copy of the file
will be added to the
+../tar_texi/tar.texi(,3897) end of the archive. As with other operations, the
member names of the
+../tar_texi/tar.texi(,3898) newly added files will be exactly the same as
their names given on the
+../tar_texi/tar.texi(,3899) command line. The @option{--verbose}
(@option{-v}) option will print
+../tar_texi/tar.texi(,3900) out the names of the files as they are written
into the archive.
+../tar_texi/tar.texi(,3901)
+../tar_texi/tar.texi(,3902) @option{--append} cannot be performed on some tape
drives, unfortunately,
+../tar_texi/tar.texi(,3903) due to deficiencies in the formats those tape
drives use. The archive
+../tar_texi/tar.texi(,3904) must be a valid @command{tar} archive, or else the
results of using this
+../tar_texi/tar.texi(,3905) operation will be unpredictable. @xref{Media}.
+../tar_texi/tar.texi(,3906)
+../tar_texi/tar.texi(,3907) To demonstrate using @option{--append} to add a
file to an archive,
+../tar_texi/tar.texi(,3908) create a file called @file{rock} in the
@file{practice} directory.
+../tar_texi/tar.texi(,3909) Make sure you are in the @file{practice}
directory. Then, run the
+../tar_texi/tar.texi(,3910) following @command{tar} command to add @file{rock}
to
+../tar_texi/tar.texi(,3911) @file{collection.tar}:
+../tar_texi/tar.texi(,3912)
+../tar_texi/tar.texi(,3913) @smallexample
+../tar_texi/tar.texi(,3914) $ @kbd{tar --append --file=collection.tar rock}
+../tar_texi/tar.texi(,3915) @end smallexample
+../tar_texi/tar.texi(,3916)
+../tar_texi/tar.texi(,3917) @noindent
+../tar_texi/tar.texi(,3918) If you now use the @option{--list} (@option{-t})
operation, you will see that
+../tar_texi/tar.texi(,3919) @file{rock} has been added to the archive:
+../tar_texi/tar.texi(,3920)
+../tar_texi/tar.texi(,3921) @smallexample
+../tar_texi/tar.texi(,3922) $ @kbd{tar --list --file=collection.tar}
+../tar_texi/tar.texi(,3923) -rw-r--r-- me user 28 1996-10-18 16:31 jazz
+../tar_texi/tar.texi(,3924) -rw-r--r-- me user 21 1996-09-23 16:44 blues
+../tar_texi/tar.texi(,3925) -rw-r--r-- me user 20 1996-09-23 16:44 folk
+../tar_texi/tar.texi(,3926) -rw-r--r-- me user 20 1996-09-23 16:44 rock
+../tar_texi/tar.texi(,3927) @end smallexample
+../tar_texi/tar.texi(,3928)
+../tar_texi/tar.texi(,3929) @node multiple
+../tar_texi/tar.texi(,3930) @subsubsection Multiple Members with the Same Name
+../tar_texi/tar.texi(,3931)
+../tar_texi/tar.texi(,3932) You can use @option{--append} (@option{-r}) to add
copies of files
+../tar_texi/tar.texi(,3933) which have been updated since the archive was
created. (However, we
+../tar_texi/tar.texi(,3934) do not recommend doing this since there is another
@command{tar}
+../tar_texi/tar.texi(,3935) option called @option{--update}; @xref{update},
for more information.
+../tar_texi/tar.texi(,3936) We describe this use of @option{--append} here for
the sake of
+../tar_texi/tar.texi(,3937) completeness.) When you extract the archive, the
older version will
+../tar_texi/tar.texi(,3938) be effectively lost. This works because files are
extracted from an
+../tar_texi/tar.texi(,3939) archive in the order in which they were archived.
Thus, when the
+../tar_texi/tar.texi(,3940) archive is extracted, a file archived later in
time will replace a
+../tar_texi/tar.texi(,3941) file of the same name which was archived earlier,
even though the
+../tar_texi/tar.texi(,3942) older version of the file will remain in the
archive unless you delete
+../tar_texi/tar.texi(,3943) all versions of the file.
+../tar_texi/tar.texi(,3944)
+../tar_texi/tar.texi(,3945) Supposing you change the file @file{blues} and
then append the changed
+../tar_texi/tar.texi(,3946) version to @file{collection.tar}. As you saw
above, the original
+../tar_texi/tar.texi(,3947) @file{blues} is in the archive
@file{collection.tar}. If you change the
+../tar_texi/tar.texi(,3948) file and append the new version of the file to the
archive, there will
+../tar_texi/tar.texi(,3949) be two copies in the archive. When you extract
the archive, the older
+../tar_texi/tar.texi(,3950) version of the file will be extracted first, and
then replaced by the
+../tar_texi/tar.texi(,3951) newer version when it is extracted.
+../tar_texi/tar.texi(,3952)
+../tar_texi/tar.texi(,3953) You can append the new, changed copy of the file
@file{blues} to the
+../tar_texi/tar.texi(,3954) archive in this way:
+../tar_texi/tar.texi(,3955)
+../tar_texi/tar.texi(,3956) @smallexample
+../tar_texi/tar.texi(,3957) $ @kbd{tar --append --verbose
--file=collection.tar blues}
+../tar_texi/tar.texi(,3958) blues
+../tar_texi/tar.texi(,3959) @end smallexample
+../tar_texi/tar.texi(,3960)
+../tar_texi/tar.texi(,3961) @noindent
+../tar_texi/tar.texi(,3962) Because you specified the @option{--verbose}
option, @command{tar} has
+../tar_texi/tar.texi(,3963) printed the name of the file being appended as it
was acted on. Now
+../tar_texi/tar.texi(,3964) list the contents of the archive:
+../tar_texi/tar.texi(,3965)
+../tar_texi/tar.texi(,3966) @smallexample
+../tar_texi/tar.texi(,3967) $ @kbd{tar --list --verbose --file=collection.tar}
+../tar_texi/tar.texi(,3968) -rw-r--r-- me user 28 1996-10-18 16:31 jazz
+../tar_texi/tar.texi(,3969) -rw-r--r-- me user 21 1996-09-23 16:44 blues
+../tar_texi/tar.texi(,3970) -rw-r--r-- me user 20 1996-09-23 16:44 folk
+../tar_texi/tar.texi(,3971) -rw-r--r-- me user 20 1996-09-23 16:44 rock
+../tar_texi/tar.texi(,3972) -rw-r--r-- me user 58 1996-10-24 18:30 blues
+../tar_texi/tar.texi(,3973) @end smallexample
+../tar_texi/tar.texi(,3974)
+../tar_texi/tar.texi(,3975) @noindent
+../tar_texi/tar.texi(,3976) The newest version of @file{blues} is now at the
end of the archive
+../tar_texi/tar.texi(,3977) (note the different creation dates and file
sizes). If you extract
+../tar_texi/tar.texi(,3978) the archive, the older version of the file
@file{blues} will be
+../tar_texi/tar.texi(,3979) replaced by the newer version. You can confirm
this by extracting
+../tar_texi/tar.texi(,3980) the archive and running @samp{ls} on the directory.
+../tar_texi/tar.texi(,3981)
+../tar_texi/tar.texi(,3982) If you wish to extract the first occurrence of the
file @file{blues}
+../tar_texi/tar.texi(,3983) from the archive, use @option{--occurrence}
option, as shown in
+../tar_texi/tar.texi(,3984) the following example:
+../tar_texi/tar.texi(,3985)
+../tar_texi/tar.texi(,3986) @smallexample
+../tar_texi/tar.texi(,3987) $ @kbd{tar --extract -vv --occurrence
--file=collection.tar blues}
+../tar_texi/tar.texi(,3988) -rw-r--r-- me user 21 1996-09-23 16:44 blues
+../tar_texi/tar.texi(,3989) @end smallexample
+../tar_texi/tar.texi(,3990)
+../tar_texi/tar.texi(,3991) @xref{Writing}, for more information on
@option{--extract} and
+../tar_texi/tar.texi(,3992) @xref{Option Summary, --occurrence}, for the
description of
+../tar_texi/tar.texi(,3993) @option{--occurrence} option.
+../tar_texi/tar.texi(,3994)
+../tar_texi/tar.texi(,3995) @node update
+../tar_texi/tar.texi(,3996) @subsection Updating an Archive
+../tar_texi/tar.texi(UNREVISED,3997) @quotation
+../tar_texi/tar.texi(UNREVISED,3997) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,3997) @end quotation
+../tar_texi/tar.texi(UNREVISED,3997)
+../tar_texi/tar.texi(,3998) @cindex Updating an archive
+../tar_texi/tar.texi(,3999)
+../tar_texi/tar.texi(,4000) @opindex update
+../tar_texi/tar.texi(,4001) In the previous section, you learned how to use
@option{--append} to
+../tar_texi/tar.texi(,4002) add a file to an existing archive. A related
operation is
+../tar_texi/tar.texi(,4003) @option{--update} (@option{-u}). The
@option{--update} operation
+../tar_texi/tar.texi(,4004) updates a @command{tar} archive by comparing the
date of the specified
+../tar_texi/tar.texi(,4005) archive members against the date of the file with
the same name. If
+../tar_texi/tar.texi(,4006) the file has been modified more recently than the
archive member, then
+../tar_texi/tar.texi(,4007) the newer version of the file is added to the
archive (as with
+../tar_texi/tar.texi(,4008) @option{--append}).
+../tar_texi/tar.texi(,4009)
+../tar_texi/tar.texi(,4010) Unfortunately, you cannot use @option{--update}
with magnetic tape drives.
+../tar_texi/tar.texi(,4011) The operation will fail.
+../tar_texi/tar.texi(,4012)
+../tar_texi/tar.texi(FIXME,4014) @allow-recursion
+../tar_texi/tar.texi(FIXME,4014) @quote-arg
+../tar_texi/tar.texi(FIXME,4014)
+../tar_texi/tar.texi(,4015)
+../tar_texi/tar.texi(,4016) Both @option{--update} and @option{--append} work
by adding to the end
+../tar_texi/tar.texi(,4017) of the archive. When you extract a file from the
archive, only the
+../tar_texi/tar.texi(,4018) version stored last will wind up in the file
system, unless you use
+../tar_texi/tar.texi(,4019) the @option{--backup} option. @xref{multiple},
for a detailed discussion.
+../tar_texi/tar.texi(,4020)
+../tar_texi/tar.texi(,4021) @menu
+../tar_texi/tar.texi(,4022) * how to update::
+../tar_texi/tar.texi(,4023) @end menu
+../tar_texi/tar.texi(,4024)
+../tar_texi/tar.texi(,4025) @node how to update
+../tar_texi/tar.texi(,4026) @subsubsection How to Update an Archive Using
@option{--update}
+../tar_texi/tar.texi(,4027)
+../tar_texi/tar.texi(,4028) You must use file name arguments with the
@option{--update}
+../tar_texi/tar.texi(,4029) (@option{-u}) operation. If you don't specify any
files,
+../tar_texi/tar.texi(,4030) @command{tar} won't act on any files and won't
tell you that it didn't
+../tar_texi/tar.texi(,4031) do anything (which may end up confusing you).
+../tar_texi/tar.texi(,4032)
+../tar_texi/tar.texi(,4033) @c note: the above parenthetical added because in
fact, this
+../tar_texi/tar.texi(,4034) @c behavior just confused the author. :-)
+../tar_texi/tar.texi(,4035)
+../tar_texi/tar.texi(,4036) To see the @option{--update} option at work,
create a new file,
+../tar_texi/tar.texi(,4037) @file{classical}, in your practice directory, and
some extra text to the
+../tar_texi/tar.texi(,4038) file @file{blues}, using any text editor. Then
invoke @command{tar} with
+../tar_texi/tar.texi(,4039) the @samp{update} operation and the
@option{--verbose} (@option{-v})
+../tar_texi/tar.texi(,4040) option specified, using the names of all the files
in the practice
+../tar_texi/tar.texi(,4041) directory as file name arguments:
+../tar_texi/tar.texi(,4042)
+../tar_texi/tar.texi(,4043) @smallexample
+../tar_texi/tar.texi(,4044) $ @kbd{tar --update -v -f collection.tar blues
folk rock classical}
+../tar_texi/tar.texi(,4045) blues
+../tar_texi/tar.texi(,4046) classical
+../tar_texi/tar.texi(,4047) $
+../tar_texi/tar.texi(,4048) @end smallexample
+../tar_texi/tar.texi(,4049)
+../tar_texi/tar.texi(,4050) @noindent
+../tar_texi/tar.texi(,4051) Because we have specified verbose mode,
@command{tar} prints out the names
+../tar_texi/tar.texi(,4052) of the files it is working on, which in this case
are the names of the
+../tar_texi/tar.texi(,4053) files that needed to be updated. If you run
@samp{tar --list} and look
+../tar_texi/tar.texi(,4054) at the archive, you will see @file{blues} and
@file{classical} at its
+../tar_texi/tar.texi(,4055) end. There will be a total of two versions of the
member @samp{blues};
+../tar_texi/tar.texi(,4056) the one at the end will be newer and larger, since
you added text before
+../tar_texi/tar.texi(,4057) updating it.
+../tar_texi/tar.texi(,4058)
+../tar_texi/tar.texi(,4059) (The reason @command{tar} does not overwrite the
older file when updating
+../tar_texi/tar.texi(,4060) it is because writing to the middle of a section
of tape is a difficult
+../tar_texi/tar.texi(,4061) process. Tapes are not designed to go backward.
@xref{Media}, for more
+../tar_texi/tar.texi(,4062) information about tapes.
+../tar_texi/tar.texi(,4063)
+../tar_texi/tar.texi(,4064) @option{--update} (@option{-u}) is not suitable
for performing backups for two
+../tar_texi/tar.texi(,4065) reasons: it does not change directory content
entries, and it
+../tar_texi/tar.texi(GNUTAR,4066) lengthens the archive every time it is used.
The ../tar_texi/tar.texi(GNUTAR,4066) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4066)
+../tar_texi/tar.texi(,4067) options intended specifically for backups are more
+../tar_texi/tar.texi(,4068) efficient. If you need to run backups, please
consult @ref{Backups}.
+../tar_texi/tar.texi(,4069)
+../tar_texi/tar.texi(,4070) @node concatenate
+../tar_texi/tar.texi(,4071) @subsection Combining Archives with
@option{--concatenate}
+../tar_texi/tar.texi(,4072)
+../tar_texi/tar.texi(,4073) @cindex Adding archives to an archive
+../tar_texi/tar.texi(,4074) @cindex Concatenating Archives
+../tar_texi/tar.texi(,4075) @opindex concatenate
+../tar_texi/tar.texi(,4076) @opindex catenate
+../tar_texi/tar.texi(,4077) @c @cindex @option{-A} described
+../tar_texi/tar.texi(,4078) Sometimes it may be convenient to add a second
archive onto the end of
+../tar_texi/tar.texi(,4079) an archive rather than adding individual files to
the archive. To add
+../tar_texi/tar.texi(,4080) one or more archives to the end of another
archive, you should use the
+../tar_texi/tar.texi(,4081) @option{--concatenate} (@option{--catenate},
@option{-A}) operation.
+../tar_texi/tar.texi(,4082)
+../tar_texi/tar.texi(,4083) To use @option{--concatenate}, give the first
archive with
+../tar_texi/tar.texi(,4084) @option{--file} option and name the rest of
archives to be
+../tar_texi/tar.texi(,4085) concatenated on the command line. The members,
and their member
+../tar_texi/tar.texi(,4086) names, will be copied verbatim from those archives
to the first one.
+../tar_texi/tar.texi(,4087) @footnote{This can cause multiple members to have
the same name, for
+../tar_texi/tar.texi(,4088) information on how this affects reading the
archive, @ref{multiple}.}
+../tar_texi/tar.texi(,4089) The new, concatenated archive will be called by
the same name as the
+../tar_texi/tar.texi(,4090) one given with the @option{--file} option. As
usual, if you omit
+../tar_texi/tar.texi(,4091) @option{--file}, @command{tar} will use the value
of the environment
+../tar_texi/tar.texi(,4092) variable @env{TAPE}, or, if this has not been set,
the default archive name.
+../tar_texi/tar.texi(,4093)
+../tar_texi/tar.texi(FIXME,4094) @allow-recursion
+../tar_texi/tar.texi(FIXME,4094) @quote-arg
+../tar_texi/tar.texi(FIXME,4094)
+../tar_texi/tar.texi(,4095)
+../tar_texi/tar.texi(,4096) To demonstrate how @option{--concatenate} works,
create two small archives
+../tar_texi/tar.texi(,4097) called @file{bluesrock.tar} and
@file{folkjazz.tar}, using the relevant
+../tar_texi/tar.texi(,4098) files from @file{practice}:
+../tar_texi/tar.texi(,4099)
+../tar_texi/tar.texi(,4100) @smallexample
+../tar_texi/tar.texi(,4101) $ @kbd{tar -cvf bluesrock.tar blues rock}
+../tar_texi/tar.texi(,4102) blues
+../tar_texi/tar.texi(,4103) rock
+../tar_texi/tar.texi(,4104) $ @kbd{tar -cvf folkjazz.tar folk jazz}
+../tar_texi/tar.texi(,4105) folk
+../tar_texi/tar.texi(,4106) jazz
+../tar_texi/tar.texi(,4107) @end smallexample
+../tar_texi/tar.texi(,4108)
+../tar_texi/tar.texi(,4109) @noindent
+../tar_texi/tar.texi(,4110) If you like, You can run @samp{tar --list} to make
sure the archives
+../tar_texi/tar.texi(,4111) contain what they are supposed to:
+../tar_texi/tar.texi(,4112)
+../tar_texi/tar.texi(,4113) @smallexample
+../tar_texi/tar.texi(,4114) $ @kbd{tar -tvf bluesrock.tar}
+../tar_texi/tar.texi(,4115) -rw-r--r-- melissa user 105 1997-01-21 19:42
blues
+../tar_texi/tar.texi(,4116) -rw-r--r-- melissa user 33 1997-01-20 15:34
rock
+../tar_texi/tar.texi(,4117) $ @kbd{tar -tvf jazzfolk.tar}
+../tar_texi/tar.texi(,4118) -rw-r--r-- melissa user 20 1996-09-23 16:44
folk
+../tar_texi/tar.texi(,4119) -rw-r--r-- melissa user 65 1997-01-30 14:15
jazz
+../tar_texi/tar.texi(,4120) @end smallexample
+../tar_texi/tar.texi(,4121)
+../tar_texi/tar.texi(,4122) We can concatenate these two archives with
@command{tar}:
+../tar_texi/tar.texi(,4123)
+../tar_texi/tar.texi(,4124) @smallexample
+../tar_texi/tar.texi(,4125) $ @kbd{cd ..}
+../tar_texi/tar.texi(,4126) $ @kbd{tar --concatenate --file=bluesrock.tar
jazzfolk.tar}
+../tar_texi/tar.texi(,4127) @end smallexample
+../tar_texi/tar.texi(,4128)
+../tar_texi/tar.texi(,4129) If you now list the contents of the
@file{bluesrock.tar}, you will see
+../tar_texi/tar.texi(,4130) that now it also contains the archive members of
@file{jazzfolk.tar}:
+../tar_texi/tar.texi(,4131)
+../tar_texi/tar.texi(,4132) @smallexample
+../tar_texi/tar.texi(,4133) $ @kbd{tar --list --file=bluesrock.tar}
+../tar_texi/tar.texi(,4134) blues
+../tar_texi/tar.texi(,4135) rock
+../tar_texi/tar.texi(,4136) folk
+../tar_texi/tar.texi(,4137) jazz
+../tar_texi/tar.texi(,4138) @end smallexample
+../tar_texi/tar.texi(,4139)
+../tar_texi/tar.texi(,4140) When you use @option{--concatenate}, the source
and target archives must
+../tar_texi/tar.texi(,4141) already exist and must have been created using
compatible format
+../tar_texi/tar.texi(,4142) parameters. Notice, that @command{tar} does not
check whether the
+../tar_texi/tar.texi(,4143) archives it concatenates have compatible formats,
it does not
+../tar_texi/tar.texi(,4144) even check if the files are really tar archives.
+../tar_texi/tar.texi(,4145)
+../tar_texi/tar.texi(,4146) Like @option{--append} (@option{-r}), this
operation cannot be performed on some
+../tar_texi/tar.texi(,4147) tape drives, due to deficiencies in the formats
those tape drives use.
+../tar_texi/tar.texi(,4148)
+../tar_texi/tar.texi(,4149) @cindex @code{concatenate} vs @command{cat}
+../tar_texi/tar.texi(,4150) @cindex @command{cat} vs @code{concatenate}
+../tar_texi/tar.texi(,4151) It may seem more intuitive to you to want or try
to use @command{cat} to
+../tar_texi/tar.texi(,4152) concatenate two archives instead of using the
@option{--concatenate}
+../tar_texi/tar.texi(,4153) operation; after all, @command{cat} is the utility
for combining files.
+../tar_texi/tar.texi(,4154)
+../tar_texi/tar.texi(,4155) However, @command{tar} archives incorporate an
end-of-file marker which
+../tar_texi/tar.texi(,4156) must be removed if the concatenated archives are
to be read properly as
+../tar_texi/tar.texi(,4157) one archive. @option{--concatenate} removes the
end-of-archive marker
+../tar_texi/tar.texi(,4158) from the target archive before each new archive is
appended. If you use
+../tar_texi/tar.texi(,4159) @command{cat} to combine the archives, the result
will not be a valid
+../tar_texi/tar.texi(,4160) @command{tar} format archive. If you need to
retrieve files from an
+../tar_texi/tar.texi(,4161) archive that was added to using the @command{cat}
utility, use the
+../tar_texi/tar.texi(,4162) @option{--ignore-zeros} (@option{-i}) option.
@xref{Ignore Zeros}, for further
+../tar_texi/tar.texi(,4163) information on dealing with archives improperly
combined using the
+../tar_texi/tar.texi(,4164) @command{cat} shell utility.
+../tar_texi/tar.texi(,4165)
+../tar_texi/tar.texi(,4166) @node delete
+../tar_texi/tar.texi(,4167) @subsection Removing Archive Members Using
@option{--delete}
+../tar_texi/tar.texi(UNREVISED,4168) @quotation
+../tar_texi/tar.texi(UNREVISED,4168) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4168) @end quotation
+../tar_texi/tar.texi(UNREVISED,4168)
+../tar_texi/tar.texi(,4169) @cindex Deleting files from an archive
+../tar_texi/tar.texi(,4170) @cindex Removing files from an archive
+../tar_texi/tar.texi(,4171)
+../tar_texi/tar.texi(,4172) @opindex delete
+../tar_texi/tar.texi(,4173) You can remove members from an archive by using
the @option{--delete}
+../tar_texi/tar.texi(,4174) option. Specify the name of the archive with
@option{--file}
+../tar_texi/tar.texi(,4175) (@option{-f}) and then specify the names of the
members to be deleted;
+../tar_texi/tar.texi(,4176) if you list no member names, nothing will be
deleted. The
+../tar_texi/tar.texi(,4177) @option{--verbose} option will cause @command{tar}
to print the names
+../tar_texi/tar.texi(,4178) of the members as they are deleted. As with
@option{--extract}, you
+../tar_texi/tar.texi(,4179) must give the exact member names when using
@samp{tar --delete}.
+../tar_texi/tar.texi(,4180) @option{--delete} will remove all versions of the
named file from the
+../tar_texi/tar.texi(,4181) archive. The @option{--delete} operation can run
very slowly.
+../tar_texi/tar.texi(,4182)
+../tar_texi/tar.texi(,4183) Unlike other operations, @option{--delete} has no
short form.
+../tar_texi/tar.texi(,4184)
+../tar_texi/tar.texi(,4185) @cindex Tapes, using @option{--delete} and
+../tar_texi/tar.texi(,4186) @cindex Deleting from tape archives
+../tar_texi/tar.texi(,4187) This operation will rewrite the archive. You can
only use
+../tar_texi/tar.texi(,4188) @option{--delete} on an archive if the archive
device allows you to
+../tar_texi/tar.texi(,4189) write to any point on the media, such as a disk;
because of this, it
+../tar_texi/tar.texi(,4190) does not work on magnetic tapes. Do not try to
delete an archive member
+../tar_texi/tar.texi(,4191) from a magnetic tape; the action will not succeed,
and you will be
+../tar_texi/tar.texi(,4192) likely to scramble the archive and damage your
tape. There is no safe
+../tar_texi/tar.texi(,4193) way (except by completely re-writing the archive)
to delete files from
+../tar_texi/tar.texi(,4194) most kinds of magnetic tape. @xref{Media}.
+../tar_texi/tar.texi(,4195)
+../tar_texi/tar.texi(,4196) To delete all versions of the file @file{blues}
from the archive
+../tar_texi/tar.texi(,4197) @file{collection.tar} in the @file{practice}
directory, make sure you
+../tar_texi/tar.texi(,4198) are in that directory, and then,
+../tar_texi/tar.texi(,4199)
+../tar_texi/tar.texi(,4200) @smallexample
+../tar_texi/tar.texi(,4201) $ @kbd{tar --list --file=collection.tar}
+../tar_texi/tar.texi(,4202) blues
+../tar_texi/tar.texi(,4203) folk
+../tar_texi/tar.texi(,4204) jazz
+../tar_texi/tar.texi(,4205) rock
+../tar_texi/tar.texi(,4206) $ @kbd{tar --delete --file=collection.tar blues}
+../tar_texi/tar.texi(,4207) $ @kbd{tar --list --file=collection.tar}
+../tar_texi/tar.texi(,4208) folk
+../tar_texi/tar.texi(,4209) jazz
+../tar_texi/tar.texi(,4210) rock
+../tar_texi/tar.texi(,4211) $
+../tar_texi/tar.texi(,4212) @end smallexample
+../tar_texi/tar.texi(,4213)
+../tar_texi/tar.texi(FIXME,4215) @allow-recursion
+../tar_texi/tar.texi(FIXME,4215) @quote-arg
+../tar_texi/tar.texi(FIXME,4215)
+../tar_texi/tar.texi(,4216)
+../tar_texi/tar.texi(,4217) The @option{--delete} option has been reported to
work properly when
+../tar_texi/tar.texi(,4218) @command{tar} acts as a filter from @code{stdin}
to @code{stdout}.
+../tar_texi/tar.texi(,4219)
+../tar_texi/tar.texi(,4220) @node compare
+../tar_texi/tar.texi(,4221) @subsection Comparing Archive Members with the
File System
+../tar_texi/tar.texi(,4222) @cindex Verifying the currency of an archive
+../tar_texi/tar.texi(UNREVISED,4223) @quotation
+../tar_texi/tar.texi(UNREVISED,4223) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4223) @end quotation
+../tar_texi/tar.texi(UNREVISED,4223)
+../tar_texi/tar.texi(,4224)
+../tar_texi/tar.texi(,4225) @opindex compare
+../tar_texi/tar.texi(,4226) The @option{--compare} (@option{-d}), or
@option{--diff} operation compares
+../tar_texi/tar.texi(,4227) specified archive members against files with the
same names, and then
+../tar_texi/tar.texi(,4228) reports differences in file size, mode, owner,
modification date and
+../tar_texi/tar.texi(,4229) contents. You should @emph{only} specify archive
member names, not file
+../tar_texi/tar.texi(,4230) names. If you do not name any members, then
@command{tar} will compare the
+../tar_texi/tar.texi(,4231) entire archive. If a file is represented in the
archive but does not
+../tar_texi/tar.texi(,4232) exist in the file system, @command{tar} reports a
difference.
+../tar_texi/tar.texi(,4233)
+../tar_texi/tar.texi(,4234) You have to specify the record size of the archive
when modifying an
+../tar_texi/tar.texi(,4235) archive with a non-default record size.
+../tar_texi/tar.texi(,4236)
+../tar_texi/tar.texi(,4237) @command{tar} ignores files in the file system
that do not have
+../tar_texi/tar.texi(,4238) corresponding members in the archive.
+../tar_texi/tar.texi(,4239)
+../tar_texi/tar.texi(,4240) The following example compares the archive members
@file{rock},
+../tar_texi/tar.texi(,4241) @file{blues} and @file{funk} in the archive
@file{bluesrock.tar} with
+../tar_texi/tar.texi(,4242) files of the same name in the file system. (Note
that there is no file,
+../tar_texi/tar.texi(,4243) @file{funk}; @command{tar} will report an error
message.)
+../tar_texi/tar.texi(,4244)
+../tar_texi/tar.texi(,4245) @smallexample
+../tar_texi/tar.texi(,4246) $ @kbd{tar --compare --file=bluesrock.tar rock
blues funk}
+../tar_texi/tar.texi(,4247) rock
+../tar_texi/tar.texi(,4248) blues
+../tar_texi/tar.texi(,4249) tar: funk not found in archive
+../tar_texi/tar.texi(,4250) @end smallexample
+../tar_texi/tar.texi(,4251)
+../tar_texi/tar.texi(,4252) The spirit behind the @option{--compare}
(@option{--diff},
+../tar_texi/tar.texi(,4253) @option{-d}) option is to check whether the
archive represents the
+../tar_texi/tar.texi(,4254) current state of files on disk, more than
validating the integrity of
+../tar_texi/tar.texi(,4255) the archive media. For this later goal,
@xref{verify}.
+../tar_texi/tar.texi(,4256)
+../tar_texi/tar.texi(,4257) @node create options
+../tar_texi/tar.texi(,4258) @section Options Used by @option{--create}
+../tar_texi/tar.texi(,4259)
+../tar_texi/tar.texi(xopindex,4260) @opindex address@hidden, additional
options}../tar_texi/tar.texi(xopindex,4260)
+../tar_texi/tar.texi(,4261) The previous chapter described the basics of how
to use
+../tar_texi/tar.texi(,4262) @option{--create} (@option{-c}) to create an
archive from a set of files.
+../tar_texi/tar.texi(,4263) @xref{create}. This section described advanced
options to be used with
+../tar_texi/tar.texi(,4264) @option{--create}.
+../tar_texi/tar.texi(,4265)
+../tar_texi/tar.texi(,4266) @menu
+../tar_texi/tar.texi(,4267) * override:: Overriding File
Metadata.
+../tar_texi/tar.texi(,4268) * Ignore Failed Read::
+../tar_texi/tar.texi(,4269) @end menu
+../tar_texi/tar.texi(,4270)
+../tar_texi/tar.texi(,4271) @node override
+../tar_texi/tar.texi(,4272) @subsection Overriding File Metadata
+../tar_texi/tar.texi(,4273)
+../tar_texi/tar.texi(,4274) As described above, a @command{tar} archive keeps,
for each member it contains,
+../tar_texi/tar.texi(,4275) its @dfn{metadata}, such as modification time,
mode and ownership of
+../tar_texi/tar.texi(GNUTAR,4276) the file. ../tar_texi/tar.texi(GNUTAR,4276)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,4276) allows to replace
these data with other values
+../tar_texi/tar.texi(,4277) when adding files to the archive. The options
described in this
+../tar_texi/tar.texi(,4278) section affect creation of archives of any type.
For POSIX archives,
+../tar_texi/tar.texi(,4279) see also @ref{PAX keywords}, for additional ways
of controlling
+../tar_texi/tar.texi(,4280) metadata, stored in the archive.
+../tar_texi/tar.texi(,4281)
+../tar_texi/tar.texi(,4282) @table @option
+../tar_texi/tar.texi(,4283) @opindex mode
+../tar_texi/tar.texi(,4284) @item address@hidden
+../tar_texi/tar.texi(,4285)
+../tar_texi/tar.texi(,4286) When adding files to an archive, @command{tar}
will use
+../tar_texi/tar.texi(,4287) @var{permissions} for the archive members, rather
than the permissions
+../tar_texi/tar.texi(,4288) from the files. @var{permissions} can be
specified either as an octal
+../tar_texi/tar.texi(,4289) number or as symbolic permissions, like with
+../tar_texi/tar.texi(,4290) @command{chmod} (@xref{File permissions,
Permissions, File
+../tar_texi/tar.texi(,4291) permissions, fileutils, @acronym{GNU} file
utilities}. This reference
+../tar_texi/tar.texi(,4292) also has useful information for those not being
overly familiar with
+../tar_texi/tar.texi(,4293) the UNIX permission system). Using latter syntax
allows for
+../tar_texi/tar.texi(,4294) more flexibility. For example, the value
@samp{a+rw} adds read and write
+../tar_texi/tar.texi(,4295) permissions for everybody, while retaining
executable bits on directories
+../tar_texi/tar.texi(,4296) or on any other file already marked as executable:
+../tar_texi/tar.texi(,4297)
+../tar_texi/tar.texi(,4298) @smallexample
+../tar_texi/tar.texi(,4299) $ @kbd{tar -c -f archive.tar --mode='a+rw' .}
+../tar_texi/tar.texi(,4300) @end smallexample
+../tar_texi/tar.texi(,4301)
+../tar_texi/tar.texi(,4302) @item address@hidden
+../tar_texi/tar.texi(,4303) @opindex mtime
+../tar_texi/tar.texi(,4304)
+../tar_texi/tar.texi(,4305) When adding files to an archive, @command{tar}
will use @var{date} as
+../tar_texi/tar.texi(,4306) the modification time of members when creating
archives, instead of
+../tar_texi/tar.texi(,4307) their actual modification times. The argument
@var{date} can be
+../tar_texi/tar.texi(,4308) either a textual date representation in almost
arbitrary format
+../tar_texi/tar.texi(,4309) (@pxref{Date input formats}) or a name of the
existing file, starting
+../tar_texi/tar.texi(,4310) with @samp{/} or @samp{.}. In the latter case,
the modification time
+../tar_texi/tar.texi(,4311) of that file will be used.
+../tar_texi/tar.texi(,4312)
+../tar_texi/tar.texi(,4313) The following example will set the modification
date to 00:00:00 UTC,
+../tar_texi/tar.texi(,4314) January 1, 1970:
+../tar_texi/tar.texi(,4315)
+../tar_texi/tar.texi(,4316) @smallexample
+../tar_texi/tar.texi(,4317) $ @kbd{tar -c -f archive.tar --mtime='1970-01-01'
.}
+../tar_texi/tar.texi(,4318) @end smallexample
+../tar_texi/tar.texi(,4319)
+../tar_texi/tar.texi(,4320) @noindent
+../tar_texi/tar.texi(GNUTAR,4321) When used with @option{--verbose}
(@pxref{verbose tutorial}) ../tar_texi/tar.texi(GNUTAR,4321) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4321)
+../tar_texi/tar.texi(,4322) will try to convert the specified date back to its
textual
+../tar_texi/tar.texi(,4323) representation and compare it with the one given
with
+../tar_texi/tar.texi(,4324) @option{--mtime} options. If the two dates
differ, @command{tar} will
+../tar_texi/tar.texi(,4325) print a warning saying what date it will use.
This is to help user
+../tar_texi/tar.texi(,4326) ensure he is using the right date.
+../tar_texi/tar.texi(,4327)
+../tar_texi/tar.texi(,4328) For example:
+../tar_texi/tar.texi(,4329)
+../tar_texi/tar.texi(,4330) @smallexample
+../tar_texi/tar.texi(,4331) $ @kbd{tar -c -f archive.tar -v --mtime=yesterday
.}
+../tar_texi/tar.texi(,4332) tar: Option --mtime: Treating date `yesterday' as
2006-06-20
+../tar_texi/tar.texi(,4333) 13:06:29.152478
+../tar_texi/tar.texi(,4334) @dots{}
+../tar_texi/tar.texi(,4335) @end smallexample
+../tar_texi/tar.texi(,4336)
+../tar_texi/tar.texi(,4337) @item address@hidden
+../tar_texi/tar.texi(,4338) @opindex owner
+../tar_texi/tar.texi(,4339)
+../tar_texi/tar.texi(,4340) Specifies that @command{tar} should use @var{user}
as the owner of members
+../tar_texi/tar.texi(,4341) when creating archives, instead of the user
associated with the source
+../tar_texi/tar.texi(,4342) file. The argument @var{user} can be either an
existing user symbolic
+../tar_texi/tar.texi(,4343) name, or a decimal numeric user ID.
+../tar_texi/tar.texi(,4344)
+../tar_texi/tar.texi(,4345) There is no value indicating a missing number, and
@samp{0} usually means
+../tar_texi/tar.texi(,4346) @code{root}. Some people like to force @samp{0}
as the value to offer in
+../tar_texi/tar.texi(,4347) their distributions for the owner of files,
because the @code{root} user is
+../tar_texi/tar.texi(,4348) anonymous anyway, so that might as well be the
owner of anonymous
+../tar_texi/tar.texi(,4349) archives. For example:
+../tar_texi/tar.texi(,4350)
+../tar_texi/tar.texi(,4351) @smallexample
+../tar_texi/tar.texi(,4352) @group
+../tar_texi/tar.texi(,4353) $ @kbd{tar -c -f archive.tar --owner=0 .}
+../tar_texi/tar.texi(,4354) # @r{Or:}
+../tar_texi/tar.texi(,4355) $ @kbd{tar -c -f archive.tar --owner=root .}
+../tar_texi/tar.texi(,4356) @end group
+../tar_texi/tar.texi(,4357) @end smallexample
+../tar_texi/tar.texi(,4358)
+../tar_texi/tar.texi(,4359) @item address@hidden
+../tar_texi/tar.texi(,4360) @opindex group
+../tar_texi/tar.texi(,4361)
+../tar_texi/tar.texi(,4362) Files added to the @command{tar} archive will have
a group id of @var{group},
+../tar_texi/tar.texi(,4363) rather than the group from the source file. The
argument @var{group}
+../tar_texi/tar.texi(,4364) can be either an existing group symbolic name, or
a decimal numeric group ID.
+../tar_texi/tar.texi(,4365) @end table
+../tar_texi/tar.texi(,4366)
+../tar_texi/tar.texi(,4367) @node Ignore Failed Read
+../tar_texi/tar.texi(,4368) @subsection Ignore Fail Read
+../tar_texi/tar.texi(,4369)
+../tar_texi/tar.texi(,4370) @table @option
+../tar_texi/tar.texi(,4371) @item --ignore-failed-read
+../tar_texi/tar.texi(,4372) @opindex ignore-failed-read
+../tar_texi/tar.texi(,4373) Do not exit with nonzero on unreadable files or
directories.
+../tar_texi/tar.texi(,4374) @end table
+../tar_texi/tar.texi(,4375)
+../tar_texi/tar.texi(,4376) @node extract options
+../tar_texi/tar.texi(,4377) @section Options Used by @option{--extract}
+../tar_texi/tar.texi(UNREVISED,4378) @quotation
+../tar_texi/tar.texi(UNREVISED,4378) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4378) @end quotation
+../tar_texi/tar.texi(UNREVISED,4378)
+../tar_texi/tar.texi(,4379)
+../tar_texi/tar.texi(xopindex,4380) @opindex address@hidden, additional
options}../tar_texi/tar.texi(xopindex,4380)
+../tar_texi/tar.texi(,4381) The previous chapter showed how to use
@option{--extract} to extract
+../tar_texi/tar.texi(,4382) an archive into the file system. Various options
cause @command{tar} to
+../tar_texi/tar.texi(,4383) extract more information than just file contents,
such as the owner,
+../tar_texi/tar.texi(,4384) the permissions, the modification date, and so
forth. This section
+../tar_texi/tar.texi(,4385) presents options to be used with
@option{--extract} when certain special
+../tar_texi/tar.texi(,4386) considerations arise. You may review the
information presented in
+../tar_texi/tar.texi(,4387) @ref{extract} for more basic information about the
+../tar_texi/tar.texi(,4388) @option{--extract} operation.
+../tar_texi/tar.texi(,4389)
+../tar_texi/tar.texi(,4390) @menu
+../tar_texi/tar.texi(,4391) * Reading:: Options to Help
Read Archives
+../tar_texi/tar.texi(,4392) * Writing:: Changing How
@command{tar} Writes Files
+../tar_texi/tar.texi(,4393) * Scarce:: Coping with Scarce
Resources
+../tar_texi/tar.texi(,4394) @end menu
+../tar_texi/tar.texi(,4395)
+../tar_texi/tar.texi(,4396) @node Reading
+../tar_texi/tar.texi(,4397) @subsection Options to Help Read Archives
+../tar_texi/tar.texi(,4398) @cindex Options when reading archives
+../tar_texi/tar.texi(UNREVISED,4399) @quotation
+../tar_texi/tar.texi(UNREVISED,4399) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4399) @end quotation
+../tar_texi/tar.texi(UNREVISED,4399)
+../tar_texi/tar.texi(,4400)
+../tar_texi/tar.texi(,4401) @cindex Reading incomplete records
+../tar_texi/tar.texi(,4402) @cindex Records, incomplete
+../tar_texi/tar.texi(,4403) @opindex read-full-records
+../tar_texi/tar.texi(,4404) Normally, @command{tar} will request data in full
record increments from
+../tar_texi/tar.texi(,4405) an archive storage device. If the device cannot
return a full record,
+../tar_texi/tar.texi(,4406) @command{tar} will report an error. However, some
devices do not always
+../tar_texi/tar.texi(,4407) return full records, or do not require the last
record of an archive to
+../tar_texi/tar.texi(,4408) be padded out to the next record boundary. To
keep reading until you
+../tar_texi/tar.texi(,4409) obtain a full record, or to accept an incomplete
record if it contains
+../tar_texi/tar.texi(,4410) an end-of-archive marker, specify the
@option{--read-full-records} (@option{-B}) option
+../tar_texi/tar.texi(,4411) in conjunction with the @option{--extract} or
@option{--list} operations.
+../tar_texi/tar.texi(,4412) @xref{Blocking}.
+../tar_texi/tar.texi(,4413)
+../tar_texi/tar.texi(,4414) The @option{--read-full-records} (@option{-B})
option is turned on by default when
+../tar_texi/tar.texi(,4415) @command{tar} reads an archive from standard
input, or from a remote
+../tar_texi/tar.texi(,4416) machine. This is because on BSD Unix systems,
attempting to read a
+../tar_texi/tar.texi(,4417) pipe returns however much happens to be in the
pipe, even if it is
+../tar_texi/tar.texi(,4418) less than was requested. If this option were not
enabled, @command{tar}
+../tar_texi/tar.texi(,4419) would fail as soon as it read an incomplete record
from the pipe.
+../tar_texi/tar.texi(,4420)
+../tar_texi/tar.texi(,4421) If you're not sure of the blocking factor of an
archive, you can
+../tar_texi/tar.texi(,4422) read the archive by specifying
@option{--read-full-records} (@option{-B}) and
+../tar_texi/tar.texi(,4423) @address@hidden (@option{-b
+../tar_texi/tar.texi(,4424) @var{512-size}}), using a blocking factor larger
than what the archive
+../tar_texi/tar.texi(,4425) uses. This lets you avoid having to determine the
blocking factor
+../tar_texi/tar.texi(,4426) of an archive. @xref{Blocking Factor}.
+../tar_texi/tar.texi(,4427)
+../tar_texi/tar.texi(,4428) @menu
+../tar_texi/tar.texi(,4429) * read full records::
+../tar_texi/tar.texi(,4430) * Ignore Zeros::
+../tar_texi/tar.texi(,4431) @end menu
+../tar_texi/tar.texi(,4432)
+../tar_texi/tar.texi(,4433) @node read full records
+../tar_texi/tar.texi(,4434) @unnumberedsubsubsec Reading Full Records
+../tar_texi/tar.texi(,4435)
+../tar_texi/tar.texi(FIXME,4436) @allow-recursion
+../tar_texi/tar.texi(FIXME,4436) @quote-arg
+../tar_texi/tar.texi(FIXME,4436)
+../tar_texi/tar.texi(,4437)
+../tar_texi/tar.texi(,4438) @table @option
+../tar_texi/tar.texi(,4439) @opindex read-full-records
+../tar_texi/tar.texi(,4440) @item --read-full-records
+../tar_texi/tar.texi(,4441) @item -B
+../tar_texi/tar.texi(,4442) Use in conjunction with @option{--extract}
(@option{--get},
+../tar_texi/tar.texi(,4443) @option{-x}) to read an archive which contains
incomplete records, or
+../tar_texi/tar.texi(,4444) one which has a blocking factor less than the one
specified.
+../tar_texi/tar.texi(,4445) @end table
+../tar_texi/tar.texi(,4446)
+../tar_texi/tar.texi(,4447) @node Ignore Zeros
+../tar_texi/tar.texi(,4448) @unnumberedsubsubsec Ignoring Blocks of Zeros
+../tar_texi/tar.texi(,4449)
+../tar_texi/tar.texi(,4450) @cindex End-of-archive blocks, ignoring
+../tar_texi/tar.texi(,4451) @cindex Ignoring end-of-archive blocks
+../tar_texi/tar.texi(,4452) @opindex ignore-zeros
+../tar_texi/tar.texi(,4453) Normally, @command{tar} stops reading when it
encounters a block of zeros
+../tar_texi/tar.texi(,4454) between file entries (which usually indicates the
end of the archive).
+../tar_texi/tar.texi(,4455) @option{--ignore-zeros} (@option{-i}) allows
@command{tar} to
+../tar_texi/tar.texi(,4456) completely read an archive which contains a block
of zeros before the
+../tar_texi/tar.texi(,4457) end (i.e., a damaged archive, or one that was
created by concatenating
+../tar_texi/tar.texi(,4458) several archives together).
+../tar_texi/tar.texi(,4459)
+../tar_texi/tar.texi(,4460) The @option{--ignore-zeros} (@option{-i}) option
is turned off by default because many
+../tar_texi/tar.texi(,4461) versions of @command{tar} write garbage after the
end-of-archive entry,
+../tar_texi/tar.texi(GNUTAR,4462) since that part of the media is never
supposed to be read. ../tar_texi/tar.texi(GNUTAR,4462) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4462)
+../tar_texi/tar.texi(,4463) does not write after the end of an archive, but
seeks to
+../tar_texi/tar.texi(,4464) maintain compatiblity among archiving utilities.
+../tar_texi/tar.texi(,4465)
+../tar_texi/tar.texi(,4466) @table @option
+../tar_texi/tar.texi(,4467) @item --ignore-zeros
+../tar_texi/tar.texi(,4468) @itemx -i
+../tar_texi/tar.texi(,4469) To ignore blocks of zeros (i.e., end-of-archive
entries) which may be
+../tar_texi/tar.texi(,4470) encountered while reading an archive. Use in
conjunction with
+../tar_texi/tar.texi(,4471) @option{--extract} or @option{--list}.
+../tar_texi/tar.texi(,4472) @end table
+../tar_texi/tar.texi(,4473)
+../tar_texi/tar.texi(,4474) @node Writing
+../tar_texi/tar.texi(,4475) @subsection Changing How @command{tar} Writes Files
+../tar_texi/tar.texi(UNREVISED,4476) @quotation
+../tar_texi/tar.texi(UNREVISED,4476) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4476) @end quotation
+../tar_texi/tar.texi(UNREVISED,4476)
+../tar_texi/tar.texi(,4477)
+../tar_texi/tar.texi(FIXME,4478) @allow-recursion
+../tar_texi/tar.texi(FIXME,4478) @quote-arg
+../tar_texi/tar.texi(FIXME,4478)
+../tar_texi/tar.texi(,4479)
+../tar_texi/tar.texi(,4480) @menu
+../tar_texi/tar.texi(,4481) * Dealing with Old Files::
+../tar_texi/tar.texi(,4482) * Overwrite Old Files::
+../tar_texi/tar.texi(,4483) * Keep Old Files::
+../tar_texi/tar.texi(,4484) * Keep Newer Files::
+../tar_texi/tar.texi(,4485) * Unlink First::
+../tar_texi/tar.texi(,4486) * Recursive Unlink::
+../tar_texi/tar.texi(,4487) * Data Modification Times::
+../tar_texi/tar.texi(,4488) * Setting Access Permissions::
+../tar_texi/tar.texi(,4489) * Directory Modification Times and Permissions::
+../tar_texi/tar.texi(,4490) * Writing to Standard Output::
+../tar_texi/tar.texi(,4491) * Writing to an External Program::
+../tar_texi/tar.texi(,4492) * remove files::
+../tar_texi/tar.texi(,4493) @end menu
+../tar_texi/tar.texi(,4494)
+../tar_texi/tar.texi(,4495) @node Dealing with Old Files
+../tar_texi/tar.texi(,4496) @unnumberedsubsubsec Options Controlling the
Overwriting of Existing Files
+../tar_texi/tar.texi(,4497)
+../tar_texi/tar.texi(xopindex,4498) @opindex address@hidden,
introduced}../tar_texi/tar.texi(xopindex,4498)
+../tar_texi/tar.texi(,4499) When extracting files, if @command{tar} discovers
that the extracted
+../tar_texi/tar.texi(,4500) file already exists, it normally replaces the file
by removing it before
+../tar_texi/tar.texi(,4501) extracting it, to prevent confusion in the
presence of hard or symbolic
+../tar_texi/tar.texi(,4502) links. (If the existing file is a symbolic link,
it is removed, not
+../tar_texi/tar.texi(,4503) followed.) However, if a directory cannot be
removed because it is
+../tar_texi/tar.texi(,4504) nonempty, @command{tar} normally overwrites its
metadata (ownership,
+../tar_texi/tar.texi(,4505) permission, etc.). The @option{--overwrite-dir}
option enables this
+../tar_texi/tar.texi(,4506) default behavior. To be more cautious and
preserve the metadata of
+../tar_texi/tar.texi(,4507) such a directory, use the
@option{--no-overwrite-dir} option.
+../tar_texi/tar.texi(,4508)
+../tar_texi/tar.texi(,4509) @cindex Overwriting old files, prevention
+../tar_texi/tar.texi(xopindex,4510) @opindex address@hidden,
introduced}../tar_texi/tar.texi(xopindex,4510)
+../tar_texi/tar.texi(,4511) To be even more cautious and prevent existing
files from being replaced, use
+../tar_texi/tar.texi(,4512) the @option{--keep-old-files} (@option{-k})
option. It causes @command{tar} to refuse
+../tar_texi/tar.texi(,4513) to replace or update a file that already exists,
i.e., a file with the
+../tar_texi/tar.texi(,4514) same name as an archive member prevents extraction
of that archive
+../tar_texi/tar.texi(,4515) member. Instead, it reports an error.
+../tar_texi/tar.texi(,4516)
+../tar_texi/tar.texi(xopindex,4517) @opindex address@hidden,
introduced}../tar_texi/tar.texi(xopindex,4517)
+../tar_texi/tar.texi(,4518) To be more aggressive about altering existing
files, use the
+../tar_texi/tar.texi(,4519) @option{--overwrite} option. It causes
@command{tar} to overwrite
+../tar_texi/tar.texi(,4520) existing files and to follow existing symbolic
links when extracting.
+../tar_texi/tar.texi(,4521)
+../tar_texi/tar.texi(,4522) @cindex Protecting old files
+../tar_texi/tar.texi(GNUTAR,4523) Some people argue that
../tar_texi/tar.texi(GNUTAR,4523) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4523) should not hesitate
+../tar_texi/tar.texi(,4524) to overwrite files with other files when
extracting. When extracting
+../tar_texi/tar.texi(,4525) a @command{tar} archive, they expect to see a
faithful copy of the
+../tar_texi/tar.texi(,4526) state of the file system when the archive was
created. It is debatable
+../tar_texi/tar.texi(,4527) that this would always be a proper behavior. For
example, suppose one
+../tar_texi/tar.texi(,4528) has an archive in which @file{usr/local} is a link
to
+../tar_texi/tar.texi(,4529) @file{usr/local2}. Since then, maybe the site
removed the link and
+../tar_texi/tar.texi(,4530) renamed the whole hierarchy from
@file{/usr/local2} to
+../tar_texi/tar.texi(,4531) @file{/usr/local}. Such things happen all the
time. I guess it would
+../tar_texi/tar.texi(GNUTAR,4532) not be welcome at all that
../tar_texi/tar.texi(GNUTAR,4532) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4532) removes the
+../tar_texi/tar.texi(,4533) whole hierarchy just to make room for the link to
be reinstated
+../tar_texi/tar.texi(,4534) (unless it @emph{also} simultaneously restores the
full
+../tar_texi/tar.texi(GNUTAR,4535) @file{/usr/local2}, of course!)
../tar_texi/tar.texi(GNUTAR,4535) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4535) is indeed
+../tar_texi/tar.texi(,4536) able to remove a whole hierarchy to reestablish a
symbolic link, for
+../tar_texi/tar.texi(,4537) example, but @emph{only if}
@option{--recursive-unlink} is specified
+../tar_texi/tar.texi(,4538) to allow this behavior. In any case, single files
are silently
+../tar_texi/tar.texi(,4539) removed.
+../tar_texi/tar.texi(,4540)
+../tar_texi/tar.texi(xopindex,4541) @opindex address@hidden,
introduced}../tar_texi/tar.texi(xopindex,4541)
+../tar_texi/tar.texi(,4542) Finally, the @option{--unlink-first} (@option{-U})
option can improve performance in
+../tar_texi/tar.texi(,4543) some cases by causing @command{tar} to remove
files unconditionally
+../tar_texi/tar.texi(,4544) before extracting them.
+../tar_texi/tar.texi(,4545)
+../tar_texi/tar.texi(,4546) @node Overwrite Old Files
+../tar_texi/tar.texi(,4547) @unnumberedsubsubsec Overwrite Old Files
+../tar_texi/tar.texi(,4548)
+../tar_texi/tar.texi(,4549) @table @option
+../tar_texi/tar.texi(,4550) @opindex overwrite
+../tar_texi/tar.texi(,4551) @item --overwrite
+../tar_texi/tar.texi(,4552) Overwrite existing files and directory metadata
when extracting files
+../tar_texi/tar.texi(,4553) from an archive.
+../tar_texi/tar.texi(,4554)
+../tar_texi/tar.texi(,4555) This causes @command{tar} to write extracted files
into the file system without
+../tar_texi/tar.texi(,4556) regard to the files already on the system; i.e.,
files with the same
+../tar_texi/tar.texi(,4557) names as archive members are overwritten when the
archive is extracted.
+../tar_texi/tar.texi(,4558) It also causes @command{tar} to extract the
ownership, permissions,
+../tar_texi/tar.texi(,4559) and time stamps onto any preexisting files or
directories.
+../tar_texi/tar.texi(,4560) If the name of a corresponding file name is a
symbolic link, the file
+../tar_texi/tar.texi(,4561) pointed to by the symbolic link will be
overwritten instead of the
+../tar_texi/tar.texi(,4562) symbolic link itself (if this is possible).
Moreover, special devices,
+../tar_texi/tar.texi(,4563) empty directories and even symbolic links are
automatically removed if
+../tar_texi/tar.texi(,4564) they are in the way of extraction.
+../tar_texi/tar.texi(,4565)
+../tar_texi/tar.texi(,4566) Be careful when using the @option{--overwrite}
option, particularly when
+../tar_texi/tar.texi(,4567) combined with the @option{--absolute-names}
(@option{-P}) option, as this combination
+../tar_texi/tar.texi(,4568) can change the contents, ownership or permissions
of any file on your
+../tar_texi/tar.texi(,4569) system. Also, many systems do not take kindly to
overwriting files that
+../tar_texi/tar.texi(,4570) are currently being executed.
+../tar_texi/tar.texi(,4571)
+../tar_texi/tar.texi(,4572) @opindex overwrite-dir
+../tar_texi/tar.texi(,4573) @item --overwrite-dir
+../tar_texi/tar.texi(,4574) Overwrite the metadata of directories when
extracting files from an
+../tar_texi/tar.texi(,4575) archive, but remove other files before extracting.
+../tar_texi/tar.texi(,4576) @end table
+../tar_texi/tar.texi(,4577)
+../tar_texi/tar.texi(,4578) @node Keep Old Files
+../tar_texi/tar.texi(,4579) @unnumberedsubsubsec Keep Old Files
+../tar_texi/tar.texi(,4580)
+../tar_texi/tar.texi(,4581) @table @option
+../tar_texi/tar.texi(,4582) @opindex keep-old-files
+../tar_texi/tar.texi(,4583) @item --keep-old-files
+../tar_texi/tar.texi(,4584) @itemx -k
+../tar_texi/tar.texi(,4585) Do not replace existing files from archive. The
+../tar_texi/tar.texi(,4586) @option{--keep-old-files} (@option{-k}) option
prevents @command{tar}
+../tar_texi/tar.texi(,4587) from replacing existing files with files with the
same name from the
+../tar_texi/tar.texi(,4588) archive. The @option{--keep-old-files} option is
meaningless with
+../tar_texi/tar.texi(,4589) @option{--list} (@option{-t}). Prevents
@command{tar} from replacing
+../tar_texi/tar.texi(,4590) files in the file system during extraction.
+../tar_texi/tar.texi(,4591) @end table
+../tar_texi/tar.texi(,4592)
+../tar_texi/tar.texi(,4593) @node Keep Newer Files
+../tar_texi/tar.texi(,4594) @unnumberedsubsubsec Keep Newer Files
+../tar_texi/tar.texi(,4595)
+../tar_texi/tar.texi(,4596) @table @option
+../tar_texi/tar.texi(,4597) @opindex keep-newer-files
+../tar_texi/tar.texi(,4598) @item --keep-newer-files
+../tar_texi/tar.texi(,4599) Do not replace existing files that are newer than
their archive
+../tar_texi/tar.texi(,4600) copies. This option is meaningless with
@option{--list} (@option{-t}).
+../tar_texi/tar.texi(,4601) @end table
+../tar_texi/tar.texi(,4602)
+../tar_texi/tar.texi(,4603) @node Unlink First
+../tar_texi/tar.texi(,4604) @unnumberedsubsubsec Unlink First
+../tar_texi/tar.texi(,4605)
+../tar_texi/tar.texi(,4606) @table @option
+../tar_texi/tar.texi(,4607) @opindex unlink-first
+../tar_texi/tar.texi(,4608) @item --unlink-first
+../tar_texi/tar.texi(,4609) @itemx -U
+../tar_texi/tar.texi(,4610) Remove files before extracting over them.
+../tar_texi/tar.texi(,4611) This can make @command{tar} run a bit faster if
you know in advance
+../tar_texi/tar.texi(,4612) that the extracted files all need to be removed.
Normally this option
+../tar_texi/tar.texi(,4613) slows @command{tar} down slightly, so it is
disabled by default.
+../tar_texi/tar.texi(,4614) @end table
+../tar_texi/tar.texi(,4615)
+../tar_texi/tar.texi(,4616) @node Recursive Unlink
+../tar_texi/tar.texi(,4617) @unnumberedsubsubsec Recursive Unlink
+../tar_texi/tar.texi(,4618)
+../tar_texi/tar.texi(,4619) @table @option
+../tar_texi/tar.texi(,4620) @opindex recursive-unlink
+../tar_texi/tar.texi(,4621) @item --recursive-unlink
+../tar_texi/tar.texi(,4622) When this option is specified, try removing files
and directory hierarchies
+../tar_texi/tar.texi(,4623) before extracting over them. @emph{This is a
dangerous option!}
+../tar_texi/tar.texi(,4624) @end table
+../tar_texi/tar.texi(,4625)
+../tar_texi/tar.texi(,4626) If you specify the @option{--recursive-unlink}
option,
+../tar_texi/tar.texi(,4627) @command{tar} removes @emph{anything} that keeps
you from extracting a file
+../tar_texi/tar.texi(,4628) as far as current permissions will allow it. This
could include removal
+../tar_texi/tar.texi(,4629) of the contents of a full directory hierarchy.
+../tar_texi/tar.texi(,4630)
+../tar_texi/tar.texi(,4631) @node Data Modification Times
+../tar_texi/tar.texi(,4632) @unnumberedsubsubsec Setting Data Modification
Times
+../tar_texi/tar.texi(,4633)
+../tar_texi/tar.texi(,4634) @cindex Data modification times of extracted files
+../tar_texi/tar.texi(,4635) @cindex Modification times of extracted files
+../tar_texi/tar.texi(,4636) Normally, @command{tar} sets the data modification
times of extracted
+../tar_texi/tar.texi(,4637) files to the corresponding times recorded for the
files in the archive, but
+../tar_texi/tar.texi(,4638) limits the permissions of extracted files by the
current @code{umask}
+../tar_texi/tar.texi(,4639) setting.
+../tar_texi/tar.texi(,4640)
+../tar_texi/tar.texi(,4641) To set the data modification times of extracted
files to the time when
+../tar_texi/tar.texi(,4642) the files were extracted, use the @option{--touch}
(@option{-m}) option in
+../tar_texi/tar.texi(,4643) conjunction with @option{--extract}
(@option{--get}, @option{-x}).
+../tar_texi/tar.texi(,4644)
+../tar_texi/tar.texi(,4645) @table @option
+../tar_texi/tar.texi(,4646) @opindex touch
+../tar_texi/tar.texi(,4647) @item --touch
+../tar_texi/tar.texi(,4648) @itemx -m
+../tar_texi/tar.texi(,4649) Sets the data modification time of extracted
archive members to the time
+../tar_texi/tar.texi(,4650) they were extracted, not the time recorded for
them in the archive.
+../tar_texi/tar.texi(,4651) Use in conjunction with @option{--extract}
(@option{--get}, @option{-x}).
+../tar_texi/tar.texi(,4652) @end table
+../tar_texi/tar.texi(,4653)
+../tar_texi/tar.texi(,4654) @node Setting Access Permissions
+../tar_texi/tar.texi(,4655) @unnumberedsubsubsec Setting Access Permissions
+../tar_texi/tar.texi(,4656)
+../tar_texi/tar.texi(,4657) @cindex Permissions of extracted files
+../tar_texi/tar.texi(,4658) @cindex Modes of extracted files
+../tar_texi/tar.texi(,4659) To set the modes (access permissions) of extracted
files to those
+../tar_texi/tar.texi(,4660) recorded for those files in the archive, use
@option{--same-permissions}
+../tar_texi/tar.texi(,4661) in conjunction with the @option{--extract}
(@option{--get},
+../tar_texi/tar.texi(,4662) @option{-x}) operation.
+../tar_texi/tar.texi(,4663)
+../tar_texi/tar.texi(,4664) @table @option
+../tar_texi/tar.texi(,4665) @opindex preserve-permissions
+../tar_texi/tar.texi(,4666) @opindex same-permissions
+../tar_texi/tar.texi(,4667) @item --preserve-permissions
+../tar_texi/tar.texi(,4668) @itemx --same-permissions
+../tar_texi/tar.texi(,4669) @c @itemx --ignore-umask
+../tar_texi/tar.texi(,4670) @itemx -p
+../tar_texi/tar.texi(,4671) Set modes of extracted archive members to those
recorded in the
+../tar_texi/tar.texi(,4672) archive, instead of current umask settings. Use
in conjunction with
+../tar_texi/tar.texi(,4673) @option{--extract} (@option{--get}, @option{-x}).
+../tar_texi/tar.texi(,4674) @end table
+../tar_texi/tar.texi(,4675)
+../tar_texi/tar.texi(,4676) @node Directory Modification Times and Permissions
+../tar_texi/tar.texi(,4677) @unnumberedsubsubsec Directory Modification Times
and Permissions
+../tar_texi/tar.texi(,4678)
+../tar_texi/tar.texi(GNUTAR,4679) After sucessfully extracting a file member,
../tar_texi/tar.texi(GNUTAR,4679) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4679) normally
+../tar_texi/tar.texi(,4680) restores its permissions and modification times,
as described in the
+../tar_texi/tar.texi(,4681) previous sections. This cannot be done for
directories, because
+../tar_texi/tar.texi(,4682) after extracting a directory @command{tar} will
almost certainly
+../tar_texi/tar.texi(,4683) extract files into that directory and this will
cause the directory
+../tar_texi/tar.texi(,4684) modification time to be updated. Moreover,
restoring that directory
+../tar_texi/tar.texi(,4685) permissions may not permit file creation within
it. Thus, restoring
+../tar_texi/tar.texi(,4686) directory permissions and modification times must
be delayed at least
+../tar_texi/tar.texi(GNUTAR,4687) until all files have been extracted into
that directory. ../tar_texi/tar.texi(GNUTAR,4687) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4687)
+../tar_texi/tar.texi(,4688) restores directories using the following approach.
+../tar_texi/tar.texi(,4689)
+../tar_texi/tar.texi(,4690) The extracted directories are created with the
mode specified in the
+../tar_texi/tar.texi(,4691) archive, as modified by the umask of the user,
which gives sufficient
+../tar_texi/tar.texi(,4692) permissions to allow file creation. The
meta-information about the
+../tar_texi/tar.texi(,4693) directory is recorded in the temporary list of
directories. When
+../tar_texi/tar.texi(GNUTAR,4694) preparing to extract next archive member,
../tar_texi/tar.texi(GNUTAR,4694) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4694) checks if the
+../tar_texi/tar.texi(,4695) directory prefix of this file contains the
remembered directory. If
+../tar_texi/tar.texi(,4696) it does not, the program assumes that all files
have been extracted
+../tar_texi/tar.texi(,4697) into that directory, restores its modification
time and permissions
+../tar_texi/tar.texi(,4698) and removes its entry from the internal list.
This approach allows
+../tar_texi/tar.texi(,4699) to correctly restore directory meta-information in
the majority of
+../tar_texi/tar.texi(,4700) cases, while keeping memory requirements
sufficiently small. It is
+../tar_texi/tar.texi(,4701) based on the fact, that most @command{tar}
archives use the predefined
+../tar_texi/tar.texi(,4702) order of members: first the directory, then all
the files and
+../tar_texi/tar.texi(,4703) subdirectories in that directory.
+../tar_texi/tar.texi(,4704)
+../tar_texi/tar.texi(,4705) However, this is not always true. The most
important exception are
+../tar_texi/tar.texi(,4706) incremental archives (@pxref{Incremental Dumps}).
The member order in
+../tar_texi/tar.texi(,4707) an incremental archive is reversed: first all
directory members are
+../tar_texi/tar.texi(,4708) stored, followed by other (non-directory) members.
So, when extracting
+../tar_texi/tar.texi(GNUTAR,4709) from incremental archives,
../tar_texi/tar.texi(GNUTAR,4709) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4709) alters the above procedure. It
+../tar_texi/tar.texi(,4710) remebers all restored directories, and restores
their meta-data
+../tar_texi/tar.texi(,4711) only after the entire archive has been processed.
Notice, that you do
+../tar_texi/tar.texi(GNUTAR,4712) not need to specity any special options for
that, as ../tar_texi/tar.texi(GNUTAR,4712) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4712)
+../tar_texi/tar.texi(,4713) automatically detects archives in incremental
format.
+../tar_texi/tar.texi(,4714)
+../tar_texi/tar.texi(,4715) There may be cases, when such processing is
required for normal archives
+../tar_texi/tar.texi(,4716) too. Consider the following example:
+../tar_texi/tar.texi(,4717)
+../tar_texi/tar.texi(,4718) @smallexample
+../tar_texi/tar.texi(,4719) @group
+../tar_texi/tar.texi(,4720) $ @kbd{tar --no-recursion -cvf archive \
+../tar_texi/tar.texi(,4721) foo foo/file1 bar bar/file foo/file2}
+../tar_texi/tar.texi(,4722) foo/
+../tar_texi/tar.texi(,4723) foo/file1
+../tar_texi/tar.texi(,4724) bar/
+../tar_texi/tar.texi(,4725) bar/file
+../tar_texi/tar.texi(,4726) foo/file2
+../tar_texi/tar.texi(,4727) @end group
+../tar_texi/tar.texi(,4728) @end smallexample
+../tar_texi/tar.texi(,4729)
+../tar_texi/tar.texi(,4730) During the normal operation, after encountering
@file{bar}
+../tar_texi/tar.texi(GNUTAR,4731) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4731) will assume that all files from
the directory @file{foo}
+../tar_texi/tar.texi(,4732) were already extracted and will therefore restore
its timestamp and
+../tar_texi/tar.texi(,4733) permission bits. However, after extracting
@file{foo/file2} the
+../tar_texi/tar.texi(,4734) directory timestamp will be offset again.
+../tar_texi/tar.texi(,4735)
+../tar_texi/tar.texi(,4736) To correctly restore directory meta-information in
such cases, use
+../tar_texi/tar.texi(,4737) @option{delay-directory-restore} command line
option:
+../tar_texi/tar.texi(,4738)
+../tar_texi/tar.texi(,4739) @table @option
+../tar_texi/tar.texi(,4740) @opindex delay-directory-restore
+../tar_texi/tar.texi(,4741) @item --delay-directory-restore
+../tar_texi/tar.texi(,4742) Delays restoring of the modification times and
permissions of extracted
+../tar_texi/tar.texi(,4743) directories until the end of extraction. This
way, correct
+../tar_texi/tar.texi(,4744) meta-information is restored even if the archive
has unusual member
+../tar_texi/tar.texi(,4745) ordering.
+../tar_texi/tar.texi(,4746)
+../tar_texi/tar.texi(,4747) @opindex no-delay-directory-restore
+../tar_texi/tar.texi(,4748) @item --no-delay-directory-restore
+../tar_texi/tar.texi(,4749) Cancel the effect of the previous
@option{--delay-directory-restore}.
+../tar_texi/tar.texi(,4750) Use this option if you have used
@option{--delay-directory-restore} in
+../tar_texi/tar.texi(,4751) @env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS})
and wish to
+../tar_texi/tar.texi(,4752) temporarily disable it.
+../tar_texi/tar.texi(,4753) @end table
+../tar_texi/tar.texi(,4754)
+../tar_texi/tar.texi(,4755) @node Writing to Standard Output
+../tar_texi/tar.texi(,4756) @unnumberedsubsubsec Writing to Standard Output
+../tar_texi/tar.texi(,4757)
+../tar_texi/tar.texi(,4758) @cindex Writing extracted files to standard output
+../tar_texi/tar.texi(,4759) @cindex Standard output, writing extracted files to
+../tar_texi/tar.texi(,4760) To write the extracted files to the standard
output, instead of
+../tar_texi/tar.texi(,4761) creating the files on the file system, use
@option{--to-stdout} (@option{-O}) in
+../tar_texi/tar.texi(,4762) conjunction with @option{--extract}
(@option{--get}, @option{-x}). This option is useful if you are
+../tar_texi/tar.texi(,4763) extracting files to send them through a pipe, and
do not need to
+../tar_texi/tar.texi(,4764) preserve them in the file system. If you extract
multiple members,
+../tar_texi/tar.texi(,4765) they appear on standard output concatenated, in
the order they are
+../tar_texi/tar.texi(,4766) found in the archive.
+../tar_texi/tar.texi(,4767)
+../tar_texi/tar.texi(,4768) @table @option
+../tar_texi/tar.texi(,4769) @opindex to-stdout
+../tar_texi/tar.texi(,4770) @item --to-stdout
+../tar_texi/tar.texi(,4771) @itemx -O
+../tar_texi/tar.texi(,4772) Writes files to the standard output. Use only in
conjunction with
+../tar_texi/tar.texi(,4773) @option{--extract} (@option{--get}, @option{-x}).
When this option is
+../tar_texi/tar.texi(,4774) used, instead of creating the files specified,
@command{tar} writes
+../tar_texi/tar.texi(,4775) the contents of the files extracted to its
standard output. This may
+../tar_texi/tar.texi(,4776) be useful if you are only extracting the files in
order to send them
+../tar_texi/tar.texi(,4777) through a pipe. This option is meaningless with
@option{--list}
+../tar_texi/tar.texi(,4778) (@option{-t}).
+../tar_texi/tar.texi(,4779) @end table
+../tar_texi/tar.texi(,4780)
+../tar_texi/tar.texi(,4781) This can be useful, for example, if you have a tar
archive containing
+../tar_texi/tar.texi(,4782) a big file and don't want to store the file on
disk before processing
+../tar_texi/tar.texi(,4783) it. You can use a command like this:
+../tar_texi/tar.texi(,4784)
+../tar_texi/tar.texi(,4785) @smallexample
+../tar_texi/tar.texi(,4786) tar -xOzf foo.tgz bigfile | process
+../tar_texi/tar.texi(,4787) @end smallexample
+../tar_texi/tar.texi(,4788)
+../tar_texi/tar.texi(,4789) or even like this if you want to process the
concatenation of the files:
+../tar_texi/tar.texi(,4790)
+../tar_texi/tar.texi(,4791) @smallexample
+../tar_texi/tar.texi(,4792) tar -xOzf foo.tgz bigfile1 bigfile2 | process
+../tar_texi/tar.texi(,4793) @end smallexample
+../tar_texi/tar.texi(,4794)
+../tar_texi/tar.texi(,4795) Hovewer, @option{--to-command} may be more
convenient for use with
+../tar_texi/tar.texi(,4796) multiple files. See the next section.
+../tar_texi/tar.texi(,4797)
+../tar_texi/tar.texi(,4798) @node Writing to an External Program
+../tar_texi/tar.texi(,4799) @unnumberedsubsubsec Writing to an External Program
+../tar_texi/tar.texi(,4800)
+../tar_texi/tar.texi(,4801) You can instruct @command{tar} to send the
contents of each extracted
+../tar_texi/tar.texi(,4802) file to the standard input of an external program:
+../tar_texi/tar.texi(,4803)
+../tar_texi/tar.texi(,4804) @table @option
+../tar_texi/tar.texi(,4805) @opindex to-command
+../tar_texi/tar.texi(,4806) @item address@hidden
+../tar_texi/tar.texi(,4807) Extract files and pipe their contents to the
standard input of
+../tar_texi/tar.texi(,4808) @var{command}. When this option is used, instead
of creating the
+../tar_texi/tar.texi(,4809) files specified, @command{tar} invokes
@var{command} and pipes the
+../tar_texi/tar.texi(,4810) contents of the files to its standard output.
@var{Command} may
+../tar_texi/tar.texi(,4811) contain command line arguments. The program is
executed via
+../tar_texi/tar.texi(,4812) @code{sh -c}. Notice, that @var{command} is
executed once for each regular file
+../tar_texi/tar.texi(,4813) extracted. Non-regular files (directories, etc.)
are ignored when this
+../tar_texi/tar.texi(,4814) option is used.
+../tar_texi/tar.texi(,4815) @end table
+../tar_texi/tar.texi(,4816)
+../tar_texi/tar.texi(,4817) The command can obtain the information about the
file it processes
+../tar_texi/tar.texi(,4818) from the following environment variables:
+../tar_texi/tar.texi(,4819)
+../tar_texi/tar.texi(,4820) @table @var
+../tar_texi/tar.texi(,4821) @vrindex TAR_FILETYPE, to-command environment
+../tar_texi/tar.texi(,4822) @item TAR_FILETYPE
+../tar_texi/tar.texi(,4823) Type of the file. It is a single letter with the
following meaning:
+../tar_texi/tar.texi(,4824)
+../tar_texi/tar.texi(,4825) @multitable @columnfractions 0.10 0.90
+../tar_texi/tar.texi(,4826) @item f @tab Regular file
+../tar_texi/tar.texi(,4827) @item d @tab Directory
+../tar_texi/tar.texi(,4828) @item l @tab Symbolic link
+../tar_texi/tar.texi(,4829) @item h @tab Hard link
+../tar_texi/tar.texi(,4830) @item b @tab Block device
+../tar_texi/tar.texi(,4831) @item c @tab Character device
+../tar_texi/tar.texi(,4832) @end multitable
+../tar_texi/tar.texi(,4833)
+../tar_texi/tar.texi(,4834) Currently only regular files are supported.
+../tar_texi/tar.texi(,4835)
+../tar_texi/tar.texi(,4836) @vrindex TAR_MODE, to-command environment
+../tar_texi/tar.texi(,4837) @item TAR_MODE
+../tar_texi/tar.texi(,4838) File mode, an octal number.
+../tar_texi/tar.texi(,4839)
+../tar_texi/tar.texi(,4840) @vrindex TAR_FILENAME, to-command environment
+../tar_texi/tar.texi(,4841) @item TAR_FILENAME
+../tar_texi/tar.texi(,4842) The name of the file.
+../tar_texi/tar.texi(,4843)
+../tar_texi/tar.texi(,4844) @vrindex TAR_REALNAME, to-command environment
+../tar_texi/tar.texi(,4845) @item TAR_REALNAME
+../tar_texi/tar.texi(,4846) Name of the file as stored in the archive.
+../tar_texi/tar.texi(,4847)
+../tar_texi/tar.texi(,4848) @vrindex TAR_UNAME, to-command environment
+../tar_texi/tar.texi(,4849) @item TAR_UNAME
+../tar_texi/tar.texi(,4850) Name of the file owner.
+../tar_texi/tar.texi(,4851)
+../tar_texi/tar.texi(,4852) @vrindex TAR_GNAME, to-command environment
+../tar_texi/tar.texi(,4853) @item TAR_GNAME
+../tar_texi/tar.texi(,4854) Name of the file owner group.
+../tar_texi/tar.texi(,4855)
+../tar_texi/tar.texi(,4856) @vrindex TAR_ATIME, to-command environment
+../tar_texi/tar.texi(,4857) @item TAR_ATIME
+../tar_texi/tar.texi(,4858) Time of last access. It is a decimal number,
representing seconds
+../tar_texi/tar.texi(,4859) since the epoch. If the archive provides times
with nanosecond
+../tar_texi/tar.texi(,4860) precision, the nanoseconds are appended to the
timestamp after a
+../tar_texi/tar.texi(,4861) decimal point.
+../tar_texi/tar.texi(,4862)
+../tar_texi/tar.texi(,4863) @vrindex TAR_MTIME, to-command environment
+../tar_texi/tar.texi(,4864) @item TAR_MTIME
+../tar_texi/tar.texi(,4865) Time of last modification.
+../tar_texi/tar.texi(,4866)
+../tar_texi/tar.texi(,4867) @vrindex TAR_CTIME, to-command environment
+../tar_texi/tar.texi(,4868) @item TAR_CTIME
+../tar_texi/tar.texi(,4869) Time of last status change.
+../tar_texi/tar.texi(,4870)
+../tar_texi/tar.texi(,4871) @vrindex TAR_SIZE, to-command environment
+../tar_texi/tar.texi(,4872) @item TAR_SIZE
+../tar_texi/tar.texi(,4873) Size of the file.
+../tar_texi/tar.texi(,4874)
+../tar_texi/tar.texi(,4875) @vrindex TAR_UID, to-command environment
+../tar_texi/tar.texi(,4876) @item TAR_UID
+../tar_texi/tar.texi(,4877) UID of the file owner.
+../tar_texi/tar.texi(,4878)
+../tar_texi/tar.texi(,4879) @vrindex TAR_GID, to-command environment
+../tar_texi/tar.texi(,4880) @item TAR_GID
+../tar_texi/tar.texi(,4881) GID of the file owner.
+../tar_texi/tar.texi(,4882) @end table
+../tar_texi/tar.texi(,4883)
+../tar_texi/tar.texi(,4884) In addition to these variables, @env{TAR_VERSION}
contains the
+../tar_texi/tar.texi(GNUTAR,4885) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4885) version number.
+../tar_texi/tar.texi(,4886)
+../tar_texi/tar.texi(,4887) If @var{command} exits with a non-0 status,
@command{tar} will print
+../tar_texi/tar.texi(,4888) an error message similar to the following:
+../tar_texi/tar.texi(,4889)
+../tar_texi/tar.texi(,4890) @smallexample
+../tar_texi/tar.texi(,4891) tar: 2345: Child returned status 1
+../tar_texi/tar.texi(,4892) @end smallexample
+../tar_texi/tar.texi(,4893)
+../tar_texi/tar.texi(,4894) Here, @samp{2345} is the PID of the finished
process.
+../tar_texi/tar.texi(,4895)
+../tar_texi/tar.texi(,4896) If this behavior is not wanted, use
@option{--ignore-command-error}:
+../tar_texi/tar.texi(,4897)
+../tar_texi/tar.texi(,4898) @table @option
+../tar_texi/tar.texi(,4899) @opindex ignore-command-error
+../tar_texi/tar.texi(,4900) @item --ignore-command-error
+../tar_texi/tar.texi(,4901) Ignore exit codes of subprocesses. Notice that if
the program
+../tar_texi/tar.texi(,4902) exits on signal or otherwise terminates
abnormally, the error message
+../tar_texi/tar.texi(,4903) will be printed even if this option is used.
+../tar_texi/tar.texi(,4904)
+../tar_texi/tar.texi(,4905) @opindex no-ignore-command-error
+../tar_texi/tar.texi(,4906) @item --no-ignore-command-error
+../tar_texi/tar.texi(,4907) Cancel the effect of any previous
@option{--ignore-command-error}
+../tar_texi/tar.texi(,4908) option. This option is useful if you have set
+../tar_texi/tar.texi(,4909) @option{--ignore-command-error} in
@env{TAR_OPTIONS}
+../tar_texi/tar.texi(,4910) (@pxref{TAR_OPTIONS}) and wish to temporarily
cancel it.
+../tar_texi/tar.texi(,4911) @end table
+../tar_texi/tar.texi(,4912)
+../tar_texi/tar.texi(,4913) @node remove files
+../tar_texi/tar.texi(,4914) @unnumberedsubsubsec Removing Files
+../tar_texi/tar.texi(,4915)
+../tar_texi/tar.texi(FIXME,4917) @allow-recursion
+../tar_texi/tar.texi(FIXME,4917) @quote-arg
+../tar_texi/tar.texi(FIXME,4917)
+../tar_texi/tar.texi(,4918)
+../tar_texi/tar.texi(,4919) @table @option
+../tar_texi/tar.texi(,4920) @opindex remove-files
+../tar_texi/tar.texi(,4921) @item --remove-files
+../tar_texi/tar.texi(,4922) Remove files after adding them to the archive.
+../tar_texi/tar.texi(,4923) @end table
+../tar_texi/tar.texi(,4924)
+../tar_texi/tar.texi(,4925) @node Scarce
+../tar_texi/tar.texi(,4926) @subsection Coping with Scarce Resources
+../tar_texi/tar.texi(UNREVISED,4927) @quotation
+../tar_texi/tar.texi(UNREVISED,4927) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,4927) @end quotation
+../tar_texi/tar.texi(UNREVISED,4927)
+../tar_texi/tar.texi(,4928)
+../tar_texi/tar.texi(,4929) @cindex Small memory
+../tar_texi/tar.texi(,4930) @cindex Running out of space
+../tar_texi/tar.texi(,4931)
+../tar_texi/tar.texi(,4932) @menu
+../tar_texi/tar.texi(,4933) * Starting File::
+../tar_texi/tar.texi(,4934) * Same Order::
+../tar_texi/tar.texi(,4935) @end menu
+../tar_texi/tar.texi(,4936)
+../tar_texi/tar.texi(,4937) @node Starting File
+../tar_texi/tar.texi(,4938) @unnumberedsubsubsec Starting File
+../tar_texi/tar.texi(,4939)
+../tar_texi/tar.texi(,4940) @table @option
+../tar_texi/tar.texi(,4941) @opindex starting-file
+../tar_texi/tar.texi(,4942) @item address@hidden
+../tar_texi/tar.texi(,4943) @itemx -K @var{name}
+../tar_texi/tar.texi(,4944) Starts an operation in the middle of an archive.
Use in conjunction
+../tar_texi/tar.texi(,4945) with @option{--extract} (@option{--get},
@option{-x}) or @option{--list} (@option{-t}).
+../tar_texi/tar.texi(,4946) @end table
+../tar_texi/tar.texi(,4947)
+../tar_texi/tar.texi(,4948) @cindex Middle of the archive, starting in the
+../tar_texi/tar.texi(,4949) If a previous attempt to extract files failed due
to lack of disk
+../tar_texi/tar.texi(,4950) space, you can use @address@hidden (@option{-K
+../tar_texi/tar.texi(,4951) @var{name}}) to start extracting only after member
@var{name} of the
+../tar_texi/tar.texi(,4952) archive. This assumes, of course, that there is
now free space, or
+../tar_texi/tar.texi(,4953) that you are now extracting into a different file
system. (You could
+../tar_texi/tar.texi(,4954) also choose to suspend @command{tar}, remove
unnecessary files from
+../tar_texi/tar.texi(,4955) the file system, and then restart the same
@command{tar} operation.
+../tar_texi/tar.texi(,4956) In this case, @option{--starting-file} is not
necessary.
+../tar_texi/tar.texi(,4957) @xref{Incremental Dumps}, @xref{interactive}, and
@ref{exclude}.)
+../tar_texi/tar.texi(,4958)
+../tar_texi/tar.texi(,4959) @node Same Order
+../tar_texi/tar.texi(,4960) @unnumberedsubsubsec Same Order
+../tar_texi/tar.texi(,4961)
+../tar_texi/tar.texi(,4962) @table @option
+../tar_texi/tar.texi(,4963) @cindex Large lists of file names on small machines
+../tar_texi/tar.texi(,4964) @opindex same-order
+../tar_texi/tar.texi(,4965) @opindex preserve-order
+../tar_texi/tar.texi(,4966) @item --same-order
+../tar_texi/tar.texi(,4967) @itemx --preserve-order
+../tar_texi/tar.texi(,4968) @itemx -s
+../tar_texi/tar.texi(,4969) To process large lists of file names on machines
with small amounts of
+../tar_texi/tar.texi(,4970) memory. Use in conjunction with
@option{--compare} (@option{--diff},
+../tar_texi/tar.texi(,4971) @option{-d}), @option{--list} (@option{-t}) or
@option{--extract}
+../tar_texi/tar.texi(,4972) (@option{--get}, @option{-x}).
+../tar_texi/tar.texi(,4973) @end table
+../tar_texi/tar.texi(,4974)
+../tar_texi/tar.texi(,4975) The @option{--same-order}
(@option{--preserve-order}, @option{-s}) option tells @command{tar} that the
list of file
+../tar_texi/tar.texi(,4976) names to be listed or extracted is sorted in the
same order as the
+../tar_texi/tar.texi(,4977) files in the archive. This allows a large list of
names to be used,
+../tar_texi/tar.texi(,4978) even on a small machine that would not otherwise
be able to hold all
+../tar_texi/tar.texi(,4979) the names in memory at the same time. Such a
sorted list can easily be
+../tar_texi/tar.texi(,4980) created by running @samp{tar -t} on the archive
and editing its output.
+../tar_texi/tar.texi(,4981)
+../tar_texi/tar.texi(,4982) This option is probably never needed on modern
computer systems.
+../tar_texi/tar.texi(,4983)
+../tar_texi/tar.texi(,4984) @node backup
+../tar_texi/tar.texi(,4985) @section Backup options
+../tar_texi/tar.texi(,4986)
+../tar_texi/tar.texi(,4987) @cindex backup options
+../tar_texi/tar.texi(,4988)
+../tar_texi/tar.texi(GNUTAR,4989) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,4989) offers options for making
backups of files
+../tar_texi/tar.texi(,4990) before writing new versions. These options
control the details of
+../tar_texi/tar.texi(,4991) these backups. They may apply to the archive
itself before it is
+../tar_texi/tar.texi(,4992) created or rewritten, as well as individual
extracted members. Other
+../tar_texi/tar.texi(,4993) @acronym{GNU} programs (@command{cp},
@command{install}, @command{ln},
+../tar_texi/tar.texi(,4994) and @command{mv}, for example) offer similar
options.
+../tar_texi/tar.texi(,4995)
+../tar_texi/tar.texi(,4996) Backup options may prove unexpectedly useful when
extracting archives
+../tar_texi/tar.texi(,4997) containing many members having identical name, or
when extracting archives
+../tar_texi/tar.texi(,4998) on systems having file name limitations, making
different members appear
+../tar_texi/tar.texi(,4999) has having similar names through the side-effect
of name truncation.
+../tar_texi/tar.texi(,5000) (This is true only if we have a good scheme for
truncated backup names,
+../tar_texi/tar.texi(,5001) which I'm not sure at all: I suspect work is
needed in this area.)
+../tar_texi/tar.texi(,5002) When any existing file is backed up before being
overwritten by extraction,
+../tar_texi/tar.texi(,5003) then clashing files are automatically be renamed
to be unique, and the
+../tar_texi/tar.texi(,5004) true name is kept for only the last file of a
series of clashing files.
+../tar_texi/tar.texi(,5005) By using verbose mode, users may track exactly
what happens.
+../tar_texi/tar.texi(,5006)
+../tar_texi/tar.texi(,5007) At the detail level, some decisions are still
experimental, and may
+../tar_texi/tar.texi(,5008) change in the future, we are waiting comments from
our users. So, please
+../tar_texi/tar.texi(,5009) do not learn to depend blindly on the details of
the backup features.
+../tar_texi/tar.texi(,5010) For example, currently, directories themselves are
never renamed through
+../tar_texi/tar.texi(,5011) using these options, so, extracting a file over a
directory still has
+../tar_texi/tar.texi(,5012) good chances to fail. Also, backup options apply
to created archives,
+../tar_texi/tar.texi(,5013) not only to extracted members. For created
archives, backups will not
+../tar_texi/tar.texi(,5014) be attempted when the archive is a block or
character device, or when it
+../tar_texi/tar.texi(,5015) refers to a remote file.
+../tar_texi/tar.texi(,5016)
+../tar_texi/tar.texi(,5017) For the sake of simplicity and efficiency, backups
are made by renaming old
+../tar_texi/tar.texi(,5018) files prior to creation or extraction, and not by
copying. The original
+../tar_texi/tar.texi(,5019) name is restored if the file creation fails. If a
failure occurs after a
+../tar_texi/tar.texi(,5020) partial extraction of a file, both the backup and
the partially extracted
+../tar_texi/tar.texi(,5021) file are kept.
+../tar_texi/tar.texi(,5022)
+../tar_texi/tar.texi(,5023) @table @samp
+../tar_texi/tar.texi(,5024) @item address@hidden
+../tar_texi/tar.texi(,5025) @opindex backup
+../tar_texi/tar.texi(,5026) @vindex VERSION_CONTROL
+../tar_texi/tar.texi(,5027) @cindex backups
+../tar_texi/tar.texi(,5028) Back up files that are about to be overwritten or
removed.
+../tar_texi/tar.texi(,5029) Without this option, the original versions are
destroyed.
+../tar_texi/tar.texi(,5030)
+../tar_texi/tar.texi(,5031) Use @var{method} to determine the type of backups
made.
+../tar_texi/tar.texi(,5032) If @var{method} is not specified, use the value of
the @env{VERSION_CONTROL}
+../tar_texi/tar.texi(,5033) environment variable. And if
@env{VERSION_CONTROL} is not set,
+../tar_texi/tar.texi(,5034) use the @samp{existing} method.
+../tar_texi/tar.texi(,5035)
+../tar_texi/tar.texi(,5036) @vindex version-control @r{Emacs variable}
+../tar_texi/tar.texi(,5037) This option corresponds to the Emacs variable
@samp{version-control};
+../tar_texi/tar.texi(,5038) the same values for @var{method} are accepted as
in Emacs. This option
+../tar_texi/tar.texi(,5039) also allows more descriptive names. The valid
@var{method}s are:
+../tar_texi/tar.texi(,5040)
+../tar_texi/tar.texi(,5041) @table @samp
+../tar_texi/tar.texi(,5042) @item t
+../tar_texi/tar.texi(,5043) @itemx numbered
+../tar_texi/tar.texi(,5044) @cindex numbered @r{backup method}
+../tar_texi/tar.texi(,5045) Always make numbered backups.
+../tar_texi/tar.texi(,5046)
+../tar_texi/tar.texi(,5047) @item nil
+../tar_texi/tar.texi(,5048) @itemx existing
+../tar_texi/tar.texi(,5049) @cindex existing @r{backup method}
+../tar_texi/tar.texi(,5050) Make numbered backups of files that already have
them, simple backups
+../tar_texi/tar.texi(,5051) of the others.
+../tar_texi/tar.texi(,5052)
+../tar_texi/tar.texi(,5053) @item never
+../tar_texi/tar.texi(,5054) @itemx simple
+../tar_texi/tar.texi(,5055) @cindex simple @r{backup method}
+../tar_texi/tar.texi(,5056) Always make simple backups.
+../tar_texi/tar.texi(,5057)
+../tar_texi/tar.texi(,5058) @end table
+../tar_texi/tar.texi(,5059)
+../tar_texi/tar.texi(,5060) @item address@hidden
+../tar_texi/tar.texi(,5061) @opindex suffix
+../tar_texi/tar.texi(,5062) @cindex backup suffix
+../tar_texi/tar.texi(,5063) @vindex SIMPLE_BACKUP_SUFFIX
+../tar_texi/tar.texi(,5064) Append @var{suffix} to each backup file made with
@option{--backup}. If this
+../tar_texi/tar.texi(,5065) option is not specified, the value of the
@env{SIMPLE_BACKUP_SUFFIX}
+../tar_texi/tar.texi(,5066) environment variable is used. And if
@env{SIMPLE_BACKUP_SUFFIX} is not
+../tar_texi/tar.texi(,5067) set, the default is @samp{~}, just as in Emacs.
+../tar_texi/tar.texi(,5068)
+../tar_texi/tar.texi(,5069) @end table
+../tar_texi/tar.texi(,5070)
+../tar_texi/tar.texi(,5071) @node Applications
+../tar_texi/tar.texi(,5072) @section Notable @command{tar} Usages
+../tar_texi/tar.texi(UNREVISED,5073) @quotation
+../tar_texi/tar.texi(UNREVISED,5073) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,5073) @end quotation
+../tar_texi/tar.texi(UNREVISED,5073)
+../tar_texi/tar.texi(,5074)
+../tar_texi/tar.texi(FIXME,5077) @allow-recursion
+../tar_texi/tar.texi(FIXME,5077) @quote-arg
+../tar_texi/tar.texi(FIXME,5077)
+../tar_texi/tar.texi(,5078)
+../tar_texi/tar.texi(FIXME,5079) @allow-recursion
+../tar_texi/tar.texi(FIXME,5079) @quote-arg
+../tar_texi/tar.texi(FIXME,5079)
+../tar_texi/tar.texi(,5080)
+../tar_texi/tar.texi(,5081) @findex uuencode
+../tar_texi/tar.texi(,5082) You can easily use archive files to transport a
group of files from
+../tar_texi/tar.texi(,5083) one system to another: put all relevant files into
an archive on one
+../tar_texi/tar.texi(,5084) computer system, transfer the archive to another
system, and extract
+../tar_texi/tar.texi(,5085) the contents there. The basic transfer medium
might be magnetic tape,
+../tar_texi/tar.texi(,5086) Internet FTP, or even electronic mail (though you
must encode the
+../tar_texi/tar.texi(,5087) archive with @command{uuencode} in order to
transport it properly by
+../tar_texi/tar.texi(,5088) mail). Both machines do not have to use the same
operating system, as
+../tar_texi/tar.texi(,5089) long as they both support the @command{tar}
program.
+../tar_texi/tar.texi(,5090)
+../tar_texi/tar.texi(,5091) For example, here is how you might copy a
directory's contents from
+../tar_texi/tar.texi(,5092) one disk to another, while preserving the dates,
modes, owners and
+../tar_texi/tar.texi(,5093) link-structure of all the files therein. In this
case, the transfer
+../tar_texi/tar.texi(,5094) medium is a @dfn{pipe}, which is one a Unix
redirection mechanism:
+../tar_texi/tar.texi(,5095)
+../tar_texi/tar.texi(,5096) @smallexample
+../tar_texi/tar.texi(,5097) $ @kbd{(cd sourcedir; tar -cf - .) | (cd
targetdir; tar -xf -)}
+../tar_texi/tar.texi(,5098) @end smallexample
+../tar_texi/tar.texi(,5099)
+../tar_texi/tar.texi(,5100) @noindent
+../tar_texi/tar.texi(,5101) You can avoid subshells by using @option{-C}
option:
+../tar_texi/tar.texi(,5102)
+../tar_texi/tar.texi(,5103) @smallexample
+../tar_texi/tar.texi(,5104) $ @kbd{tar -C sourcedir -cf - . | tar -C targetdir
-xf -}
+../tar_texi/tar.texi(,5105) @end smallexample
+../tar_texi/tar.texi(,5106)
+../tar_texi/tar.texi(,5107) @noindent
+../tar_texi/tar.texi(,5108) The command also works using short option forms:
+../tar_texi/tar.texi(,5109)
+../tar_texi/tar.texi(,5110) @smallexample
+../tar_texi/tar.texi(,5111) $ @kbd{(cd sourcedir; tar --create --file=- . ) \
+../tar_texi/tar.texi(,5112) | (cd targetdir; tar --extract --file=-)}
+../tar_texi/tar.texi(,5113) # Or:
+../tar_texi/tar.texi(,5114) $ @kbd{tar --directory sourcedir --create --file=-
. ) \
+../tar_texi/tar.texi(,5115) | tar --directory targetdir --extract
--file=-}
+../tar_texi/tar.texi(,5116) @end smallexample
+../tar_texi/tar.texi(,5117)
+../tar_texi/tar.texi(,5118) @noindent
+../tar_texi/tar.texi(,5119) This is one of the easiest methods to transfer a
@command{tar} archive.
+../tar_texi/tar.texi(,5120)
+../tar_texi/tar.texi(,5121) @node looking ahead
+../tar_texi/tar.texi(,5122) @section Looking Ahead: The Rest of this Manual
+../tar_texi/tar.texi(,5123)
+../tar_texi/tar.texi(,5124) You have now seen how to use all eight of the
operations available to
+../tar_texi/tar.texi(,5125) @command{tar}, and a number of the possible
options. The next chapter
+../tar_texi/tar.texi(,5126) explains how to choose and change file and archive
names, how to use
+../tar_texi/tar.texi(,5127) files to store names of other files which you can
then call as
+../tar_texi/tar.texi(,5128) arguments to @command{tar} (this can help you save
time if you expect to
+../tar_texi/tar.texi(,5129) archive the same list of files a number of times),
and so forth.
+../tar_texi/tar.texi(FIXME,5133) @allow-recursion
+../tar_texi/tar.texi(FIXME,5133) @quote-arg
+../tar_texi/tar.texi(FIXME,5133)
+../tar_texi/tar.texi(,5134)
+../tar_texi/tar.texi(,5135) If there are too many files to conveniently list
on the command line,
+../tar_texi/tar.texi(,5136) you can list the names in a file, and
@command{tar} will read that file.
+../tar_texi/tar.texi(,5137) @xref{files}.
+../tar_texi/tar.texi(,5138)
+../tar_texi/tar.texi(,5139) There are various ways of causing @command{tar} to
skip over some files,
+../tar_texi/tar.texi(,5140) and not archive them. @xref{Choosing}.
+../tar_texi/tar.texi(,5141)
+../tar_texi/tar.texi(,5142) @node Backups
+../tar_texi/tar.texi(,5143) @chapter Performing Backups and Restoring Files
+../tar_texi/tar.texi(UNREVISED,5144) @quotation
+../tar_texi/tar.texi(UNREVISED,5144) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,5144) @end quotation
+../tar_texi/tar.texi(UNREVISED,5144)
+../tar_texi/tar.texi(,5145)
+../tar_texi/tar.texi(GNUTAR,5146) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,5146) is distributed along with the
scripts
+../tar_texi/tar.texi(,5147) which the Free Software Foundation uses for
performing backups. There
+../tar_texi/tar.texi(,5148) is no corresponding scripts available yet for
doing restoration of
+../tar_texi/tar.texi(,5149) files. Even if there is a good chance those
scripts may be satisfying
+../tar_texi/tar.texi(,5150) to you, they are not the only scripts or methods
available for doing
+../tar_texi/tar.texi(,5151) backups and restore. You may well create your
own, or use more
+../tar_texi/tar.texi(,5152) sophisticated packages dedicated to that purpose.
+../tar_texi/tar.texi(,5153)
+../tar_texi/tar.texi(,5154) Some users are enthusiastic about @code{Amanda}
(The Advanced Maryland
+../tar_texi/tar.texi(,5155) Automatic Network Disk Archiver), a backup system
developed by James
+../tar_texi/tar.texi(,5156) da Silva @file{jds@@cs.umd.edu} and available on
many Unix systems.
+../tar_texi/tar.texi(,5157) This is free software, and it is available at
these places:
+../tar_texi/tar.texi(,5158)
+../tar_texi/tar.texi(,5159) @smallexample
+../tar_texi/tar.texi(,5160) http://www.cs.umd.edu/projects/amanda/amanda.html
+../tar_texi/tar.texi(,5161) ftp://ftp.cs.umd.edu/pub/amanda
+../tar_texi/tar.texi(,5162) @end smallexample
+../tar_texi/tar.texi(,5163)
+../tar_texi/tar.texi(FIXME,5209) @allow-recursion
+../tar_texi/tar.texi(FIXME,5209) @quote-arg
+../tar_texi/tar.texi(FIXME,5209)
+../tar_texi/tar.texi(,5210)
+../tar_texi/tar.texi(,5211) This chapter documents both the provided shell
scripts and @command{tar}
+../tar_texi/tar.texi(,5212) options which are more specific to usage as a
backup tool.
+../tar_texi/tar.texi(,5213)
+../tar_texi/tar.texi(,5214) To @dfn{back up} a file system means to create
archives that contain
+../tar_texi/tar.texi(,5215) all the files in that file system. Those archives
can then be used to
+../tar_texi/tar.texi(,5216) restore any or all of those files (for instance if
a disk crashes or a
+../tar_texi/tar.texi(,5217) file is accidentally deleted). File system
@dfn{backups} are also
+../tar_texi/tar.texi(,5218) called @dfn{dumps}.
+../tar_texi/tar.texi(,5219)
+../tar_texi/tar.texi(,5220) @menu
+../tar_texi/tar.texi(,5221) * Full Dumps:: Using
@command{tar} to Perform Full Dumps
+../tar_texi/tar.texi(,5222) * Incremental Dumps:: Using
@command{tar} to Perform Incremental Dumps
+../tar_texi/tar.texi(,5223) * Backup Levels:: Levels of Backups
+../tar_texi/tar.texi(,5224) * Backup Parameters:: Setting Parameters
for Backups and Restoration
+../tar_texi/tar.texi(,5225) * Scripted Backups:: Using the Backup
Scripts
+../tar_texi/tar.texi(,5226) * Scripted Restoration:: Using the Restore
Script
+../tar_texi/tar.texi(,5227) @end menu
+../tar_texi/tar.texi(,5228)
+../tar_texi/tar.texi(,5229) @node Full Dumps
+../tar_texi/tar.texi(,5230) @section Using @command{tar} to Perform Full Dumps
+../tar_texi/tar.texi(UNREVISED,5231) @quotation
+../tar_texi/tar.texi(UNREVISED,5231) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,5231) @end quotation
+../tar_texi/tar.texi(UNREVISED,5231)
+../tar_texi/tar.texi(,5232)
+../tar_texi/tar.texi(,5233) @cindex full dumps
+../tar_texi/tar.texi(,5234) @cindex dumps, full
+../tar_texi/tar.texi(,5235)
+../tar_texi/tar.texi(,5236) @cindex corrupted archives
+../tar_texi/tar.texi(,5237) Full dumps should only be made when no other
people or programs
+../tar_texi/tar.texi(,5238) are modifying files in the file system. If files
are modified while
+../tar_texi/tar.texi(,5239) @command{tar} is making the backup, they may not
be stored properly in
+../tar_texi/tar.texi(,5240) the archive, in which case you won't be able to
restore them if you
+../tar_texi/tar.texi(,5241) have to. (Files not being modified are written
with no trouble, and do
+../tar_texi/tar.texi(,5242) not corrupt the entire archive.)
+../tar_texi/tar.texi(,5243)
+../tar_texi/tar.texi(,5244) You will want to use the @address@hidden
+../tar_texi/tar.texi(,5245) (@option{-V @var{archive-label}}) option to give
the archive a
+../tar_texi/tar.texi(,5246) volume label, so you can tell what this archive is
even if the label
+../tar_texi/tar.texi(,5247) falls off the tape, or anything like that.
+../tar_texi/tar.texi(,5248)
+../tar_texi/tar.texi(,5249) Unless the file system you are dumping is
guaranteed to fit on
+../tar_texi/tar.texi(,5250) one volume, you will need to use the
@option{--multi-volume} (@option{-M}) option.
+../tar_texi/tar.texi(,5251) Make sure you have enough tapes on hand to
complete the backup.
+../tar_texi/tar.texi(,5252)
+../tar_texi/tar.texi(,5253) If you want to dump each file system separately
you will need to use
+../tar_texi/tar.texi(,5254) the @option{--one-file-system} option to prevent
+../tar_texi/tar.texi(,5255) @command{tar} from crossing file system boundaries
when storing
+../tar_texi/tar.texi(,5256) (sub)directories.
+../tar_texi/tar.texi(,5257)
+../tar_texi/tar.texi(,5258) The @option{--incremental} (@option{-G})
(@pxref{Incremental Dumps})
+../tar_texi/tar.texi(,5259) option is not needed, since this is a complete
copy of everything in
+../tar_texi/tar.texi(,5260) the file system, and a full restore from this
backup would only be
+../tar_texi/tar.texi(,5261) done onto a completely
+../tar_texi/tar.texi(,5262) empty disk.
+../tar_texi/tar.texi(,5263)
+../tar_texi/tar.texi(,5264) Unless you are in a hurry, and trust the
@command{tar} program (and your
+../tar_texi/tar.texi(,5265) tapes), it is a good idea to use the
@option{--verify} (@option{-W})
+../tar_texi/tar.texi(,5266) option, to make sure your files really made it
onto the dump properly.
+../tar_texi/tar.texi(,5267) This will also detect cases where the file was
modified while (or just
+../tar_texi/tar.texi(,5268) after) it was being archived. Not all media
(notably cartridge tapes)
+../tar_texi/tar.texi(,5269) are capable of being verified, unfortunately.
+../tar_texi/tar.texi(,5270)
+../tar_texi/tar.texi(,5271) @node Incremental Dumps
+../tar_texi/tar.texi(,5272) @section Using @command{tar} to Perform
Incremental Dumps
+../tar_texi/tar.texi(,5273)
+../tar_texi/tar.texi(GNUTAR,5274) @dfn{Incremental backup} is a special form
of ../tar_texi/tar.texi(GNUTAR,5274) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,5274) archive that
+../tar_texi/tar.texi(,5275) stores additional metadata so that exact state of
the file system
+../tar_texi/tar.texi(,5276) can be restored when extracting the archive.
+../tar_texi/tar.texi(,5277)
+../tar_texi/tar.texi(GNUTAR,5278) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,5278) currently offers two options
for handling incremental
+../tar_texi/tar.texi(,5279) backups: @address@hidden (@option{-g
+../tar_texi/tar.texi(,5280) @var{snapshot-file}}) and @option{--incremental}
(@option{-G}).
+../tar_texi/tar.texi(,5281)
+../tar_texi/tar.texi(,5282) @opindex listed-incremental
+../tar_texi/tar.texi(,5283) The option @option{--listed-incremental} instructs
tar to operate on
+../tar_texi/tar.texi(,5284) an incremental archive with additional metadata
stored in a standalone
+../tar_texi/tar.texi(,5285) file, called a @dfn{snapshot file}. The purpose
of this file is to help
+../tar_texi/tar.texi(,5286) determine which files have been changed, added or
deleted since the
+../tar_texi/tar.texi(,5287) last backup, so that the next incremental backup
will contain only
+../tar_texi/tar.texi(,5288) modified files. The name of the snapshot file is
given as an argument
+../tar_texi/tar.texi(,5289) to the option:
+../tar_texi/tar.texi(,5290)
+../tar_texi/tar.texi(,5291) @table @option
+../tar_texi/tar.texi(,5292) @item address@hidden
+../tar_texi/tar.texi(,5293) @itemx -g @var{file}
+../tar_texi/tar.texi(,5294) Handle incremental backups with snapshot data in
@var{file}.
+../tar_texi/tar.texi(,5295) @end table
+../tar_texi/tar.texi(,5296)
+../tar_texi/tar.texi(,5297) To create an incremental backup, you would use
+../tar_texi/tar.texi(,5298) @option{--listed-incremental} together with
@option{--create}
+../tar_texi/tar.texi(,5299) (@pxref{create}). For example:
+../tar_texi/tar.texi(,5300)
+../tar_texi/tar.texi(,5301) @smallexample
+../tar_texi/tar.texi(,5302) $ @kbd{tar --create \
+../tar_texi/tar.texi(,5303) --file=archive.1.tar \
+../tar_texi/tar.texi(,5304) --listed-incremental=/var/log/usr.snar \
+../tar_texi/tar.texi(,5305) /usr}
+../tar_texi/tar.texi(,5306) @end smallexample
+../tar_texi/tar.texi(,5307)
+../tar_texi/tar.texi(,5308) This will create in @file{archive.1.tar} an
incremental backup of
+../tar_texi/tar.texi(,5309) the @file{/usr} file system, storing additional
metadata in the file
+../tar_texi/tar.texi(,5310) @file{/var/log/usr.snar}. If this file does not
exist, it will be
+../tar_texi/tar.texi(,5311) created. The created archive will then be a
@dfn{level 0 backup};
+../tar_texi/tar.texi(,5312) please see the next section for more on backup
levels.
+../tar_texi/tar.texi(,5313)
+../tar_texi/tar.texi(,5314) Otherwise, if the file @file{/var/log/usr.snar}
exists, it
+../tar_texi/tar.texi(,5315) determines which files are modified. In this case
only these files will be
+../tar_texi/tar.texi(,5316) stored in the archive. Suppose, for example, that
after running the
+../tar_texi/tar.texi(,5317) above command, you delete file @file{/usr/doc/old}
and create
+../tar_texi/tar.texi(,5318) directory @file{/usr/local/db} with the following
contents:
+../tar_texi/tar.texi(,5319)
+../tar_texi/tar.texi(,5320) @smallexample
+../tar_texi/tar.texi(,5321) $ @kbd{ls /usr/local/db}
+../tar_texi/tar.texi(,5322) /usr/local/db/data
+../tar_texi/tar.texi(,5323) /usr/local/db/index
+../tar_texi/tar.texi(,5324) @end smallexample
+../tar_texi/tar.texi(,5325)
+../tar_texi/tar.texi(,5326) Some time later you create another incremental
backup. You will
+../tar_texi/tar.texi(,5327) then see:
+../tar_texi/tar.texi(,5328)
+../tar_texi/tar.texi(,5329) @smallexample
+../tar_texi/tar.texi(,5330) $ @kbd{tar --create \
+../tar_texi/tar.texi(,5331) --file=archive.2.tar \
+../tar_texi/tar.texi(,5332) --listed-incremental=/var/log/usr.snar \
+../tar_texi/tar.texi(,5333) /usr}
+../tar_texi/tar.texi(,5334) tar: usr/local/db: Directory is new
+../tar_texi/tar.texi(,5335) usr/local/db/
+../tar_texi/tar.texi(,5336) usr/local/db/data
+../tar_texi/tar.texi(,5337) usr/local/db/index
+../tar_texi/tar.texi(,5338) @end smallexample
+../tar_texi/tar.texi(,5339)
+../tar_texi/tar.texi(,5340) @noindent
+../tar_texi/tar.texi(,5341) The created archive @file{archive.2.tar} will
contain only these
+../tar_texi/tar.texi(,5342) three members. This archive is called a
@dfn{level 1 backup}. Notice
+../tar_texi/tar.texi(,5343) that @file{/var/log/usr.snar} will be updated with
the new data, so if
+../tar_texi/tar.texi(,5344) you plan to create more @samp{level 1} backups, it
is necessary to
+../tar_texi/tar.texi(,5345) create a working copy of the snapshot file before
running
+../tar_texi/tar.texi(,5346) @command{tar}. The above example will then be
modified as follows:
+../tar_texi/tar.texi(,5347)
+../tar_texi/tar.texi(,5348) @smallexample
+../tar_texi/tar.texi(,5349) $ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
+../tar_texi/tar.texi(,5350) $ @kbd{tar --create \
+../tar_texi/tar.texi(,5351) --file=archive.2.tar \
+../tar_texi/tar.texi(,5352)
--listed-incremental=/var/log/usr.snar-1 \
+../tar_texi/tar.texi(,5353) /usr}
+../tar_texi/tar.texi(,5354) @end smallexample
+../tar_texi/tar.texi(,5355)
+../tar_texi/tar.texi(,5356) Incremental dumps depend crucially on time stamps,
so the results are
+../tar_texi/tar.texi(,5357) unreliable if you modify a file's time stamps
during dumping (e.g.,
+../tar_texi/tar.texi(,5358) with the @option{--atime-preserve=replace}
option), or if you set the clock
+../tar_texi/tar.texi(,5359) backwards.
+../tar_texi/tar.texi(,5360)
+../tar_texi/tar.texi(,5361) Metadata stored in snapshot files include device
numbers, which,
+../tar_texi/tar.texi(,5362) obviously is supposed to be a non-volatile value.
However, it turns
+../tar_texi/tar.texi(,5363) out that NFS devices have undependable values when
an automounter
+../tar_texi/tar.texi(,5364) gets in the picture. This can lead to a great
deal of spurious
+../tar_texi/tar.texi(,5365) redumping in incremental dumps, so it is somewhat
useless to compare
+../tar_texi/tar.texi(,5366) two NFS devices numbers over time. The solution
implemented currently
+../tar_texi/tar.texi(,5367) is to considers all NFS devices as being equal
when it comes to
+../tar_texi/tar.texi(,5368) comparing directories; this is fairly gross, but
there does not seem
+../tar_texi/tar.texi(,5369) to be a better way to go.
+../tar_texi/tar.texi(,5370)
+../tar_texi/tar.texi(,5371) Note that incremental archives use @command{tar}
extensions and may
+../tar_texi/tar.texi(,5372) not be readable by address@hidden versions of the
@command{tar} program.
+../tar_texi/tar.texi(,5373)
+../tar_texi/tar.texi(xopindex,5374) @opindex address@hidden, using with
@option{--extract}}../tar_texi/tar.texi(xopindex,5374)
+../tar_texi/tar.texi(xopindex,5375) @opindex address@hidden, using with
@option{--listed-incremental}}../tar_texi/tar.texi(xopindex,5375)
+../tar_texi/tar.texi(,5376) To extract from the incremental dumps, use
+../tar_texi/tar.texi(,5377) @option{--listed-incremental} together with
@option{--extract}
+../tar_texi/tar.texi(,5378) option (@pxref{extracting files}). In this case,
@command{tar} does
+../tar_texi/tar.texi(,5379) not need to access snapshot file, since all the
data necessary for
+../tar_texi/tar.texi(,5380) extraction are stored in the archive itself. So,
when extracting, you
+../tar_texi/tar.texi(,5381) can give whatever argument to
@option{--listed-incremental}, the usual
+../tar_texi/tar.texi(,5382) practice is to use
@option{--listed-incremental=/dev/null}.
+../tar_texi/tar.texi(,5383) Alternatively, you can use @option{--incremental},
which needs no
+../tar_texi/tar.texi(,5384) arguments. In general, @option{--incremental}
(@option{-G}) can be
+../tar_texi/tar.texi(,5385) used as a shortcut for
@option{--listed-incremental} when listing or
+../tar_texi/tar.texi(,5386) extracting incremental backups (for more
information, regarding this
+../tar_texi/tar.texi(,5387) option, @pxref{incremental-op}).
+../tar_texi/tar.texi(,5388)
+../tar_texi/tar.texi(GNUTAR,5389) When extracting from the incremental backup
../tar_texi/tar.texi(GNUTAR,5389) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,5389) attempts to
+../tar_texi/tar.texi(,5390) restore the exact state the file system had when
the archive was
+../tar_texi/tar.texi(,5391) created. In particular, it will @emph{delete}
those files in the file
+../tar_texi/tar.texi(,5392) system that did not exist in their directories
when the archive was
+../tar_texi/tar.texi(,5393) created. If you have created several levels of
incremental files,
+../tar_texi/tar.texi(,5394) then in order to restore the exact contents the
file system had when
+../tar_texi/tar.texi(,5395) the last level was created, you will need to
restore from all backups
+../tar_texi/tar.texi(,5396) in turn. Continuing our example, to restore the
state of @file{/usr}
+../tar_texi/tar.texi(,5397) file system, one would address@hidden, that since
both archives
+../tar_texi/tar.texi(,5398) were created withouth @option{-P} option
(@pxref{absolute}), these
+../tar_texi/tar.texi(,5399) commands should be run from the root file system.}:
+../tar_texi/tar.texi(,5400)
+../tar_texi/tar.texi(,5401) @smallexample
+../tar_texi/tar.texi(,5402) $ @kbd{tar --extract \
+../tar_texi/tar.texi(,5403) --listed-incremental=/dev/null \
+../tar_texi/tar.texi(,5404) --file archive.1.tar}
+../tar_texi/tar.texi(,5405) $ @kbd{tar --extract \
+../tar_texi/tar.texi(,5406) --listed-incremental=/dev/null \
+../tar_texi/tar.texi(,5407) --file archive.2.tar}
+../tar_texi/tar.texi(,5408) @end smallexample
+../tar_texi/tar.texi(,5409)
+../tar_texi/tar.texi(,5410) To list the contents of an incremental archive,
use @option{--list}
+../tar_texi/tar.texi(,5411) (@pxref{list}), as usual. To obtain more
information about the
+../tar_texi/tar.texi(,5412) archive, use @option{--listed-incremental} or
@option{--incremental}
+../tar_texi/tar.texi(,5413) combined with two @option{--verbose} address@hidden
+../tar_texi/tar.texi(,5414) @option{--verbose} options were selected to avoid
breaking usual
+../tar_texi/tar.texi(,5415) verbose listing output (@option{--list --verbose})
when using in
+../tar_texi/tar.texi(,5416) scripts.
+../tar_texi/tar.texi(,5417)
+../tar_texi/tar.texi(xopindex,5418) @opindex address@hidden, using with
@option{--list}}
+../tar_texi/tar.texi(xopindex,5419) @opindex address@hidden, using with
@option{--list}}
+../tar_texi/tar.texi(xopindex,5420) @opindex address@hidden, using with
@option{--incremental}}
+../tar_texi/tar.texi(xopindex,5421) @opindex address@hidden, using with
@option{--listed-incremental}}
+../tar_texi/tar.texi(GNUTAR,5422) Versions of @acronym{GNU} @command{tar} up
to 1.15.1 used to dump verbatim binary
+../tar_texi/tar.texi(,5423) contents of the DUMPDIR header (with terminating
nulls) when
+../tar_texi/tar.texi(,5424) @option{--incremental} or
@option{--listed-incremental} option was
+../tar_texi/tar.texi(,5425) given, no matter what the verbosity level. This
behavior, and,
+../tar_texi/tar.texi(,5426) especially, the binary output it produced were
considered incovenient
+../tar_texi/tar.texi(,5427) and were changed in version 1.16}:
+../tar_texi/tar.texi(,5428)
+../tar_texi/tar.texi(,5429) @smallexample
+../tar_texi/tar.texi(,5430) @kbd{tar --list --incremental --verbose --verbose
archive.tar}
+../tar_texi/tar.texi(,5431) @end smallexample
+../tar_texi/tar.texi(,5432)
+../tar_texi/tar.texi(,5433) This command will print, for each directory in the
archive, the list
+../tar_texi/tar.texi(,5434) of files in that directory at the time the archive
was created. This
+../tar_texi/tar.texi(,5435) information is put out in a format which is both
human-readable and
+../tar_texi/tar.texi(,5436) unambiguous for a program: each file name is
printed as
+../tar_texi/tar.texi(,5437)
+../tar_texi/tar.texi(,5438) @smallexample
+../tar_texi/tar.texi(,5439) @var{x} @var{file}
+../tar_texi/tar.texi(,5440) @end smallexample
+../tar_texi/tar.texi(,5441)
+../tar_texi/tar.texi(,5442) @noindent
+../tar_texi/tar.texi(,5443) where @var{x} is a letter describing the status of
the file: @samp{Y}
+../tar_texi/tar.texi(,5444) if the file is present in the archive, @samp{N}
if the file is not
+../tar_texi/tar.texi(,5445) included in the archive, or a @samp{D} if the file
is a directory (and
+../tar_texi/tar.texi(,5446) is included in the archive). @xref{Dumpdir}, for
the detailed
+../tar_texi/tar.texi(,5447) description of dumpdirs and status codes. Each
such
+../tar_texi/tar.texi(,5448) line is terminated by a newline character. The
last line is followed
+../tar_texi/tar.texi(,5449) by an additional newline to indicate the end of
the data.
+../tar_texi/tar.texi(,5450)
+../tar_texi/tar.texi(,5451) @anchor{incremental-op}The option
@option{--incremental} (@option{-G})
+../tar_texi/tar.texi(,5452) gives the same behavior as
@option{--listed-incremental} when used
+../tar_texi/tar.texi(,5453) with @option{--list} and @option{--extract}
options. When used with
+../tar_texi/tar.texi(,5454) @option{--create} option, it creates an
incremental archive without
+../tar_texi/tar.texi(,5455) creating snapshot file. Thus, it is impossible to
create several
+../tar_texi/tar.texi(,5456) levels of incremental backups with
@option{--incremental} option.
+../tar_texi/tar.texi(,5457)
+../tar_texi/tar.texi(,5458) @node Backup Levels
+../tar_texi/tar.texi(,5459) @section Levels of Backups
+../tar_texi/tar.texi(,5460)
+../tar_texi/tar.texi(,5461) An archive containing all the files in the file
system is called a
+../tar_texi/tar.texi(,5462) @dfn{full backup} or @dfn{full dump}. You could
insure your data by
+../tar_texi/tar.texi(,5463) creating a full dump every day. This strategy,
however, would waste a
+../tar_texi/tar.texi(,5464) substantial amount of archive media and user time,
as unchanged files
+../tar_texi/tar.texi(,5465) are daily re-archived.
+../tar_texi/tar.texi(,5466)
+../tar_texi/tar.texi(,5467) It is more efficient to do a full dump only
occasionally. To back up
+../tar_texi/tar.texi(,5468) files between full dumps, you can use
@dfn{incremental dumps}. A @dfn{level
+../tar_texi/tar.texi(,5469) one} dump archives all the files that have changed
since the last full
+../tar_texi/tar.texi(,5470) dump.
+../tar_texi/tar.texi(,5471)
+../tar_texi/tar.texi(,5472) A typical dump strategy would be to perform a full
dump once a week,
+../tar_texi/tar.texi(,5473) and a level one dump once a day. This means some
versions of files
+../tar_texi/tar.texi(,5474) will in fact be archived more than once, but this
dump strategy makes
+../tar_texi/tar.texi(,5475) it possible to restore a file system to within one
day of accuracy by
+../tar_texi/tar.texi(,5476) only extracting two archives---the last weekly
(full) dump and the
+../tar_texi/tar.texi(,5477) last daily (level one) dump. The only information
lost would be in
+../tar_texi/tar.texi(,5478) files changed or created since the last daily
backup. (Doing dumps
+../tar_texi/tar.texi(,5479) more than once a day is usually not worth the
trouble).
+../tar_texi/tar.texi(,5480)
+../tar_texi/tar.texi(GNUTAR,5481) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,5481) comes with scripts you can use
to do full
+../tar_texi/tar.texi(,5482) and level-one (actually, even level-two and so on)
dumps. Using
+../tar_texi/tar.texi(,5483) scripts (shell programs) to perform backups and
restoration is a
+../tar_texi/tar.texi(,5484) convenient and reliable alternative to typing out
file name lists
+../tar_texi/tar.texi(,5485) and @command{tar} commands by hand.
+../tar_texi/tar.texi(,5486)
+../tar_texi/tar.texi(,5487) Before you use these scripts, you need to edit the
file
+../tar_texi/tar.texi(,5488) @file{backup-specs}, which specifies parameters
used by the backup
+../tar_texi/tar.texi(,5489) scripts and by the restore script. This file is
usually located
+../tar_texi/tar.texi(,5490) in @file{/etc/backup} directory. @xref{Backup
Parameters}, for its
+../tar_texi/tar.texi(,5491) detailed description. Once the backup parameters
are set, you can
+../tar_texi/tar.texi(,5492) perform backups or restoration by running the
appropriate script.
+../tar_texi/tar.texi(,5493)
+../tar_texi/tar.texi(,5494) The name of the backup script is @code{backup}.
The name of the
+../tar_texi/tar.texi(,5495) restore script is @code{restore}. The following
sections describe
+../tar_texi/tar.texi(,5496) their use in detail.
+../tar_texi/tar.texi(,5497)
+../tar_texi/tar.texi(,5498) @emph{Please Note:} The backup and restoration
scripts are
+../tar_texi/tar.texi(,5499) designed to be used together. While it is
possible to restore files by
+../tar_texi/tar.texi(,5500) hand from an archive which was created using a
backup script, and to create
+../tar_texi/tar.texi(,5501) an archive by hand which could then be extracted
using the restore script,
+../tar_texi/tar.texi(,5502) it is easier to use the scripts.
@xref{Incremental Dumps}, before
+../tar_texi/tar.texi(,5503) making such an attempt.
+../tar_texi/tar.texi(,5504)
+../tar_texi/tar.texi(,5505) @node Backup Parameters
+../tar_texi/tar.texi(,5506) @section Setting Parameters for Backups and
Restoration
+../tar_texi/tar.texi(,5507)
+../tar_texi/tar.texi(,5508) The file @file{backup-specs} specifies backup
parameters for the
+../tar_texi/tar.texi(,5509) backup and restoration scripts provided with
@command{tar}. You must
+../tar_texi/tar.texi(,5510) edit @file{backup-specs} to fit your system
configuration and schedule
+../tar_texi/tar.texi(,5511) before using these scripts.
+../tar_texi/tar.texi(,5512)
+../tar_texi/tar.texi(,5513) Syntactically, @file{backup-specs} is a shell
script, containing
+../tar_texi/tar.texi(,5514) mainly variable assignments. However, any valid
shell construct
+../tar_texi/tar.texi(,5515) is allowed in this file. Particularly, you may
wish to define
+../tar_texi/tar.texi(,5516) functions within that script (e.g., see
@code{RESTORE_BEGIN} below).
+../tar_texi/tar.texi(,5517) For more information about shell script syntax,
please refer to
+../tar_texi/tar.texi(,5518)
@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+../tar_texi/tar.texi(,5519) g_02, the definition of the Shell Command
Language}. See also
+../tar_texi/tar.texi(,5520) @ref{Top,,Bash Features,bashref,Bash Reference
Manual}.
+../tar_texi/tar.texi(,5521)
+../tar_texi/tar.texi(,5522) The shell variables controlling behavior of
@code{backup} and
+../tar_texi/tar.texi(,5523) @code{restore} are described in the following
subsections.
+../tar_texi/tar.texi(,5524)
+../tar_texi/tar.texi(,5525) @menu
+../tar_texi/tar.texi(,5526) * General-Purpose Variables::
+../tar_texi/tar.texi(,5527) * Magnetic Tape Control::
+../tar_texi/tar.texi(,5528) * User Hooks::
+../tar_texi/tar.texi(,5529) * backup-specs example:: An Example Text of
@file{Backup-specs}
+../tar_texi/tar.texi(,5530) @end menu
+../tar_texi/tar.texi(,5531)
+../tar_texi/tar.texi(,5532) @node General-Purpose Variables
+../tar_texi/tar.texi(,5533) @subsection General-Purpose Variables
+../tar_texi/tar.texi(,5534)
+../tar_texi/tar.texi(,5535) @defvr {Backup variable} ADMINISTRATOR
+../tar_texi/tar.texi(,5536) The user name of the backup administrator.
@code{Backup} scripts
+../tar_texi/tar.texi(,5537) sends a backup report to this address.
+../tar_texi/tar.texi(,5538) @end defvr
+../tar_texi/tar.texi(,5539)
+../tar_texi/tar.texi(,5540) @defvr {Backup variable} BACKUP_HOUR
+../tar_texi/tar.texi(,5541) The hour at which the backups are done. This can
be a number from 0
+../tar_texi/tar.texi(,5542) to 23, or the time specification in form
@var{hours}:@var{minutes},
+../tar_texi/tar.texi(,5543) or the string @samp{now}.
+../tar_texi/tar.texi(,5544)
+../tar_texi/tar.texi(,5545) This variable is used by @code{backup}. Its value
may be overridden
+../tar_texi/tar.texi(,5546) using @option{--time} option (@pxref{Scripted
Backups}).
+../tar_texi/tar.texi(,5547) @end defvr
+../tar_texi/tar.texi(,5548)
+../tar_texi/tar.texi(,5549) @defvr {Backup variable} TAPE_FILE
+../tar_texi/tar.texi(,5550)
+../tar_texi/tar.texi(,5551) The device @command{tar} writes the archive to.
If @var{TAPE_FILE}
+../tar_texi/tar.texi(,5552) is a remote archive (@pxref{remote-dev}), backup
script will suppose
+../tar_texi/tar.texi(,5553) that your @command{mt} is able to access remote
devices. If @var{RSH}
+../tar_texi/tar.texi(,5554) (@pxref{RSH}) is set, @option{--rsh-command}
option will be added to
+../tar_texi/tar.texi(,5555) invocations of @command{mt}.
+../tar_texi/tar.texi(,5556) @end defvr
+../tar_texi/tar.texi(,5557)
+../tar_texi/tar.texi(,5558) @defvr {Backup variable} BLOCKING
+../tar_texi/tar.texi(,5559)
+../tar_texi/tar.texi(,5560) The blocking factor @command{tar} will use when
writing the dump archive.
+../tar_texi/tar.texi(,5561) @xref{Blocking Factor}.
+../tar_texi/tar.texi(,5562) @end defvr
+../tar_texi/tar.texi(,5563)
+../tar_texi/tar.texi(,5564) @defvr {Backup variable} BACKUP_DIRS
+../tar_texi/tar.texi(,5565)
+../tar_texi/tar.texi(,5566) A list of file systems to be dumped (for
@code{backup}), or restored
+../tar_texi/tar.texi(,5567) (for @code{restore}). You can include any
directory
+../tar_texi/tar.texi(,5568) name in the list --- subdirectories on that file
system will be
+../tar_texi/tar.texi(,5569) included, regardless of how they may look to other
networked machines.
+../tar_texi/tar.texi(,5570) Subdirectories on other file systems will be
ignored.
+../tar_texi/tar.texi(,5571)
+../tar_texi/tar.texi(,5572) The host name specifies which host to run
@command{tar} on, and should
+../tar_texi/tar.texi(,5573) normally be the host that actually contains the
file system. However,
+../tar_texi/tar.texi(GNUTAR,5574) the host machine must have
../tar_texi/tar.texi(GNUTAR,5574) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,5574) installed, and
+../tar_texi/tar.texi(,5575) must be able to access the directory containing
the backup scripts and
+../tar_texi/tar.texi(,5576) their support files using the same file name that
is used on the
+../tar_texi/tar.texi(,5577) machine where the scripts are run (i.e. what
@command{pwd} will print
+../tar_texi/tar.texi(,5578) when in that directory on that machine). If the
host that contains
+../tar_texi/tar.texi(,5579) the file system does not have this capability, you
can specify another
+../tar_texi/tar.texi(,5580) host as long as it can access the file system
through NFS.
+../tar_texi/tar.texi(,5581)
+../tar_texi/tar.texi(,5582) If the list of file systems is very long you may
wish to put it
+../tar_texi/tar.texi(,5583) in a separate file. This file is usually named
+../tar_texi/tar.texi(,5584) @file{/etc/backup/dirs}, but this name may be
overridden in
+../tar_texi/tar.texi(,5585) @file{backup-specs} using @code{DIRLIST} variable.
+../tar_texi/tar.texi(,5586) @end defvr
+../tar_texi/tar.texi(,5587)
+../tar_texi/tar.texi(,5588) @defvr {Backup variable} DIRLIST
+../tar_texi/tar.texi(,5589)
+../tar_texi/tar.texi(,5590) A path to the file containing the list of the file
systems to backup
+../tar_texi/tar.texi(,5591) or restore. By default it is
@file{/etc/backup/dirs}.
+../tar_texi/tar.texi(,5592) @end defvr
+../tar_texi/tar.texi(,5593)
+../tar_texi/tar.texi(,5594) @defvr {Backup variable} BACKUP_FILES
+../tar_texi/tar.texi(,5595)
+../tar_texi/tar.texi(,5596) A list of individual files to be dumped (for
@code{backup}), or restored
+../tar_texi/tar.texi(,5597) (for @code{restore}). These should be accessible
from the machine on
+../tar_texi/tar.texi(,5598) which the backup script is run.
+../tar_texi/tar.texi(,5599)
+../tar_texi/tar.texi(,5600) If the list of file systems is very long you may
wish to store it
+../tar_texi/tar.texi(,5601) in a separate file. This file is usually named
+../tar_texi/tar.texi(,5602) @file{/etc/backup/files}, but this name may be
overridden in
+../tar_texi/tar.texi(,5603) @file{backup-specs} using @code{FILELIST} variable.
+../tar_texi/tar.texi(,5604) @end defvr
+../tar_texi/tar.texi(,5605)
+../tar_texi/tar.texi(,5606) @defvr {Backup variable} FILELIST
+../tar_texi/tar.texi(,5607)
+../tar_texi/tar.texi(,5608) A path to the file containing the list of the
individual files to backup
+../tar_texi/tar.texi(,5609) or restore. By default it is
@file{/etc/backup/files}.
+../tar_texi/tar.texi(,5610) @end defvr
+../tar_texi/tar.texi(,5611)
+../tar_texi/tar.texi(,5612) @defvr {Backup variable} MT
+../tar_texi/tar.texi(,5613)
+../tar_texi/tar.texi(,5614) Full file name of @command{mt} binary.
+../tar_texi/tar.texi(,5615) @end defvr
+../tar_texi/tar.texi(,5616)
+../tar_texi/tar.texi(,5617) @defvr {Backup variable} RSH
+../tar_texi/tar.texi(,5618) @anchor{RSH}
+../tar_texi/tar.texi(,5619) Full file name of @command{rsh} binary or its
equivalent. You may wish to
+../tar_texi/tar.texi(,5620) set it to @code{ssh}, to improve security. In
this case you will have
+../tar_texi/tar.texi(,5621) to use public key authentication.
+../tar_texi/tar.texi(,5622) @end defvr
+../tar_texi/tar.texi(,5623)
+../tar_texi/tar.texi(,5624) @defvr {Backup variable} RSH_COMMAND
+../tar_texi/tar.texi(,5625)
+../tar_texi/tar.texi(,5626) Full file name of @command{rsh} binary on remote
mashines. This will
+../tar_texi/tar.texi(,5627) be passed via @option{--rsh-command} option to the
remote invocation
+../tar_texi/tar.texi(GNUTAR,5628) of ../tar_texi/tar.texi(GNUTAR,5628)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,5628) .
+../tar_texi/tar.texi(,5629) @end defvr
+../tar_texi/tar.texi(,5630)
+../tar_texi/tar.texi(,5631) @defvr {Backup variable} VOLNO_FILE
+../tar_texi/tar.texi(,5632)
+../tar_texi/tar.texi(,5633) Name of temporary file to hold volume numbers.
This needs to be accessible
+../tar_texi/tar.texi(,5634) by all the machines which have file systems to be
dumped.
+../tar_texi/tar.texi(,5635) @end defvr
+../tar_texi/tar.texi(,5636)
+../tar_texi/tar.texi(,5637) @defvr {Backup variable} XLIST
+../tar_texi/tar.texi(,5638)
+../tar_texi/tar.texi(,5639) Name of @dfn{exclude file list}. An @dfn{exclude
file list} is a file
+../tar_texi/tar.texi(,5640) located on the remote machine and containing the
list of files to
+../tar_texi/tar.texi(,5641) be excluded from the backup. Exclude file lists
are searched in
+../tar_texi/tar.texi(,5642) /etc/tar-backup directory. A common use for
exclude file lists
+../tar_texi/tar.texi(,5643) is to exclude files containing security-sensitive
information
+../tar_texi/tar.texi(,5644) (e.g., @file{/etc/shadow} from backups).
+../tar_texi/tar.texi(,5645)
+../tar_texi/tar.texi(,5646) This variable affects only @code{backup}.
+../tar_texi/tar.texi(,5647) @end defvr
+../tar_texi/tar.texi(,5648)
+../tar_texi/tar.texi(,5649) @defvr {Backup variable} SLEEP_TIME
+../tar_texi/tar.texi(,5650)
+../tar_texi/tar.texi(,5651) Time to sleep between dumps of any two successive
file systems
+../tar_texi/tar.texi(,5652)
+../tar_texi/tar.texi(,5653) This variable affects only @code{backup}.
+../tar_texi/tar.texi(,5654) @end defvr
+../tar_texi/tar.texi(,5655)
+../tar_texi/tar.texi(,5656) @defvr {Backup variable} DUMP_REMIND_SCRIPT
+../tar_texi/tar.texi(,5657)
+../tar_texi/tar.texi(,5658) Script to be run when it's time to insert a new
tape in for the next
+../tar_texi/tar.texi(,5659) volume. Administrators may want to tailor this
script for their site.
+../tar_texi/tar.texi(GNUTAR,5660) If this variable isn't set,
../tar_texi/tar.texi(GNUTAR,5660) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,5660) will display its built-in
+../tar_texi/tar.texi(,5661) prompt, and will expect confirmation from the
console. For the
+../tar_texi/tar.texi(,5662) description of the default prompt, see @ref{change
volume prompt}.
+../tar_texi/tar.texi(,5663)
+../tar_texi/tar.texi(,5664) @end defvr
+../tar_texi/tar.texi(,5665)
+../tar_texi/tar.texi(,5666) @defvr {Backup variable} SLEEP_MESSAGE
+../tar_texi/tar.texi(,5667)
+../tar_texi/tar.texi(,5668) Message to display on the terminal while waiting
for dump time. Usually
+../tar_texi/tar.texi(,5669) this will just be some literal text.
+../tar_texi/tar.texi(,5670) @end defvr
+../tar_texi/tar.texi(,5671)
+../tar_texi/tar.texi(,5672) @defvr {Backup variable} TAR
+../tar_texi/tar.texi(,5673)
+../tar_texi/tar.texi(GNUTAR,5674) Full file name of the
../tar_texi/tar.texi(GNUTAR,5674) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,5674) executable. If this is not
set, backup
+../tar_texi/tar.texi(,5675) scripts will search @command{tar} in the current
shell path.
+../tar_texi/tar.texi(,5676) @end defvr
+../tar_texi/tar.texi(,5677)
+../tar_texi/tar.texi(,5678) @node Magnetic Tape Control
+../tar_texi/tar.texi(,5679) @subsection Magnetic Tape Control
+../tar_texi/tar.texi(,5680)
+../tar_texi/tar.texi(,5681) Backup scripts access tape device using special
@dfn{hook functions}.
+../tar_texi/tar.texi(,5682) These functions take a single argument -- the name
of the tape
+../tar_texi/tar.texi(,5683) device. Their names are kept in the following
variables:
+../tar_texi/tar.texi(,5684)
+../tar_texi/tar.texi(,5685) @defvr {Backup variable} MT_BEGIN
+../tar_texi/tar.texi(,5686) The name of @dfn{begin} function. This function
is called before
+../tar_texi/tar.texi(,5687) accessing the drive. By default it retensions the
tape:
+../tar_texi/tar.texi(,5688)
+../tar_texi/tar.texi(,5689) @smallexample
+../tar_texi/tar.texi(,5690) MT_BEGIN=mt_begin
+../tar_texi/tar.texi(,5691)
+../tar_texi/tar.texi(,5692) mt_begin() @{
+../tar_texi/tar.texi(,5693) mt -f "$1" retension
+../tar_texi/tar.texi(,5694) @}
+../tar_texi/tar.texi(,5695) @end smallexample
+../tar_texi/tar.texi(,5696) @end defvr
+../tar_texi/tar.texi(,5697)
+../tar_texi/tar.texi(,5698) @defvr {Backup variable} MT_REWIND
+../tar_texi/tar.texi(,5699) The name of @dfn{rewind} function. The default
definition is as
+../tar_texi/tar.texi(,5700) follows:
+../tar_texi/tar.texi(,5701)
+../tar_texi/tar.texi(,5702) @smallexample
+../tar_texi/tar.texi(,5703) MT_REWIND=mt_rewind
+../tar_texi/tar.texi(,5704)
+../tar_texi/tar.texi(,5705) mt_rewind() @{
+../tar_texi/tar.texi(,5706) mt -f "$1" rewind
+../tar_texi/tar.texi(,5707) @}
+../tar_texi/tar.texi(,5708) @end smallexample
+../tar_texi/tar.texi(,5709)
+../tar_texi/tar.texi(,5710) @end defvr
+../tar_texi/tar.texi(,5711)
+../tar_texi/tar.texi(,5712) @defvr {Backup variable} MT_OFFLINE
+../tar_texi/tar.texi(,5713) The name of the function switching the tape off
line. By default
+../tar_texi/tar.texi(,5714) it is defined as follows:
+../tar_texi/tar.texi(,5715)
+../tar_texi/tar.texi(,5716) @smallexample
+../tar_texi/tar.texi(,5717) MT_OFFLINE=mt_offline
+../tar_texi/tar.texi(,5718)
+../tar_texi/tar.texi(,5719) mt_offline() @{
+../tar_texi/tar.texi(,5720) mt -f "$1" offl
+../tar_texi/tar.texi(,5721) @}
+../tar_texi/tar.texi(,5722) @end smallexample
+../tar_texi/tar.texi(,5723) @end defvr
+../tar_texi/tar.texi(,5724)
+../tar_texi/tar.texi(,5725) @defvr {Backup variable} MT_STATUS
+../tar_texi/tar.texi(,5726) The name of the function used to obtain the status
of the archive device,
+../tar_texi/tar.texi(,5727) including error count. Default definition:
+../tar_texi/tar.texi(,5728)
+../tar_texi/tar.texi(,5729) @smallexample
+../tar_texi/tar.texi(,5730) MT_STATUS=mt_status
+../tar_texi/tar.texi(,5731)
+../tar_texi/tar.texi(,5732) mt_status() @{
+../tar_texi/tar.texi(,5733) mt -f "$1" status
+../tar_texi/tar.texi(,5734) @}
+../tar_texi/tar.texi(,5735) @end smallexample
+../tar_texi/tar.texi(,5736) @end defvr
+../tar_texi/tar.texi(,5737)
+../tar_texi/tar.texi(,5738) @node User Hooks
+../tar_texi/tar.texi(,5739) @subsection User Hooks
+../tar_texi/tar.texi(,5740)
+../tar_texi/tar.texi(,5741) @dfn{User hooks} are shell functions executed
before and after
+../tar_texi/tar.texi(,5742) each @command{tar} invocation. Thus, there are
@dfn{backup
+../tar_texi/tar.texi(,5743) hooks}, which are executed before and after
dumping each file
+../tar_texi/tar.texi(,5744) system, and @dfn{restore hooks}, executed before
and
+../tar_texi/tar.texi(,5745) after restoring a file system. Each user hook is
a shell function
+../tar_texi/tar.texi(,5746) taking four arguments:
+../tar_texi/tar.texi(,5747)
+../tar_texi/tar.texi(,5748) @deffn {User Hook Function} hook @var{level}
@var{host} @var{fs} @var{fsname}
+../tar_texi/tar.texi(,5749) Its arguments are:
+../tar_texi/tar.texi(,5750)
+../tar_texi/tar.texi(,5751) @table @var
+../tar_texi/tar.texi(,5752) @item level
+../tar_texi/tar.texi(,5753) Current backup or restore level.
+../tar_texi/tar.texi(,5754)
+../tar_texi/tar.texi(,5755) @item host
+../tar_texi/tar.texi(,5756) Name or IP address of the host machine being
dumped or restored.
+../tar_texi/tar.texi(,5757)
+../tar_texi/tar.texi(,5758) @item fs
+../tar_texi/tar.texi(,5759) Full path name to the file system being dumped or
restored.
+../tar_texi/tar.texi(,5760)
+../tar_texi/tar.texi(,5761) @item fsname
+../tar_texi/tar.texi(,5762) File system name with directory separators
replaced with colons. This
+../tar_texi/tar.texi(,5763) is useful, e.g., for creating unique files.
+../tar_texi/tar.texi(,5764) @end table
+../tar_texi/tar.texi(,5765) @end deffn
+../tar_texi/tar.texi(,5766)
+../tar_texi/tar.texi(,5767) Following variables keep the names of user hook
functions
+../tar_texi/tar.texi(,5768)
+../tar_texi/tar.texi(,5769) @defvr {Backup variable} DUMP_BEGIN
+../tar_texi/tar.texi(,5770) Dump begin function. It is executed before
dumping the file system.
+../tar_texi/tar.texi(,5771) @end defvr
+../tar_texi/tar.texi(,5772)
+../tar_texi/tar.texi(,5773) @defvr {Backup variable} DUMP_END
+../tar_texi/tar.texi(,5774) Executed after dumping the file system.
+../tar_texi/tar.texi(,5775) @end defvr
+../tar_texi/tar.texi(,5776)
+../tar_texi/tar.texi(,5777) @defvr {Backup variable} RESTORE_BEGIN
+../tar_texi/tar.texi(,5778) Executed before restoring the file system.
+../tar_texi/tar.texi(,5779) @end defvr
+../tar_texi/tar.texi(,5780)
+../tar_texi/tar.texi(,5781) @defvr {Backup variable} RESTORE_END
+../tar_texi/tar.texi(,5782) Executed after restoring the file system.
+../tar_texi/tar.texi(,5783) @end defvr
+../tar_texi/tar.texi(,5784)
+../tar_texi/tar.texi(,5785) @node backup-specs example
+../tar_texi/tar.texi(,5786) @subsection An Example Text of @file{Backup-specs}
+../tar_texi/tar.texi(,5787)
+../tar_texi/tar.texi(,5788) The following is an example of @file{backup-specs}:
+../tar_texi/tar.texi(,5789)
+../tar_texi/tar.texi(,5790) @smallexample
+../tar_texi/tar.texi(,5791) # site-specific parameters for file system backup.
+../tar_texi/tar.texi(,5792)
+../tar_texi/tar.texi(,5793) ADMINISTRATOR=friedman
+../tar_texi/tar.texi(,5794) BACKUP_HOUR=1
+../tar_texi/tar.texi(,5795) TAPE_FILE=/dev/nrsmt0
+../tar_texi/tar.texi(,5796)
+../tar_texi/tar.texi(,5797) # Use @code{ssh} instead of the less secure
@code{rsh}
+../tar_texi/tar.texi(,5798) RSH=/usr/bin/ssh
+../tar_texi/tar.texi(,5799) RSH_COMMAND=/usr/bin/ssh
+../tar_texi/tar.texi(,5800)
+../tar_texi/tar.texi(,5801) # Override MT_STATUS function:
+../tar_texi/tar.texi(,5802) my_status() @{
+../tar_texi/tar.texi(,5803) mts -t $TAPE_FILE
+../tar_texi/tar.texi(,5804) @}
+../tar_texi/tar.texi(,5805) MT_STATUS=my_status
+../tar_texi/tar.texi(,5806)
+../tar_texi/tar.texi(,5807) # Disable MT_OFFLINE function
+../tar_texi/tar.texi(,5808) MT_OFFLINE=:
+../tar_texi/tar.texi(,5809)
+../tar_texi/tar.texi(,5810) BLOCKING=124
+../tar_texi/tar.texi(,5811) BACKUP_DIRS="
+../tar_texi/tar.texi(,5812) albert:/fs/fsf
+../tar_texi/tar.texi(,5813) apple-gunkies:/gd
+../tar_texi/tar.texi(,5814) albert:/fs/gd2
+../tar_texi/tar.texi(,5815) albert:/fs/gp
+../tar_texi/tar.texi(,5816) geech:/usr/jla
+../tar_texi/tar.texi(,5817) churchy:/usr/roland
+../tar_texi/tar.texi(,5818) albert:/
+../tar_texi/tar.texi(,5819) albert:/usr
+../tar_texi/tar.texi(,5820) apple-gunkies:/
+../tar_texi/tar.texi(,5821) apple-gunkies:/usr
+../tar_texi/tar.texi(,5822) gnu:/hack
+../tar_texi/tar.texi(,5823) gnu:/u
+../tar_texi/tar.texi(,5824) apple-gunkies:/com/mailer/gnu
+../tar_texi/tar.texi(,5825) apple-gunkies:/com/archive/gnu"
+../tar_texi/tar.texi(,5826)
+../tar_texi/tar.texi(,5827) BACKUP_FILES="/com/mailer/aliases
/com/mailer/league*[a-z]"
+../tar_texi/tar.texi(,5828)
+../tar_texi/tar.texi(,5829) @end smallexample
+../tar_texi/tar.texi(,5830)
+../tar_texi/tar.texi(,5831) @node Scripted Backups
+../tar_texi/tar.texi(,5832) @section Using the Backup Scripts
+../tar_texi/tar.texi(,5833)
+../tar_texi/tar.texi(,5834) The syntax for running a backup script is:
+../tar_texi/tar.texi(,5835)
+../tar_texi/tar.texi(,5836) @smallexample
+../tar_texi/tar.texi(,5837) backup address@hidden address@hidden
+../tar_texi/tar.texi(,5838) @end smallexample
+../tar_texi/tar.texi(,5839)
+../tar_texi/tar.texi(,5840) The @option{level} option requests the dump level.
Thus, to produce
+../tar_texi/tar.texi(,5841) a full dump, specify @code{--level=0} (this is the
default, so
+../tar_texi/tar.texi(,5842) @option{--level} may be omitted if its value is
@code{0}).
+../tar_texi/tar.texi(,5843) @footnote{For backward compatibility, the
@code{backup} will also
+../tar_texi/tar.texi(,5844) try to deduce the requested dump level from the
name of the
+../tar_texi/tar.texi(,5845) script itself. If the name consists of a string
@samp{level-}
+../tar_texi/tar.texi(,5846) followed by a single decimal digit, that digit is
taken as
+../tar_texi/tar.texi(,5847) the dump level number. Thus, you may create a
link from @code{backup}
+../tar_texi/tar.texi(,5848) to @code{level-1} and then run @code{level-1}
whenever you need to
+../tar_texi/tar.texi(,5849) create a level one dump.}
+../tar_texi/tar.texi(,5850)
+../tar_texi/tar.texi(,5851) The @option{--time} option determines when should
the backup be
+../tar_texi/tar.texi(,5852) run. @var{Time} may take three forms:
+../tar_texi/tar.texi(,5853)
+../tar_texi/tar.texi(,5854) @table @asis
+../tar_texi/tar.texi(,5855) @item @var{hh}:@var{mm}
+../tar_texi/tar.texi(,5856)
+../tar_texi/tar.texi(,5857) The dump must be run at @var{hh} hours @var{mm}
minutes.
+../tar_texi/tar.texi(,5858)
+../tar_texi/tar.texi(,5859) @item @var{hh}
+../tar_texi/tar.texi(,5860)
+../tar_texi/tar.texi(,5861) The dump must be run at @var{hh} hours
+../tar_texi/tar.texi(,5862)
+../tar_texi/tar.texi(,5863) @item now
+../tar_texi/tar.texi(,5864)
+../tar_texi/tar.texi(,5865) The dump must be run immediately.
+../tar_texi/tar.texi(,5866) @end table
+../tar_texi/tar.texi(,5867)
+../tar_texi/tar.texi(,5868) You should start a script with a tape or disk
mounted. Once you
+../tar_texi/tar.texi(,5869) start a script, it prompts you for new tapes or
disks as it
+../tar_texi/tar.texi(,5870) needs them. Media volumes don't have to
correspond to archive
+../tar_texi/tar.texi(,5871) files --- a multi-volume archive can be started in
the middle of a
+../tar_texi/tar.texi(,5872) tape that already contains the end of another
multi-volume archive.
+../tar_texi/tar.texi(,5873) The @code{restore} script prompts for media by its
archive volume,
+../tar_texi/tar.texi(,5874) so to avoid an error message you should keep track
of which tape
+../tar_texi/tar.texi(,5875) (or disk) contains which volume of the archive
(@pxref{Scripted
+../tar_texi/tar.texi(,5876) Restoration}).
+../tar_texi/tar.texi(,5877)
+../tar_texi/tar.texi(,5878) The backup scripts write two files on the file
system. The first is a
+../tar_texi/tar.texi(,5879) record file in @file{/etc/tar-backup/}, which is
used by the scripts
+../tar_texi/tar.texi(,5880) to store and retrieve information about which
files were dumped. This
+../tar_texi/tar.texi(,5881) file is not meant to be read by humans, and should
not be deleted by
+../tar_texi/tar.texi(,5882) them. @xref{Snapshot Files}, for a more detailed
explanation of this
+../tar_texi/tar.texi(,5883) file.
+../tar_texi/tar.texi(,5884)
+../tar_texi/tar.texi(,5885) The second file is a log file containing the names
of the file systems
+../tar_texi/tar.texi(,5886) and files dumped, what time the backup was made,
and any error
+../tar_texi/tar.texi(,5887) messages that were generated, as well as how much
space was left in
+../tar_texi/tar.texi(,5888) the media volume after the last volume of the
archive was written.
+../tar_texi/tar.texi(,5889) You should check this log file after every backup.
The file name is
+../tar_texi/tar.texi(,5890) @address@hidden@var{n}}, where @var{mm-dd-yyyy}
+../tar_texi/tar.texi(,5891) represents current date, and @var{n} represents
current dump level number.
+../tar_texi/tar.texi(,5892)
+../tar_texi/tar.texi(,5893) The script also prints the name of each system
being dumped to the
+../tar_texi/tar.texi(,5894) standard output.
+../tar_texi/tar.texi(,5895)
+../tar_texi/tar.texi(,5896) Following is the full list of options accepted by
@code{backup}
+../tar_texi/tar.texi(,5897) script:
+../tar_texi/tar.texi(,5898)
+../tar_texi/tar.texi(,5899) @table @option
+../tar_texi/tar.texi(,5900) @item -l @var{level}
+../tar_texi/tar.texi(,5901) @itemx address@hidden
+../tar_texi/tar.texi(,5902) Do backup level @var{level} (default 0).
+../tar_texi/tar.texi(,5903)
+../tar_texi/tar.texi(,5904) @item -f
+../tar_texi/tar.texi(,5905) @itemx --force
+../tar_texi/tar.texi(,5906) Force backup even if today's log file already
exists.
+../tar_texi/tar.texi(,5907)
+../tar_texi/tar.texi(,5908) @item address@hidden
+../tar_texi/tar.texi(,5909) @itemx address@hidden
+../tar_texi/tar.texi(,5910) Set verbosity level. The higher the level is, the
more debugging
+../tar_texi/tar.texi(,5911) information will be output during execution.
Devault @var{level}
+../tar_texi/tar.texi(,5912) is 100, which means the highest debugging level.
+../tar_texi/tar.texi(,5913)
+../tar_texi/tar.texi(,5914) @item -t @var{start-time}
+../tar_texi/tar.texi(,5915) @itemx address@hidden
+../tar_texi/tar.texi(,5916) Wait till @var{time}, then do backup.
+../tar_texi/tar.texi(,5917)
+../tar_texi/tar.texi(,5918) @item -h
+../tar_texi/tar.texi(,5919) @itemx --help
+../tar_texi/tar.texi(,5920) Display short help message and exit.
+../tar_texi/tar.texi(,5921)
+../tar_texi/tar.texi(,5922) @item -V
+../tar_texi/tar.texi(,5923) @itemx --version
+../tar_texi/tar.texi(,5924) Display information about the program's name,
version, origin and legal
+../tar_texi/tar.texi(,5925) status, all on standard output, and then exit
successfully.
+../tar_texi/tar.texi(,5926) @end table
+../tar_texi/tar.texi(,5927)
+../tar_texi/tar.texi(,5928)
+../tar_texi/tar.texi(,5929) @node Scripted Restoration
+../tar_texi/tar.texi(,5930) @section Using the Restore Script
+../tar_texi/tar.texi(,5931)
+../tar_texi/tar.texi(,5932) To restore files that were archived using a
scripted backup, use the
+../tar_texi/tar.texi(,5933) @code{restore} script. Its usage is quite
straightforward. In the
+../tar_texi/tar.texi(,5934) simplest form, invoke @code{restore --all}, it will
+../tar_texi/tar.texi(,5935) then restore all the file systems and files
specified in
+../tar_texi/tar.texi(,5936) @file{backup-specs} (@pxref{General-Purpose
Variables,BACKUP_DIRS}).
+../tar_texi/tar.texi(,5937)
+../tar_texi/tar.texi(,5938) You may select the file systems (and/or files) to
restore by
+../tar_texi/tar.texi(,5939) giving @code{restore} list of @dfn{patterns} in
its command
+../tar_texi/tar.texi(,5940) line. For example, running
+../tar_texi/tar.texi(,5941)
+../tar_texi/tar.texi(,5942) @smallexample
+../tar_texi/tar.texi(,5943) restore 'albert:*'
+../tar_texi/tar.texi(,5944) @end smallexample
+../tar_texi/tar.texi(,5945)
+../tar_texi/tar.texi(,5946) @noindent
+../tar_texi/tar.texi(,5947) will restore all file systems on the machine
@samp{albert}. A more
+../tar_texi/tar.texi(,5948) complicated example:
+../tar_texi/tar.texi(,5949)
+../tar_texi/tar.texi(,5950) @smallexample
+../tar_texi/tar.texi(,5951) restore 'albert:*' '*:/var'
+../tar_texi/tar.texi(,5952) @end smallexample
+../tar_texi/tar.texi(,5953)
+../tar_texi/tar.texi(,5954) @noindent
+../tar_texi/tar.texi(,5955) This command will restore all file systems on the
machine @samp{albert}
+../tar_texi/tar.texi(,5956) as well as @file{/var} file system on all machines.
+../tar_texi/tar.texi(,5957)
+../tar_texi/tar.texi(,5958) By default @code{restore} will start restoring
files from the lowest
+../tar_texi/tar.texi(,5959) available dump level (usually zero) and will
continue through
+../tar_texi/tar.texi(,5960) all available dump levels. There may be
situations where such a
+../tar_texi/tar.texi(,5961) thorough restore is not necessary. For example,
you may wish to
+../tar_texi/tar.texi(,5962) restore only files from the recent level one
backup. To do so,
+../tar_texi/tar.texi(,5963) use @option{--level} option, as shown in the
example below:
+../tar_texi/tar.texi(,5964)
+../tar_texi/tar.texi(,5965) @smallexample
+../tar_texi/tar.texi(,5966) restore --level=1
+../tar_texi/tar.texi(,5967) @end smallexample
+../tar_texi/tar.texi(,5968)
+../tar_texi/tar.texi(,5969) The full list of options accepted by
@code{restore} follows:
+../tar_texi/tar.texi(,5970)
+../tar_texi/tar.texi(,5971) @table @option
+../tar_texi/tar.texi(,5972) @item -a
+../tar_texi/tar.texi(,5973) @itemx --all
+../tar_texi/tar.texi(,5974) Restore all file systems and files specified in
@file{backup-specs}
+../tar_texi/tar.texi(,5975)
+../tar_texi/tar.texi(,5976) @item -l @var{level}
+../tar_texi/tar.texi(,5977) @itemx address@hidden
+../tar_texi/tar.texi(,5978) Start restoring from the given backup level,
instead of the default 0.
+../tar_texi/tar.texi(,5979)
+../tar_texi/tar.texi(,5980) @item address@hidden
+../tar_texi/tar.texi(,5981) @itemx address@hidden
+../tar_texi/tar.texi(,5982) Set verbosity level. The higher the level is, the
more debugging
+../tar_texi/tar.texi(,5983) information will be output during execution.
Devault @var{level}
+../tar_texi/tar.texi(,5984) is 100, which means the highest debugging level.
+../tar_texi/tar.texi(,5985)
+../tar_texi/tar.texi(,5986) @item -h
+../tar_texi/tar.texi(,5987) @itemx --help
+../tar_texi/tar.texi(,5988) Display short help message and exit.
+../tar_texi/tar.texi(,5989)
+../tar_texi/tar.texi(,5990) @item -V
+../tar_texi/tar.texi(,5991) @itemx --version
+../tar_texi/tar.texi(,5992) Display information about the program's name,
version, origin and legal
+../tar_texi/tar.texi(,5993) status, all on standard output, and then exit
successfully.
+../tar_texi/tar.texi(,5994) @end table
+../tar_texi/tar.texi(,5995)
+../tar_texi/tar.texi(,5996) You should start the restore script with the media
containing the
+../tar_texi/tar.texi(,5997) first volume of the archive mounted. The script
will prompt for other
+../tar_texi/tar.texi(,5998) volumes as they are needed. If the archive is on
tape, you don't need
+../tar_texi/tar.texi(,5999) to rewind the tape to to its beginning---if the
tape head is
+../tar_texi/tar.texi(,6000) positioned past the beginning of the archive, the
script will rewind
+../tar_texi/tar.texi(,6001) the tape as needed. @xref{Tape Positioning}, for
a discussion of tape
+../tar_texi/tar.texi(,6002) positioning.
+../tar_texi/tar.texi(,6003)
+../tar_texi/tar.texi(,6004) @quotation
+../tar_texi/tar.texi(,6005) @strong{Warning:} The script will delete files
from the active file
+../tar_texi/tar.texi(,6006) system if they were not in the file system when
the archive was made.
+../tar_texi/tar.texi(,6007) @end quotation
+../tar_texi/tar.texi(,6008)
+../tar_texi/tar.texi(,6009) @xref{Incremental Dumps}, for an explanation of
how the script makes
+../tar_texi/tar.texi(,6010) that determination.
+../tar_texi/tar.texi(,6011)
+../tar_texi/tar.texi(,6012) @node Choosing
+../tar_texi/tar.texi(,6013) @chapter Choosing Files and Names for @command{tar}
+../tar_texi/tar.texi(UNREVISED,6014) @quotation
+../tar_texi/tar.texi(UNREVISED,6014) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,6014) @end quotation
+../tar_texi/tar.texi(UNREVISED,6014)
+../tar_texi/tar.texi(,6015)
+../tar_texi/tar.texi(,6016) Certain options to @command{tar} enable you to
specify a name for your
+../tar_texi/tar.texi(,6017) archive. Other options let you decide which files
to include or exclude
+../tar_texi/tar.texi(,6018) from the archive, based on when or whether files
were modified, whether
+../tar_texi/tar.texi(,6019) the file names do or don't match specified
patterns, or whether files
+../tar_texi/tar.texi(,6020) are in specified directories.
+../tar_texi/tar.texi(,6021)
+../tar_texi/tar.texi(,6022) This chapter discusses these options in detail.
+../tar_texi/tar.texi(,6023)
+../tar_texi/tar.texi(,6024) @menu
+../tar_texi/tar.texi(,6025) * file:: Choosing the
Archive's Name
+../tar_texi/tar.texi(,6026) * Selecting Archive Members::
+../tar_texi/tar.texi(,6027) * files:: Reading Names from
a File
+../tar_texi/tar.texi(,6028) * exclude:: Excluding Some
Files
+../tar_texi/tar.texi(,6029) * wildcards:: Wildcards Patterns
and Matching
+../tar_texi/tar.texi(,6030) * quoting styles:: Ways of Quoting
Special Characters in Names
+../tar_texi/tar.texi(,6031) * transform:: Modifying File and
Member Names
+../tar_texi/tar.texi(,6032) * after:: Operating Only on
New Files
+../tar_texi/tar.texi(,6033) * recurse:: Descending into
Directories
+../tar_texi/tar.texi(,6034) * one:: Crossing File
System Boundaries
+../tar_texi/tar.texi(,6035) @end menu
+../tar_texi/tar.texi(,6036)
+../tar_texi/tar.texi(,6037) @node file
+../tar_texi/tar.texi(,6038) @section Choosing and Naming Archive Files
+../tar_texi/tar.texi(UNREVISED,6039) @quotation
+../tar_texi/tar.texi(UNREVISED,6039) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,6039) @end quotation
+../tar_texi/tar.texi(UNREVISED,6039)
+../tar_texi/tar.texi(,6040)
+../tar_texi/tar.texi(,6041) @cindex Naming an archive
+../tar_texi/tar.texi(,6042) @cindex Archive Name
+../tar_texi/tar.texi(,6043) @cindex Choosing an archive file
+../tar_texi/tar.texi(,6044) @cindex Where is the archive?
+../tar_texi/tar.texi(,6045) By default, @command{tar} uses an archive file
name that was compiled when
+../tar_texi/tar.texi(,6046) it was built on the system; usually this name
refers to some physical
+../tar_texi/tar.texi(,6047) tape drive on the machine. However, the person
who installed @command{tar}
+../tar_texi/tar.texi(,6048) on the system may not have set the default to a
meaningful value as far as
+../tar_texi/tar.texi(,6049) most users are concerned. As a result, you will
usually want to tell
+../tar_texi/tar.texi(,6050) @command{tar} where to find (or create) the
archive. The
+../tar_texi/tar.texi(,6051) @address@hidden (@option{-f @var{archive-name}})
+../tar_texi/tar.texi(,6052) option allows you to either specify or name a file
to use as the archive
+../tar_texi/tar.texi(,6053) instead of the default archive file location.
+../tar_texi/tar.texi(,6054)
+../tar_texi/tar.texi(,6055) @table @option
+../tar_texi/tar.texi(xopindex,6056) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,6056)
+../tar_texi/tar.texi(,6057) @item address@hidden
+../tar_texi/tar.texi(,6058) @itemx -f @var{archive-name}
+../tar_texi/tar.texi(,6059) Name the archive to create or operate on. Use in
conjunction with
+../tar_texi/tar.texi(,6060) any operation.
+../tar_texi/tar.texi(,6061) @end table
+../tar_texi/tar.texi(,6062)
+../tar_texi/tar.texi(,6063) For example, in this @command{tar} command,
+../tar_texi/tar.texi(,6064)
+../tar_texi/tar.texi(,6065) @smallexample
+../tar_texi/tar.texi(,6066) $ @kbd{tar -cvf collection.tar blues folk jazz}
+../tar_texi/tar.texi(,6067) @end smallexample
+../tar_texi/tar.texi(,6068)
+../tar_texi/tar.texi(,6069) @noindent
+../tar_texi/tar.texi(,6070) @file{collection.tar} is the name of the archive.
It must directly
+../tar_texi/tar.texi(,6071) follow the @option{-f} option, since whatever
directly follows @option{-f}
+../tar_texi/tar.texi(,6072) @emph{will} end up naming the archive. If you
neglect to specify an
+../tar_texi/tar.texi(,6073) archive name, you may end up overwriting a file in
the working directory
+../tar_texi/tar.texi(,6074) with the archive you create since @command{tar}
will use this file's name
+../tar_texi/tar.texi(,6075) for the archive name.
+../tar_texi/tar.texi(,6076)
+../tar_texi/tar.texi(,6077) An archive can be saved as a file in the file
system, sent through a
+../tar_texi/tar.texi(,6078) pipe or over a network, or written to an I/O
device such as a tape,
+../tar_texi/tar.texi(,6079) floppy disk, or CD write drive.
+../tar_texi/tar.texi(,6080)
+../tar_texi/tar.texi(,6081) @cindex Writing new archives
+../tar_texi/tar.texi(,6082) @cindex Archive creation
+../tar_texi/tar.texi(,6083) If you do not name the archive, @command{tar} uses
the value of the
+../tar_texi/tar.texi(,6084) environment variable @env{TAPE} as the file name
for the archive. If
+../tar_texi/tar.texi(,6085) that is not available, @command{tar} uses a
default, compiled-in archive
+../tar_texi/tar.texi(,6086) name, usually that for tape unit zero (i.e.
@file{/dev/tu00}).
+../tar_texi/tar.texi(,6087)
+../tar_texi/tar.texi(,6088) @cindex Standard input and output
+../tar_texi/tar.texi(,6089) @cindex tar to standard input and output
+../tar_texi/tar.texi(,6090) If you use @file{-} as an @var{archive-name},
@command{tar} reads the
+../tar_texi/tar.texi(,6091) archive from standard input (when listing or
extracting files), or
+../tar_texi/tar.texi(,6092) writes it to standard output (when creating an
archive). If you use
+../tar_texi/tar.texi(,6093) @file{-} as an @var{archive-name} when modifying
an archive,
+../tar_texi/tar.texi(,6094) @command{tar} reads the original archive from its
standard input and
+../tar_texi/tar.texi(,6095) writes the entire new archive to its standard
output.
+../tar_texi/tar.texi(,6096)
+../tar_texi/tar.texi(,6097) The following example is a convenient way of
copying directory
+../tar_texi/tar.texi(,6098) hierarchy from @file{sourcedir} to
@file{targetdir}.
+../tar_texi/tar.texi(,6099)
+../tar_texi/tar.texi(,6100) @smallexample
+../tar_texi/tar.texi(,6101) $ @kbd{(cd sourcedir; tar -cf - .) | (cd
targetdir; tar -xpf -)}
+../tar_texi/tar.texi(,6102) @end smallexample
+../tar_texi/tar.texi(,6103)
+../tar_texi/tar.texi(,6104) The @option{-C} option allows to avoid using
subshells:
+../tar_texi/tar.texi(,6105)
+../tar_texi/tar.texi(,6106) @smallexample
+../tar_texi/tar.texi(,6107) $ @kbd{tar -C sourcedir -cf - . | tar -C targetdir
-xpf -}
+../tar_texi/tar.texi(,6108) @end smallexample
+../tar_texi/tar.texi(,6109)
+../tar_texi/tar.texi(,6110) In both examples above, the leftmost @command{tar}
invocation archives
+../tar_texi/tar.texi(,6111) the contents of @file{sourcedir} to the standard
output, while the
+../tar_texi/tar.texi(,6112) rightmost one reads this archive from its standard
input and
+../tar_texi/tar.texi(,6113) extracts it. The @option{-p} option tells it to
restore permissions
+../tar_texi/tar.texi(,6114) of the extracted files.
+../tar_texi/tar.texi(,6115)
+../tar_texi/tar.texi(,6116) @cindex Remote devices
+../tar_texi/tar.texi(,6117) @cindex tar to a remote device
+../tar_texi/tar.texi(,6118) @anchor{remote-dev}
+../tar_texi/tar.texi(,6119) To specify an archive file on a device attached to
a remote machine,
+../tar_texi/tar.texi(,6120) use the following:
+../tar_texi/tar.texi(,6121)
+../tar_texi/tar.texi(,6122) @smallexample
+../tar_texi/tar.texi(,6123) @address@hidden:/@var{dev}/@var{file-name}}
+../tar_texi/tar.texi(,6124) @end smallexample
+../tar_texi/tar.texi(,6125)
+../tar_texi/tar.texi(,6126) @noindent
+../tar_texi/tar.texi(,6127) @command{tar} will complete the remote connection,
if possible, and
+../tar_texi/tar.texi(,6128) prompt you for a username and password. If you use
+../tar_texi/tar.texi(,6129)
@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
+../tar_texi/tar.texi(,6130) will complete the remote connection, if possible,
using your username
+../tar_texi/tar.texi(,6131) as the username on the remote machine.
+../tar_texi/tar.texi(,6132)
+../tar_texi/tar.texi(,6133) @cindex Local and remote archives
+../tar_texi/tar.texi(,6134) @anchor{local and remote archives}
+../tar_texi/tar.texi(,6135) If the archive file name includes a colon
(@samp{:}), then it is assumed
+../tar_texi/tar.texi(,6136) to be a file on another machine. If the archive
file is
+../tar_texi/tar.texi(,6137) @address@hidden@@@var{host}:@var{file}}, then
@var{file} is used on the
+../tar_texi/tar.texi(,6138) host @var{host}. The remote host is accessed
using the @command{rsh}
+../tar_texi/tar.texi(,6139) program, with a username of @var{user}. If the
username is omitted
+../tar_texi/tar.texi(,6140) (along with the @samp{@@} sign), then your user
name will be used.
+../tar_texi/tar.texi(,6141) (This is the normal @command{rsh} behavior.) It
is necessary for the
+../tar_texi/tar.texi(,6142) remote machine, in addition to permitting your
@command{rsh} access, to
+../tar_texi/tar.texi(,6143) have the @file{rmt} program installed (This
command is included in
+../tar_texi/tar.texi(GNUTAR,6144) the ../tar_texi/tar.texi(GNUTAR,6144)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,6144) distribution and
by default is installed under
+../tar_texi/tar.texi(,6145) @address@hidden/libexec/rmt}, were @var{prefix}
means your
+../tar_texi/tar.texi(,6146) installation prefix). If you need to use a file
whose name includes a
+../tar_texi/tar.texi(,6147) colon, then the remote tape drive behavior
+../tar_texi/tar.texi(,6148) can be inhibited by using the
@option{--force-local} option.
+../tar_texi/tar.texi(,6149)
+../tar_texi/tar.texi(GNUTAR,6150) When the archive is being created to
@file{/dev/null}, ../tar_texi/tar.texi(GNUTAR,6150) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,6150)
+../tar_texi/tar.texi(,6151) tries to minimize input and output operations.
The Amanda backup
+../tar_texi/tar.texi(GNUTAR,6152) system, when used with
../tar_texi/tar.texi(GNUTAR,6152) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,6152) , has an initial sizing pass
which
+../tar_texi/tar.texi(,6153) uses this feature.
+../tar_texi/tar.texi(,6154)
+../tar_texi/tar.texi(,6155) @node Selecting Archive Members
+../tar_texi/tar.texi(,6156) @section Selecting Archive Members
+../tar_texi/tar.texi(,6157) @cindex Specifying files to act on
+../tar_texi/tar.texi(,6158) @cindex Specifying archive members
+../tar_texi/tar.texi(,6159)
+../tar_texi/tar.texi(,6160) @dfn{File Name arguments} specify which files in
the file system
+../tar_texi/tar.texi(,6161) @command{tar} operates on, when creating or adding
to an archive, or which
+../tar_texi/tar.texi(,6162) archive members @command{tar} operates on, when
reading or deleting from
+../tar_texi/tar.texi(,6163) an archive. @xref{Operations}.
+../tar_texi/tar.texi(,6164)
+../tar_texi/tar.texi(,6165) To specify file names, you can include them as the
last arguments on
+../tar_texi/tar.texi(,6166) the command line, as follows:
+../tar_texi/tar.texi(,6167) @smallexample
+../tar_texi/tar.texi(,6168) @kbd{tar} @var{operation} address@hidden
@var{option2} @dots{}] address@hidden name-1} @var{file name-2} @dots{}]
+../tar_texi/tar.texi(,6169) @end smallexample
+../tar_texi/tar.texi(,6170)
+../tar_texi/tar.texi(,6171) If a file name begins with dash (@samp{-}),
precede it with
+../tar_texi/tar.texi(,6172) @option{--add-file} option to prevent it from
being treated as an
+../tar_texi/tar.texi(,6173) option.
+../tar_texi/tar.texi(,6174)
+../tar_texi/tar.texi(,6175) @anchor{input name quoting}
+../tar_texi/tar.texi(GNUTAR,6176) By default ../tar_texi/tar.texi(GNUTAR,6176)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,6176) attempts to
@dfn{unquote} each file or member
+../tar_texi/tar.texi(,6177) name, replacing @dfn{escape sequences} according
to the following
+../tar_texi/tar.texi(,6178) table:
+../tar_texi/tar.texi(,6179)
+../tar_texi/tar.texi(,6180) @multitable @columnfractions 0.20 0.60
+../tar_texi/tar.texi(,6181) @headitem Escape @tab Replaced with
+../tar_texi/tar.texi(,6182) @item \a @tab Audible bell (ASCII 7)
+../tar_texi/tar.texi(,6183) @item \b @tab Backspace (ASCII 8)
+../tar_texi/tar.texi(,6184) @item \f @tab Form feed (ASCII 12)
+../tar_texi/tar.texi(,6185) @item \n @tab New line (ASCII 10)
+../tar_texi/tar.texi(,6186) @item \r @tab Carriage return (ASCII 13)
+../tar_texi/tar.texi(,6187) @item \t @tab Horizontal tabulation (ASCII
9)
+../tar_texi/tar.texi(,6188) @item \v @tab Vertical tabulation (ASCII
11)
+../tar_texi/tar.texi(,6189) @item \? @tab ASCII 127
+../tar_texi/tar.texi(,6190) @item address@hidden @tab ASCII @var{n} (@var{n}
should be an octal number
+../tar_texi/tar.texi(,6191) of up to 3 digits)
+../tar_texi/tar.texi(,6192) @end multitable
+../tar_texi/tar.texi(,6193)
+../tar_texi/tar.texi(,6194) A backslash followed by any other symbol is
retained.
+../tar_texi/tar.texi(,6195)
+../tar_texi/tar.texi(,6196) This default behavior is controlled by the
following command line
+../tar_texi/tar.texi(,6197) option:
+../tar_texi/tar.texi(,6198)
+../tar_texi/tar.texi(,6199) @table @option
+../tar_texi/tar.texi(,6200) @opindex unquote
+../tar_texi/tar.texi(,6201) @item --unquote
+../tar_texi/tar.texi(,6202) Enable unquoting input file or member names
(default).
+../tar_texi/tar.texi(,6203)
+../tar_texi/tar.texi(,6204) @opindex no-unquote
+../tar_texi/tar.texi(,6205) @item --no-unquote
+../tar_texi/tar.texi(,6206) Disable unquoting input file or member names.
+../tar_texi/tar.texi(,6207) @end table
+../tar_texi/tar.texi(,6208)
+../tar_texi/tar.texi(,6209) If you specify a directory name as a file name
argument, all the files
+../tar_texi/tar.texi(,6210) in that directory are operated on by @command{tar}.
+../tar_texi/tar.texi(,6211)
+../tar_texi/tar.texi(,6212) If you do not specify files, @command{tar}
behavior differs depending
+../tar_texi/tar.texi(,6213) on the operation mode as described below:
+../tar_texi/tar.texi(,6214)
+../tar_texi/tar.texi(,6215) When @command{tar} is invoked with
@option{--create} (@option{-c}),
+../tar_texi/tar.texi(,6216) @command{tar} will stop immediately, reporting the
following:
+../tar_texi/tar.texi(,6217)
+../tar_texi/tar.texi(,6218) @smallexample
+../tar_texi/tar.texi(,6219) @group
+../tar_texi/tar.texi(,6220) $ @kbd{tar cf a.tar}
+../tar_texi/tar.texi(,6221) tar: Cowardly refusing to create an empty archive
+../tar_texi/tar.texi(,6222) Try `tar --help' or `tar --usage' for more
information.
+../tar_texi/tar.texi(,6223) @end group
+../tar_texi/tar.texi(,6224) @end smallexample
+../tar_texi/tar.texi(,6225)
+../tar_texi/tar.texi(,6226) If you specify either @option{--list}
(@option{-t}) or
+../tar_texi/tar.texi(,6227) @option{--extract} (@option{--get}, @option{-x}),
@command{tar}
+../tar_texi/tar.texi(,6228) operates on all the archive members in the archive.
+../tar_texi/tar.texi(,6229)
+../tar_texi/tar.texi(,6230) If run with @option{--diff} option, tar will
compare the archive with
+../tar_texi/tar.texi(,6231) the contents of the current working directory.
+../tar_texi/tar.texi(,6232)
+../tar_texi/tar.texi(,6233) If you specify any other operation, @command{tar}
does nothing.
+../tar_texi/tar.texi(,6234)
+../tar_texi/tar.texi(,6235) By default, @command{tar} takes file names from
the command line. However,
+../tar_texi/tar.texi(,6236) there are other ways to specify file or member
names, or to modify the
+../tar_texi/tar.texi(,6237) manner in which @command{tar} selects the files or
members upon which to
+../tar_texi/tar.texi(,6238) operate. In general, these methods work both for
specifying the names
+../tar_texi/tar.texi(,6239) of files and archive members.
+../tar_texi/tar.texi(,6240)
+../tar_texi/tar.texi(,6241) @node files
+../tar_texi/tar.texi(,6242) @section Reading Names from a File
+../tar_texi/tar.texi(,6243)
+../tar_texi/tar.texi(,6244) @cindex Reading file names from a file
+../tar_texi/tar.texi(,6245) @cindex Lists of file names
+../tar_texi/tar.texi(,6246) @cindex File Name arguments, alternatives
+../tar_texi/tar.texi(,6247) Instead of giving the names of files or archive
members on the command
+../tar_texi/tar.texi(,6248) line, you can put the names into a file, and then
use the
+../tar_texi/tar.texi(,6249) @address@hidden (@option{-T
+../tar_texi/tar.texi(,6250) @var{file-of-names}}) option to @command{tar}.
Give the name of the
+../tar_texi/tar.texi(,6251) file which contains the list of files to include
as the argument to
+../tar_texi/tar.texi(,6252) @option{--files-from}. In the list, the file
names should be separated by
+../tar_texi/tar.texi(,6253) newlines. You will frequently use this option
when you have generated
+../tar_texi/tar.texi(,6254) the list of files to archive with the
@command{find} utility.
+../tar_texi/tar.texi(,6255)
+../tar_texi/tar.texi(,6256) @table @option
+../tar_texi/tar.texi(,6257) @opindex files-from
+../tar_texi/tar.texi(,6258) @item address@hidden
+../tar_texi/tar.texi(,6259) @itemx -T @var{file-name}
+../tar_texi/tar.texi(,6260) Get names to extract or create from file
@var{file-name}.
+../tar_texi/tar.texi(,6261) @end table
+../tar_texi/tar.texi(,6262)
+../tar_texi/tar.texi(,6263) If you give a single dash as a file name for
@option{--files-from}, (i.e.,
+../tar_texi/tar.texi(,6264) you specify either @code{--files-from=-} or
@code{-T -}), then the file
+../tar_texi/tar.texi(,6265) names are read from standard input.
+../tar_texi/tar.texi(,6266)
+../tar_texi/tar.texi(,6267) Unless you are running @command{tar} with
@option{--create}, you can not use
+../tar_texi/tar.texi(,6268) both @code{--files-from=-} and @code{--file=-}
(@code{-f -}) in the same
+../tar_texi/tar.texi(,6269) command.
+../tar_texi/tar.texi(,6270)
+../tar_texi/tar.texi(,6271) Any number of @option{-T} options can be given in
the command line.
+../tar_texi/tar.texi(,6272)
+../tar_texi/tar.texi(,6273) The following example shows how to use
@command{find} to generate a list of
+../tar_texi/tar.texi(,6274) files smaller than 400K in length and put that
list into a file
+../tar_texi/tar.texi(,6275) called @file{small-files}. You can then use the
@option{-T} option to
+../tar_texi/tar.texi(,6276) @command{tar} to specify the files from that file,
@file{small-files}, to
+../tar_texi/tar.texi(,6277) create the archive @file{little.tgz}. (The
@option{-z} option to
+../tar_texi/tar.texi(,6278) @command{tar} compresses the archive with
@command{gzip}; @pxref{gzip} for
+../tar_texi/tar.texi(,6279) more information.)
+../tar_texi/tar.texi(,6280)
+../tar_texi/tar.texi(,6281) @smallexample
+../tar_texi/tar.texi(,6282) $ @kbd{find . -size -400 -print > small-files}
+../tar_texi/tar.texi(,6283) $ @kbd{tar -c -v -z -T small-files -f little.tgz}
+../tar_texi/tar.texi(,6284) @end smallexample
+../tar_texi/tar.texi(,6285)
+../tar_texi/tar.texi(,6286) @noindent
+../tar_texi/tar.texi(,6287) In the file list given by @option{-T} option, any
file name beginning
+../tar_texi/tar.texi(,6288) with @samp{-} character is considered a
@command{tar} option and is
+../tar_texi/tar.texi(GNUTAR,6289) processed address@hidden of @acronym{GNU}
@command{tar} up to 1.15.1
+../tar_texi/tar.texi(,6290) recognized only @option{-C} option in file lists,
and only if the
+../tar_texi/tar.texi(,6291) option and its argument occupied two consecutive
lines.} For example,
+../tar_texi/tar.texi(,6292) the common use of this feature is to change to
another directory by
+../tar_texi/tar.texi(,6293) specifying @option{-C} option:
+../tar_texi/tar.texi(,6294)
+../tar_texi/tar.texi(,6295) @smallexample
+../tar_texi/tar.texi(,6296) @group
+../tar_texi/tar.texi(,6297) $ @kbd{cat list}
+../tar_texi/tar.texi(,6298) -C/etc
+../tar_texi/tar.texi(,6299) passwd
+../tar_texi/tar.texi(,6300) hosts
+../tar_texi/tar.texi(,6301) -C/lib
+../tar_texi/tar.texi(,6302) libc.a
+../tar_texi/tar.texi(,6303) $ @kbd{tar -c -f foo.tar --files-from list}
+../tar_texi/tar.texi(,6304) @end group
+../tar_texi/tar.texi(,6305) @end smallexample
+../tar_texi/tar.texi(,6306)
+../tar_texi/tar.texi(,6307) @noindent
+../tar_texi/tar.texi(,6308) In this example, @command{tar} will first switch
to @file{/etc}
+../tar_texi/tar.texi(,6309) directory and add files @file{passwd} and
@file{hosts} to the
+../tar_texi/tar.texi(,6310) archive. Then it will change to @file{/lib}
directory and will archive
+../tar_texi/tar.texi(,6311) the file @file{libc.a}. Thus, the resulting
archive @file{foo.tar} will
+../tar_texi/tar.texi(,6312) contain:
+../tar_texi/tar.texi(,6313)
+../tar_texi/tar.texi(,6314) @smallexample
+../tar_texi/tar.texi(,6315) @group
+../tar_texi/tar.texi(,6316) $ @kbd{tar tf foo.tar}
+../tar_texi/tar.texi(,6317) passwd
+../tar_texi/tar.texi(,6318) hosts
+../tar_texi/tar.texi(,6319) libc.a
+../tar_texi/tar.texi(,6320) @end group
+../tar_texi/tar.texi(,6321) @end smallexample
+../tar_texi/tar.texi(,6322)
+../tar_texi/tar.texi(,6323) @noindent
+../tar_texi/tar.texi(xopindex,6324) @opindex address@hidden, using in
@option{--files-from} argument}../tar_texi/tar.texi(xopindex,6324)
+../tar_texi/tar.texi(,6325) Notice that the option parsing algorithm used with
@option{-T} is
+../tar_texi/tar.texi(,6326) stricter than the one used by shell. Namely, when
specifying option
+../tar_texi/tar.texi(,6327) arguments, you should observe the following rules:
+../tar_texi/tar.texi(,6328)
+../tar_texi/tar.texi(,6329) @itemize @bullet
+../tar_texi/tar.texi(,6330) @item
+../tar_texi/tar.texi(,6331) When using short (single-letter) option form, its
argument must
+../tar_texi/tar.texi(,6332) immediately follow the option letter, without any
intervening
+../tar_texi/tar.texi(,6333) whitespace. For example: @code{-Cdir}.
+../tar_texi/tar.texi(,6334)
+../tar_texi/tar.texi(,6335) @item
+../tar_texi/tar.texi(,6336) When using long option form, the option argument
must be separated
+../tar_texi/tar.texi(,6337) from the option by a single equal sign. No
whitespace is allowed on
+../tar_texi/tar.texi(,6338) any side of the equal sign. For example:
@code{--directory=dir}.
+../tar_texi/tar.texi(,6339)
+../tar_texi/tar.texi(,6340) @item
+../tar_texi/tar.texi(,6341) For both short and long option forms, the option
argument can be given
+../tar_texi/tar.texi(,6342) on the next line after the option name, e.g.:
+../tar_texi/tar.texi(,6343)
+../tar_texi/tar.texi(,6344) @smallexample
+../tar_texi/tar.texi(,6345) @group
+../tar_texi/tar.texi(,6346) --directory
+../tar_texi/tar.texi(,6347) dir
+../tar_texi/tar.texi(,6348) @end group
+../tar_texi/tar.texi(,6349) @end smallexample
+../tar_texi/tar.texi(,6350)
+../tar_texi/tar.texi(,6351) @noindent
+../tar_texi/tar.texi(,6352) and
+../tar_texi/tar.texi(,6353)
+../tar_texi/tar.texi(,6354) @smallexample
+../tar_texi/tar.texi(,6355) @group
+../tar_texi/tar.texi(,6356) -C
+../tar_texi/tar.texi(,6357) dir
+../tar_texi/tar.texi(,6358) @end group
+../tar_texi/tar.texi(,6359) @end smallexample
+../tar_texi/tar.texi(,6360) @end itemize
+../tar_texi/tar.texi(,6361)
+../tar_texi/tar.texi(,6362) @opindex add-file
+../tar_texi/tar.texi(,6363) If you happen to have a file whose name starts
with @samp{-},
+../tar_texi/tar.texi(,6364) precede it with @option{--add-file} option to
prevent it from
+../tar_texi/tar.texi(,6365) being recognized as an option. For example:
@code{--add-file=--my-file}.
+../tar_texi/tar.texi(,6366)
+../tar_texi/tar.texi(,6367) @menu
+../tar_texi/tar.texi(,6368) * nul::
+../tar_texi/tar.texi(,6369) @end menu
+../tar_texi/tar.texi(,6370)
+../tar_texi/tar.texi(,6371) @node nul
+../tar_texi/tar.texi(,6372) @subsection @code{NUL} Terminated File Names
+../tar_texi/tar.texi(,6373)
+../tar_texi/tar.texi(,6374) @cindex File names, terminated by @code{NUL}
+../tar_texi/tar.texi(,6375) @cindex @code{NUL} terminated file names
+../tar_texi/tar.texi(,6376) The @option{--null} option causes
+../tar_texi/tar.texi(,6377) @address@hidden (@option{-T @var{file-of-names}})
+../tar_texi/tar.texi(,6378) to read file names terminated by a @code{NUL}
instead of a newline, so
+../tar_texi/tar.texi(,6379) files whose names contain newlines can be archived
using
+../tar_texi/tar.texi(,6380) @option{--files-from}.
+../tar_texi/tar.texi(,6381)
+../tar_texi/tar.texi(,6382) @table @option
+../tar_texi/tar.texi(,6383) @opindex null
+../tar_texi/tar.texi(,6384) @item --null
+../tar_texi/tar.texi(,6385) Only consider @code{NUL} terminated file names,
instead of files that
+../tar_texi/tar.texi(,6386) terminate in a newline.
+../tar_texi/tar.texi(,6387) @end table
+../tar_texi/tar.texi(,6388)
+../tar_texi/tar.texi(,6389) The @option{--null} option is just like the one in
@acronym{GNU}
+../tar_texi/tar.texi(,6390) @command{xargs} and @command{cpio}, and is useful
with the
+../tar_texi/tar.texi(,6391) @option{-print0} predicate of @acronym{GNU}
@command{find}. In
+../tar_texi/tar.texi(,6392) @command{tar}, @option{--null} also disables
special handling for
+../tar_texi/tar.texi(,6393) file names that begin with dash.
+../tar_texi/tar.texi(,6394)
+../tar_texi/tar.texi(,6395) This example shows how to use @command{find} to
generate a list of files
+../tar_texi/tar.texi(,6396) larger than 800K in length and put that list into
a file called
+../tar_texi/tar.texi(,6397) @file{long-files}. The @option{-print0} option to
@command{find} is just
+../tar_texi/tar.texi(,6398) like @option{-print}, except that it separates
files with a @code{NUL}
+../tar_texi/tar.texi(,6399) rather than with a newline. You can then run
@command{tar} with both the
+../tar_texi/tar.texi(,6400) @option{--null} and @option{-T} options to specify
that @command{tar} get the
+../tar_texi/tar.texi(,6401) files from that file, @file{long-files}, to create
the archive
+../tar_texi/tar.texi(,6402) @file{big.tgz}. The @option{--null} option to
@command{tar} will cause
+../tar_texi/tar.texi(,6403) @command{tar} to recognize the @code{NUL}
separator between files.
+../tar_texi/tar.texi(,6404)
+../tar_texi/tar.texi(,6405) @smallexample
+../tar_texi/tar.texi(,6406) $ @kbd{find . -size +800 -print0 > long-files}
+../tar_texi/tar.texi(,6407) $ @kbd{tar -c -v --null --files-from=long-files
--file=big.tar}
+../tar_texi/tar.texi(,6408) @end smallexample
+../tar_texi/tar.texi(,6409)
+../tar_texi/tar.texi(FIXME,6410) @allow-recursion
+../tar_texi/tar.texi(FIXME,6410) @quote-arg
+../tar_texi/tar.texi(FIXME,6410)
+../tar_texi/tar.texi(,6411)
+../tar_texi/tar.texi(,6412) @node exclude
+../tar_texi/tar.texi(,6413) @section Excluding Some Files
+../tar_texi/tar.texi(UNREVISED,6414) @quotation
+../tar_texi/tar.texi(UNREVISED,6414) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,6414) @end quotation
+../tar_texi/tar.texi(UNREVISED,6414)
+../tar_texi/tar.texi(,6415)
+../tar_texi/tar.texi(,6416) @cindex File names, excluding files by
+../tar_texi/tar.texi(,6417) @cindex Excluding files by name and pattern
+../tar_texi/tar.texi(,6418) @cindex Excluding files by file system
+../tar_texi/tar.texi(,6419) To avoid operating on files whose names match a
particular pattern,
+../tar_texi/tar.texi(,6420) use the @option{--exclude} or
@option{--exclude-from} options.
+../tar_texi/tar.texi(,6421)
+../tar_texi/tar.texi(,6422) @table @option
+../tar_texi/tar.texi(,6423) @opindex exclude
+../tar_texi/tar.texi(,6424) @item address@hidden
+../tar_texi/tar.texi(,6425) Causes @command{tar} to ignore files that match
the @var{pattern}.
+../tar_texi/tar.texi(,6426) @end table
+../tar_texi/tar.texi(,6427)
+../tar_texi/tar.texi(,6428) @findex exclude
+../tar_texi/tar.texi(,6429) The @address@hidden option prevents any file or
+../tar_texi/tar.texi(,6430) member whose name matches the shell wildcard
(@var{pattern}) from
+../tar_texi/tar.texi(,6431) being operated on.
+../tar_texi/tar.texi(,6432) For example, to create an archive with all the
contents of the directory
+../tar_texi/tar.texi(,6433) @file{src} except for files whose names end in
@file{.o}, use the
+../tar_texi/tar.texi(,6434) command @samp{tar -cf src.tar --exclude='*.o' src}.
+../tar_texi/tar.texi(,6435)
+../tar_texi/tar.texi(,6436) You may give multiple @option{--exclude} options.
+../tar_texi/tar.texi(,6437)
+../tar_texi/tar.texi(,6438) @table @option
+../tar_texi/tar.texi(,6439) @opindex exclude-from
+../tar_texi/tar.texi(,6440) @item address@hidden
+../tar_texi/tar.texi(,6441) @itemx -X @var{file}
+../tar_texi/tar.texi(,6442) Causes @command{tar} to ignore files that match
the patterns listed in
+../tar_texi/tar.texi(,6443) @var{file}.
+../tar_texi/tar.texi(,6444) @end table
+../tar_texi/tar.texi(,6445)
+../tar_texi/tar.texi(,6446) @findex exclude-from
+../tar_texi/tar.texi(,6447) Use the @option{--exclude-from} option to read a
+../tar_texi/tar.texi(,6448) list of patterns, one per line, from @var{file};
@command{tar} will
+../tar_texi/tar.texi(,6449) ignore files matching those patterns. Thus if
@command{tar} is
+../tar_texi/tar.texi(,6450) called as @address@hidden -c -X foo .}} and the
file @file{foo} contains a
+../tar_texi/tar.texi(,6451) single line @file{*.o}, no files whose names end
in @file{.o} will be
+../tar_texi/tar.texi(,6452) added to the archive.
+../tar_texi/tar.texi(,6453)
+../tar_texi/tar.texi(,6454) @table @option
+../tar_texi/tar.texi(,6455) @opindex exclude-caches
+../tar_texi/tar.texi(,6456) @item --exclude-caches
+../tar_texi/tar.texi(,6457) Causes @command{tar} to ignore directories
containing a cache directory tag.
+../tar_texi/tar.texi(,6458) @end table
+../tar_texi/tar.texi(,6459)
+../tar_texi/tar.texi(,6460) @findex exclude-caches
+../tar_texi/tar.texi(,6461) When creating an archive, the
@option{--exclude-caches} option causes
+../tar_texi/tar.texi(,6462) @command{tar} to exclude all directories that
contain a @dfn{cache
+../tar_texi/tar.texi(,6463) directory tag}. A cache directory tag is a short
file with the
+../tar_texi/tar.texi(,6464) well-known name @file{CACHEDIR.TAG} and having a
standard header
+../tar_texi/tar.texi(,6465) specified in
@url{http://www.brynosaurus.com/cachedir/spec.html}.
+../tar_texi/tar.texi(,6466) Various applications write cache directory tags
into directories they
+../tar_texi/tar.texi(,6467) use to hold regenerable, non-precious data, so
that such data can be
+../tar_texi/tar.texi(,6468) more easily excluded from backups.
+../tar_texi/tar.texi(,6469)
+../tar_texi/tar.texi(,6470) @menu
+../tar_texi/tar.texi(,6471) * problems with exclude::
+../tar_texi/tar.texi(,6472) @end menu
+../tar_texi/tar.texi(,6473)
+../tar_texi/tar.texi(,6474) @node problems with exclude
+../tar_texi/tar.texi(,6475) @unnumberedsubsec Problems with Using the
@code{exclude} Options
+../tar_texi/tar.texi(,6476)
+../tar_texi/tar.texi(xopindex,6477) @opindex address@hidden, potential
problems with}../tar_texi/tar.texi(xopindex,6477)
+../tar_texi/tar.texi(,6478) Some users find @samp{exclude} options confusing.
Here are some common
+../tar_texi/tar.texi(,6479) pitfalls:
+../tar_texi/tar.texi(,6480)
+../tar_texi/tar.texi(,6481) @itemize @bullet
+../tar_texi/tar.texi(,6482) @item
+../tar_texi/tar.texi(,6483) The main operating mode of @command{tar} does not
act on a path name
+../tar_texi/tar.texi(,6484) explicitly listed on the command line if one of
its file name
+../tar_texi/tar.texi(,6485) components is excluded. In the example above, if
+../tar_texi/tar.texi(,6486) you create an archive and exclude files that end
with @samp{*.o}, but
+../tar_texi/tar.texi(,6487) explicitly name the file @samp{dir.o/foo} after
all the options have been
+../tar_texi/tar.texi(,6488) listed, @samp{dir.o/foo} will be excluded from the
archive.
+../tar_texi/tar.texi(,6489)
+../tar_texi/tar.texi(,6490) @item
+../tar_texi/tar.texi(,6491) You can sometimes confuse the meanings of
@option{--exclude} and
+../tar_texi/tar.texi(,6492) @option{--exclude-from}. Be careful: use
@option{--exclude} when files
+../tar_texi/tar.texi(,6493) to be excluded are given as a pattern on the
command line. Use
+../tar_texi/tar.texi(,6494) @option{--exclude-from} to introduce the name of a
file which contains
+../tar_texi/tar.texi(,6495) a list of patterns, one per line; each of these
patterns can exclude
+../tar_texi/tar.texi(,6496) zero, one, or many files.
+../tar_texi/tar.texi(,6497)
+../tar_texi/tar.texi(,6498) @item
+../tar_texi/tar.texi(,6499) When you use @address@hidden, be sure to quote the
+../tar_texi/tar.texi(GNUTAR,6500) @var{pattern} parameter, so
../tar_texi/tar.texi(GNUTAR,6500) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,6500) sees wildcard characters
+../tar_texi/tar.texi(,6501) like @samp{*}. If you do not do this, the shell
might expand the
+../tar_texi/tar.texi(,6502) @samp{*} itself using files at hand, so
@command{tar} might receive a
+../tar_texi/tar.texi(,6503) list of files instead of one pattern, or none at
all, making the
+../tar_texi/tar.texi(,6504) command somewhat illegal. This might not
correspond to what you want.
+../tar_texi/tar.texi(,6505)
+../tar_texi/tar.texi(,6506) For example, write:
+../tar_texi/tar.texi(,6507)
+../tar_texi/tar.texi(,6508) @smallexample
+../tar_texi/tar.texi(,6509) $ @kbd{tar -c -f @var{archive.tar} --exclude '*.o'
@var{directory}}
+../tar_texi/tar.texi(,6510) @end smallexample
+../tar_texi/tar.texi(,6511)
+../tar_texi/tar.texi(,6512) @noindent
+../tar_texi/tar.texi(,6513) rather than:
+../tar_texi/tar.texi(,6514)
+../tar_texi/tar.texi(,6515) @smallexample
+../tar_texi/tar.texi(,6516) # @emph{Wrong!}
+../tar_texi/tar.texi(,6517) $ @kbd{tar -c -f @var{archive.tar} --exclude *.o
@var{directory}}
+../tar_texi/tar.texi(,6518) @end smallexample
+../tar_texi/tar.texi(,6519)
+../tar_texi/tar.texi(,6520) @item
+../tar_texi/tar.texi(,6521) You must use use shell syntax, or globbing, rather
than @code{regexp}
+../tar_texi/tar.texi(,6522) syntax, when using exclude options in
@command{tar}. If you try to use
+../tar_texi/tar.texi(,6523) @code{regexp} syntax to describe files to be
excluded, your command
+../tar_texi/tar.texi(,6524) might fail.
+../tar_texi/tar.texi(,6525)
+../tar_texi/tar.texi(,6526) @item
+../tar_texi/tar.texi(FIXME,6529) @allow-recursion
+../tar_texi/tar.texi(FIXME,6529) @quote-arg
+../tar_texi/tar.texi(FIXME,6529)
+../tar_texi/tar.texi(,6530) In earlier versions of @command{tar}, what is now
the
+../tar_texi/tar.texi(,6531) @option{--exclude-from} option was called
@option{--exclude} instead.
+../tar_texi/tar.texi(,6532) Now, @option{--exclude} applies to patterns listed
on the command
+../tar_texi/tar.texi(,6533) line and @option{--exclude-from} applies to
patterns listed in a
+../tar_texi/tar.texi(,6534) file.
+../tar_texi/tar.texi(,6535)
+../tar_texi/tar.texi(,6536) @end itemize
+../tar_texi/tar.texi(,6537)
+../tar_texi/tar.texi(,6538) @node wildcards
+../tar_texi/tar.texi(,6539) @section Wildcards Patterns and Matching
+../tar_texi/tar.texi(,6540)
+../tar_texi/tar.texi(,6541) @dfn{Globbing} is the operation by which
@dfn{wildcard} characters,
+../tar_texi/tar.texi(,6542) @samp{*} or @samp{?} for example, are replaced and
expanded into all
+../tar_texi/tar.texi(GNUTAR,6543) existing files matching the given pattern.
../tar_texi/tar.texi(GNUTAR,6543) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,6543) can use wildcard
+../tar_texi/tar.texi(,6544) patterns for matching (or globbing) archive
members when extracting
+../tar_texi/tar.texi(,6545) from or listing an archive. Wildcard patterns are
also used for
+../tar_texi/tar.texi(,6546) verifying volume labels of @command{tar} archives.
This section has the
+../tar_texi/tar.texi(,6547) purpose of explaining wildcard syntax for
@command{tar}.
+../tar_texi/tar.texi(,6548)
+../tar_texi/tar.texi(FIXME,6549) @allow-recursion
+../tar_texi/tar.texi(FIXME,6549) @quote-arg
+../tar_texi/tar.texi(FIXME,6549)
+../tar_texi/tar.texi(,6550)
+../tar_texi/tar.texi(,6551) A @var{pattern} should be written according to
shell syntax, using wildcard
+../tar_texi/tar.texi(,6552) characters to effect globbing. Most characters in
the pattern stand
+../tar_texi/tar.texi(,6553) for themselves in the matched string, and case is
significant: @samp{a}
+../tar_texi/tar.texi(,6554) will match only @samp{a}, and not @samp{A}. The
character @samp{?} in the
+../tar_texi/tar.texi(,6555) pattern matches any single character in the
matched string. The character
+../tar_texi/tar.texi(,6556) @samp{*} in the pattern matches zero, one, or more
single characters in
+../tar_texi/tar.texi(,6557) the matched string. The character @samp{\} says
to take the following
+../tar_texi/tar.texi(,6558) character of the pattern @emph{literally}; it is
useful when one needs to
+../tar_texi/tar.texi(,6559) match the @samp{?}, @samp{*}, @samp{[} or @samp{\}
characters, themselves.
+../tar_texi/tar.texi(,6560)
+../tar_texi/tar.texi(,6561) The character @samp{[}, up to the matching
@samp{]}, introduces a character
+../tar_texi/tar.texi(,6562) class. A @dfn{character class} is a list of
acceptable characters
+../tar_texi/tar.texi(,6563) for the next single character of the matched
string. For example,
+../tar_texi/tar.texi(,6564) @samp{[abcde]} would match any of the first five
letters of the alphabet.
+../tar_texi/tar.texi(,6565) Note that within a character class, all of the
``special characters''
+../tar_texi/tar.texi(,6566) listed above other than @samp{\} lose their
special meaning; for example,
+../tar_texi/tar.texi(,6567) @samp{[-\\[*?]]} would match any of the
characters, @samp{-}, @samp{\},
+../tar_texi/tar.texi(,6568) @samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due
to parsing constraints,
+../tar_texi/tar.texi(,6569) the characters @samp{-} and @samp{]} must either
come @emph{first} or
+../tar_texi/tar.texi(,6570) @emph{last} in a character class.)
+../tar_texi/tar.texi(,6571)
+../tar_texi/tar.texi(,6572) @cindex Excluding characters from a character class
+../tar_texi/tar.texi(,6573) @cindex Character class, excluding characters from
+../tar_texi/tar.texi(,6574) If the first character of the class after the
opening @samp{[}
+../tar_texi/tar.texi(,6575) is @samp{!} or @samp{^}, then the meaning of the
class is reversed.
+../tar_texi/tar.texi(,6576) Rather than listing character to match, it lists
those characters which
+../tar_texi/tar.texi(,6577) are @emph{forbidden} as the next single character
of the matched string.
+../tar_texi/tar.texi(,6578)
+../tar_texi/tar.texi(,6579) Other characters of the class stand for
themselves. The special
+../tar_texi/tar.texi(,6580) construction @address@hidden@var{e}]}, using an
hyphen between two
+../tar_texi/tar.texi(,6581) letters, is meant to represent all characters
between @var{a} and
+../tar_texi/tar.texi(,6582) @var{e}, inclusive.
+../tar_texi/tar.texi(,6583)
+../tar_texi/tar.texi(FIXME,6585) @allow-recursion
+../tar_texi/tar.texi(FIXME,6585) @quote-arg
+../tar_texi/tar.texi(FIXME,6585)
+../tar_texi/tar.texi(,6586)
+../tar_texi/tar.texi(,6587) Periods (@samp{.}) or forward slashes (@samp{/})
are not considered
+../tar_texi/tar.texi(,6588) special for wildcard matches. However, if a
pattern completely matches
+../tar_texi/tar.texi(,6589) a directory prefix of a matched string, then it
matches the full matched
+../tar_texi/tar.texi(,6590) string: thus, excluding a directory also excludes
all the files beneath it.
+../tar_texi/tar.texi(,6591)
+../tar_texi/tar.texi(,6592) @menu
+../tar_texi/tar.texi(,6593) * controlling pattern-matching::
+../tar_texi/tar.texi(,6594) @end menu
+../tar_texi/tar.texi(,6595)
+../tar_texi/tar.texi(,6596) @node controlling pattern-matching
+../tar_texi/tar.texi(,6597) @unnumberedsubsec Controlling Pattern-Matching
+../tar_texi/tar.texi(,6598)
+../tar_texi/tar.texi(,6599) For the purposes of this section, we call
@dfn{exclusion members} all
+../tar_texi/tar.texi(,6600) member names obtained while processing
@option{--exclude} and
+../tar_texi/tar.texi(,6601) @option{--exclude-from} options, and
@dfn{inclusion members} those
+../tar_texi/tar.texi(,6602) member names that were given in the command line
or read from the file
+../tar_texi/tar.texi(,6603) specified with @option{--files-from} option.
+../tar_texi/tar.texi(,6604)
+../tar_texi/tar.texi(,6605) These two pairs of member lists are used in the
following operations:
+../tar_texi/tar.texi(,6606) @option{--diff}, @option{--extract},
@option{--list},
+../tar_texi/tar.texi(,6607) @option{--update}.
+../tar_texi/tar.texi(,6608)
+../tar_texi/tar.texi(,6609) There are no inclusion members in create mode
(@option{--create} and
+../tar_texi/tar.texi(,6610) @option{--append}), since in this mode the names
obtained from the
+../tar_texi/tar.texi(,6611) command line refer to @emph{files}, not archive
members.
+../tar_texi/tar.texi(,6612)
+../tar_texi/tar.texi(,6613) By default, inclusion members are compared with
archive members
+../tar_texi/tar.texi(GNUTAR,6614) literally @footnote{Notice that earlier
@acronym{GNU} @command{tar} versions used
+../tar_texi/tar.texi(,6615) globbing for inclusion members, which contradicted
to UNIX98
+../tar_texi/tar.texi(,6616) specification and was not documented.
@xref{Changes}, for more
+../tar_texi/tar.texi(,6617) information on this and other changes.} and
exclusion members are
+../tar_texi/tar.texi(,6618) treated as globbing patterns. For example:
+../tar_texi/tar.texi(,6619)
+../tar_texi/tar.texi(,6620) @smallexample
+../tar_texi/tar.texi(,6621) @group
+../tar_texi/tar.texi(,6622) $ @kbd{tar tf foo.tar}
+../tar_texi/tar.texi(,6623) a.c
+../tar_texi/tar.texi(,6624) b.c
+../tar_texi/tar.texi(,6625) a.txt
+../tar_texi/tar.texi(,6626) [remarks]
+../tar_texi/tar.texi(,6627) # @i{Member names are used verbatim:}
+../tar_texi/tar.texi(,6628) $ @kbd{tar -xf foo.tar -v '[remarks]'}
+../tar_texi/tar.texi(,6629) [remarks]
+../tar_texi/tar.texi(,6630) # @i{Exclude member names are globbed:}
+../tar_texi/tar.texi(,6631) $ @kbd{tar -xf foo.tar -v --exclude '*.c'}
+../tar_texi/tar.texi(,6632) a.txt
+../tar_texi/tar.texi(,6633) [remarks]
+../tar_texi/tar.texi(,6634) @end group
+../tar_texi/tar.texi(,6635) @end smallexample
+../tar_texi/tar.texi(,6636)
+../tar_texi/tar.texi(,6637) This behavior can be altered by using the
following options:
+../tar_texi/tar.texi(,6638)
+../tar_texi/tar.texi(,6639) @table @option
+../tar_texi/tar.texi(,6640) @opindex wildcards
+../tar_texi/tar.texi(,6641) @item --wildcards
+../tar_texi/tar.texi(,6642) Treat all member names as wildcards.
+../tar_texi/tar.texi(,6643)
+../tar_texi/tar.texi(,6644) @opindex no-wildcards
+../tar_texi/tar.texi(,6645) @item --no-wildcards
+../tar_texi/tar.texi(,6646) Treat all member names as literal strings.
+../tar_texi/tar.texi(,6647) @end table
+../tar_texi/tar.texi(,6648)
+../tar_texi/tar.texi(,6649) Thus, to extract files whose names end in
@samp{.c}, you can use:
+../tar_texi/tar.texi(,6650)
+../tar_texi/tar.texi(,6651) @smallexample
+../tar_texi/tar.texi(,6652) $ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
+../tar_texi/tar.texi(,6653) a.c
+../tar_texi/tar.texi(,6654) b.c
+../tar_texi/tar.texi(,6655) @end smallexample
+../tar_texi/tar.texi(,6656)
+../tar_texi/tar.texi(,6657) @noindent
+../tar_texi/tar.texi(,6658) Notice quoting of the pattern to prevent the shell
from interpreting
+../tar_texi/tar.texi(,6659) it.
+../tar_texi/tar.texi(,6660)
+../tar_texi/tar.texi(,6661) The effect of @option{--wildcards} option is
cancelled by
+../tar_texi/tar.texi(,6662) @option{--no-wildcards}. This can be used to pass
part of
+../tar_texi/tar.texi(,6663) the command line arguments verbatim and other part
as globbing
+../tar_texi/tar.texi(,6664) patterns. For example, the following invocation:
+../tar_texi/tar.texi(,6665)
+../tar_texi/tar.texi(,6666) @smallexample
+../tar_texi/tar.texi(,6667) $ @kbd{tar -xf foo.tar --wildcards '*.txt'
--no-wildcards '[remarks]'}
+../tar_texi/tar.texi(,6668) @end smallexample
+../tar_texi/tar.texi(,6669)
+../tar_texi/tar.texi(,6670) @noindent
+../tar_texi/tar.texi(,6671) instructs @command{tar} to extract from
@file{foo.tar} all files whose
+../tar_texi/tar.texi(,6672) names end in @samp{.txt} and the file named
@file{[remarks]}.
+../tar_texi/tar.texi(,6673)
+../tar_texi/tar.texi(,6674) Normally, a pattern matches a name if an initial
subsequence of the
+../tar_texi/tar.texi(,6675) name's components matches the pattern, where
@samp{*}, @samp{?}, and
+../tar_texi/tar.texi(,6676) @samp{[...]} are the usual shell wildcards,
@samp{\} escapes wildcards,
+../tar_texi/tar.texi(,6677) and wildcards can match @samp{/}.
+../tar_texi/tar.texi(,6678)
+../tar_texi/tar.texi(,6679) Other than optionally stripping leading @samp{/}
from names
+../tar_texi/tar.texi(,6680) (@pxref{absolute}), patterns and names are used
as-is. For
+../tar_texi/tar.texi(,6681) example, trailing @samp{/} is not trimmed from a
user-specified name
+../tar_texi/tar.texi(,6682) before deciding whether to exclude it.
+../tar_texi/tar.texi(,6683)
+../tar_texi/tar.texi(,6684) However, this matching procedure can be altered by
the options listed
+../tar_texi/tar.texi(,6685) below. These options accumulate. For example:
+../tar_texi/tar.texi(,6686)
+../tar_texi/tar.texi(,6687) @smallexample
+../tar_texi/tar.texi(,6688) --ignore-case --exclude='makefile'
--no-ignore-case ---exclude='readme'
+../tar_texi/tar.texi(,6689) @end smallexample
+../tar_texi/tar.texi(,6690)
+../tar_texi/tar.texi(,6691) @noindent
+../tar_texi/tar.texi(,6692) ignores case when excluding @samp{makefile}, but
not when excluding
+../tar_texi/tar.texi(,6693) @samp{readme}.
+../tar_texi/tar.texi(,6694)
+../tar_texi/tar.texi(,6695) @table @option
+../tar_texi/tar.texi(,6696) @opindex anchored
+../tar_texi/tar.texi(,6697) @opindex no-anchored
+../tar_texi/tar.texi(,6698) @item --anchored
+../tar_texi/tar.texi(,6699) @itemx --no-anchored
+../tar_texi/tar.texi(,6700) If anchored, a pattern must match an initial
subsequence
+../tar_texi/tar.texi(,6701) of the name's components. Otherwise, the pattern
can match any
+../tar_texi/tar.texi(,6702) subsequence. Default is @option{--no-anchored}
for exclusion members
+../tar_texi/tar.texi(,6703) and @option{--anchored} inclusion members.
+../tar_texi/tar.texi(,6704)
+../tar_texi/tar.texi(,6705) @opindex ignore-case
+../tar_texi/tar.texi(,6706) @opindex no-ignore-case
+../tar_texi/tar.texi(,6707) @item --ignore-case
+../tar_texi/tar.texi(,6708) @itemx --no-ignore-case
+../tar_texi/tar.texi(,6709) When ignoring case, upper-case patterns match
lower-case names and vice versa.
+../tar_texi/tar.texi(,6710) When not ignoring case (the default), matching is
case-sensitive.
+../tar_texi/tar.texi(,6711)
+../tar_texi/tar.texi(,6712) @opindex wildcards-match-slash
+../tar_texi/tar.texi(,6713) @opindex no-wildcards-match-slash
+../tar_texi/tar.texi(,6714) @item --wildcards-match-slash
+../tar_texi/tar.texi(,6715) @itemx --no-wildcards-match-slash
+../tar_texi/tar.texi(,6716) When wildcards match slash (the default for
exclusion members), a
+../tar_texi/tar.texi(,6717) wildcard like @samp{*} in the pattern can match a
@samp{/} in the
+../tar_texi/tar.texi(,6718) name. Otherwise, @samp{/} is matched only by
@samp{/}.
+../tar_texi/tar.texi(,6719)
+../tar_texi/tar.texi(,6720) @end table
+../tar_texi/tar.texi(,6721)
+../tar_texi/tar.texi(,6722) The @option{--recursion} and
@option{--no-recursion} options
+../tar_texi/tar.texi(,6723) (@pxref{recurse}) also affect how member patterns
are interpreted. If
+../tar_texi/tar.texi(,6724) recursion is in effect, a pattern matches a name
if it matches any of
+../tar_texi/tar.texi(,6725) the name's parent directories.
+../tar_texi/tar.texi(,6726)
+../tar_texi/tar.texi(,6727) The following table summarizes pattern-matching
default values:
+../tar_texi/tar.texi(,6728)
+../tar_texi/tar.texi(,6729) @multitable @columnfractions .3 .7
+../tar_texi/tar.texi(,6730) @headitem Members @tab Default settings
+../tar_texi/tar.texi(,6731) @item Inclusion @tab @option{--no-wildcards
--anchored --no-wildcards-match-slash}
+../tar_texi/tar.texi(,6732) @item Exclusion @tab @option{--wildcards
--no-anchored --wildcards-match-slash}
+../tar_texi/tar.texi(,6733) @end multitable
+../tar_texi/tar.texi(,6734)
+../tar_texi/tar.texi(,6735) @node quoting styles
+../tar_texi/tar.texi(,6736) @section Quoting Member Names
+../tar_texi/tar.texi(,6737)
+../tar_texi/tar.texi(,6738) When displaying member names, @command{tar} takes
care to avoid
+../tar_texi/tar.texi(,6739) ambiguities caused by certain characters. This is
called @dfn{name
+../tar_texi/tar.texi(,6740) quoting}. The characters in question are:
+../tar_texi/tar.texi(,6741)
+../tar_texi/tar.texi(,6742) @itemize @bullet
+../tar_texi/tar.texi(,6743) @item Non-printable control characters:
+../tar_texi/tar.texi(,6744)
+../tar_texi/tar.texi(,6745) @multitable @columnfractions 0.20 0.10 0.60
+../tar_texi/tar.texi(,6746) @headitem Character @tab ASCII @tab Character name
+../tar_texi/tar.texi(,6747) @item \a @tab 7 @tab Audible bell
+../tar_texi/tar.texi(,6748) @item \b @tab 8 @tab Backspace
+../tar_texi/tar.texi(,6749) @item \f @tab 12 @tab Form feed
+../tar_texi/tar.texi(,6750) @item \n @tab 10 @tab New line
+../tar_texi/tar.texi(,6751) @item \r @tab 13 @tab Carriage return
+../tar_texi/tar.texi(,6752) @item \t @tab 9 @tab Horizontal tabulation
+../tar_texi/tar.texi(,6753) @item \v @tab 11 @tab Vertical tabulation
+../tar_texi/tar.texi(,6754) @end multitable
+../tar_texi/tar.texi(,6755)
+../tar_texi/tar.texi(,6756) @item Space (ASCII 32)
+../tar_texi/tar.texi(,6757)
+../tar_texi/tar.texi(,6758) @item Single and double quotes (@samp{'} and
@samp{"})
+../tar_texi/tar.texi(,6759)
+../tar_texi/tar.texi(,6760) @item Backslash (@samp{\})
+../tar_texi/tar.texi(,6761) @end itemize
+../tar_texi/tar.texi(,6762)
+../tar_texi/tar.texi(,6763) The exact way @command{tar} uses to quote these
characters depends on
+../tar_texi/tar.texi(,6764) the @dfn{quoting style}. The default quoting
style, called
+../tar_texi/tar.texi(,6765) @dfn{escape} (see below), uses backslash notation
to represent control
+../tar_texi/tar.texi(,6766) characters, space and backslash. Using this
quoting style, control
+../tar_texi/tar.texi(,6767) characters are represented as listed in column
@samp{Character} in the
+../tar_texi/tar.texi(,6768) above table, a space is printed as @samp{\ } and a
backslash as @samp{\\}.
+../tar_texi/tar.texi(,6769)
+../tar_texi/tar.texi(GNUTAR,6770) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,6770) offers seven distinct quoting
styles, which can be selected
+../tar_texi/tar.texi(,6771) using @option{--quoting-style} option:
+../tar_texi/tar.texi(,6772)
+../tar_texi/tar.texi(,6773) @table @option
+../tar_texi/tar.texi(,6774) @item address@hidden
+../tar_texi/tar.texi(,6775) @opindex quoting-style
+../tar_texi/tar.texi(,6776)
+../tar_texi/tar.texi(,6777) Sets quoting style. Valid values for @var{style}
argument are:
+../tar_texi/tar.texi(,6778) literal, shell, shell-always, c, escape, locale,
clocale.
+../tar_texi/tar.texi(,6779) @end table
+../tar_texi/tar.texi(,6780)
+../tar_texi/tar.texi(,6781) These styles are described in detail below. To
illustrate their
+../tar_texi/tar.texi(,6782) effect, we will use an imaginary tar archive
@file{arch.tar}
+../tar_texi/tar.texi(,6783) containing the following members:
+../tar_texi/tar.texi(,6784)
+../tar_texi/tar.texi(,6785) @smallexample
+../tar_texi/tar.texi(,6786) @group
+../tar_texi/tar.texi(,6787) # 1. Contains horizontal tabulation character.
+../tar_texi/tar.texi(,6788) a tab
+../tar_texi/tar.texi(,6789) # 2. Contains newline character
+../tar_texi/tar.texi(,6790) a
+../tar_texi/tar.texi(,6791) newline
+../tar_texi/tar.texi(,6792) # 3. Contains a space
+../tar_texi/tar.texi(,6793) a space
+../tar_texi/tar.texi(,6794) # 4. Contains double quotes
+../tar_texi/tar.texi(,6795) a"double"quote
+../tar_texi/tar.texi(,6796) # 5. Contains single quotes
+../tar_texi/tar.texi(,6797) a'single'quote
+../tar_texi/tar.texi(,6798) # 6. Contains a backslash character:
+../tar_texi/tar.texi(,6799) a\backslash
+../tar_texi/tar.texi(,6800) @end group
+../tar_texi/tar.texi(,6801) @end smallexample
+../tar_texi/tar.texi(,6802)
+../tar_texi/tar.texi(,6803) Here is how usual @command{ls} command would have
listed them, if they
+../tar_texi/tar.texi(,6804) had existed in the current working directory:
+../tar_texi/tar.texi(,6805)
+../tar_texi/tar.texi(,6806) @smallexample
+../tar_texi/tar.texi(,6807) @group
+../tar_texi/tar.texi(,6808) $ @kbd{ls}
+../tar_texi/tar.texi(,6809) a\ttab
+../tar_texi/tar.texi(,6810) a\nnewline
+../tar_texi/tar.texi(,6811) a\ space
+../tar_texi/tar.texi(,6812) a"double"quote
+../tar_texi/tar.texi(,6813) a'single'quote
+../tar_texi/tar.texi(,6814) a\\backslash
+../tar_texi/tar.texi(,6815) @end group
+../tar_texi/tar.texi(,6816) @end smallexample
+../tar_texi/tar.texi(,6817)
+../tar_texi/tar.texi(,6818) Quoting styles:
+../tar_texi/tar.texi(,6819)
+../tar_texi/tar.texi(,6820) @table @samp
+../tar_texi/tar.texi(,6821) @item literal
+../tar_texi/tar.texi(,6822) No quoting, display each character as is:
+../tar_texi/tar.texi(,6823)
+../tar_texi/tar.texi(,6824) @smallexample
+../tar_texi/tar.texi(,6825) @group
+../tar_texi/tar.texi(,6826) $ @kbd{tar tf arch.tar --quoting-style=literal}
+../tar_texi/tar.texi(,6827) ./
+../tar_texi/tar.texi(,6828) ./a space
+../tar_texi/tar.texi(,6829) ./a'single'quote
+../tar_texi/tar.texi(,6830) ./a"double"quote
+../tar_texi/tar.texi(,6831) ./a\backslash
+../tar_texi/tar.texi(,6832) ./a tab
+../tar_texi/tar.texi(,6833) ./a
+../tar_texi/tar.texi(,6834) newline
+../tar_texi/tar.texi(,6835) @end group
+../tar_texi/tar.texi(,6836) @end smallexample
+../tar_texi/tar.texi(,6837)
+../tar_texi/tar.texi(,6838) @item shell
+../tar_texi/tar.texi(,6839) Display characters the same way Bourne shell does:
+../tar_texi/tar.texi(,6840) control characters, except @samp{\t} and
@samp{\n}, are printed using
+../tar_texi/tar.texi(,6841) backslash escapes, @samp{\t} and @samp{\n} are
printed as is, and a
+../tar_texi/tar.texi(,6842) single quote is printed as @samp{\'}. If a name
contains any quoted
+../tar_texi/tar.texi(,6843) characters, it is enclosed in single quotes. In
particular, if a name
+../tar_texi/tar.texi(,6844) contains single quotes, it is printed as several
single-quoted strings:
+../tar_texi/tar.texi(,6845)
+../tar_texi/tar.texi(,6846) @smallexample
+../tar_texi/tar.texi(,6847) @group
+../tar_texi/tar.texi(,6848) $ @kbd{tar tf arch.tar --quoting-style=shell}
+../tar_texi/tar.texi(,6849) ./
+../tar_texi/tar.texi(,6850) './a space'
+../tar_texi/tar.texi(,6851) './a'\''single'\''quote'
+../tar_texi/tar.texi(,6852) './a"double"quote'
+../tar_texi/tar.texi(,6853) './a\backslash'
+../tar_texi/tar.texi(,6854) './a tab'
+../tar_texi/tar.texi(,6855) './a
+../tar_texi/tar.texi(,6856) newline'
+../tar_texi/tar.texi(,6857) @end group
+../tar_texi/tar.texi(,6858) @end smallexample
+../tar_texi/tar.texi(,6859)
+../tar_texi/tar.texi(,6860) @item shell-always
+../tar_texi/tar.texi(,6861) Same as @samp{shell}, but the names are always
enclosed in single
+../tar_texi/tar.texi(,6862) quotes:
+../tar_texi/tar.texi(,6863)
+../tar_texi/tar.texi(,6864) @smallexample
+../tar_texi/tar.texi(,6865) @group
+../tar_texi/tar.texi(,6866) $ @kbd{tar tf arch.tar
--quoting-style=shell-always}
+../tar_texi/tar.texi(,6867) './'
+../tar_texi/tar.texi(,6868) './a space'
+../tar_texi/tar.texi(,6869) './a'\''single'\''quote'
+../tar_texi/tar.texi(,6870) './a"double"quote'
+../tar_texi/tar.texi(,6871) './a\backslash'
+../tar_texi/tar.texi(,6872) './a tab'
+../tar_texi/tar.texi(,6873) './a
+../tar_texi/tar.texi(,6874) newline'
+../tar_texi/tar.texi(,6875) @end group
+../tar_texi/tar.texi(,6876) @end smallexample
+../tar_texi/tar.texi(,6877)
+../tar_texi/tar.texi(,6878) @item c
+../tar_texi/tar.texi(,6879) Use the notation of the C programming language.
All names are
+../tar_texi/tar.texi(,6880) enclosed in double quotes. Control characters are
quoted using
+../tar_texi/tar.texi(,6881) backslash notations, double quotes are represented
as @samp{\"},
+../tar_texi/tar.texi(,6882) backslash characters are represented as @samp{\\}.
Single quotes and
+../tar_texi/tar.texi(,6883) spaces are not quoted:
+../tar_texi/tar.texi(,6884)
+../tar_texi/tar.texi(,6885) @smallexample
+../tar_texi/tar.texi(,6886) @group
+../tar_texi/tar.texi(,6887) $ @kbd{tar tf arch.tar --quoting-style=c}
+../tar_texi/tar.texi(,6888) "./"
+../tar_texi/tar.texi(,6889) "./a space"
+../tar_texi/tar.texi(,6890) "./a'single'quote"
+../tar_texi/tar.texi(,6891) "./a\"double\"quote"
+../tar_texi/tar.texi(,6892) "./a\\backslash"
+../tar_texi/tar.texi(,6893) "./a\ttab"
+../tar_texi/tar.texi(,6894) "./a\nnewline"
+../tar_texi/tar.texi(,6895) @end group
+../tar_texi/tar.texi(,6896) @end smallexample
+../tar_texi/tar.texi(,6897)
+../tar_texi/tar.texi(,6898) @item escape
+../tar_texi/tar.texi(,6899) Control characters are printed using backslash
notation, a space is
+../tar_texi/tar.texi(,6900) printed as @samp{\ } and a backslash as @samp{\\}.
This is the
+../tar_texi/tar.texi(,6901) default quoting style, unless it was changed when
configured the
+../tar_texi/tar.texi(,6902) package.
+../tar_texi/tar.texi(,6903)
+../tar_texi/tar.texi(,6904) @smallexample
+../tar_texi/tar.texi(,6905) @group
+../tar_texi/tar.texi(,6906) $ @kbd{tar tf arch.tar --quoting-style=escape}
+../tar_texi/tar.texi(,6907) ./
+../tar_texi/tar.texi(,6908) ./a space
+../tar_texi/tar.texi(,6909) ./a'single'quote
+../tar_texi/tar.texi(,6910) ./a"double"quote
+../tar_texi/tar.texi(,6911) ./a\\backslash
+../tar_texi/tar.texi(,6912) ./a\ttab
+../tar_texi/tar.texi(,6913) ./a\nnewline
+../tar_texi/tar.texi(,6914) @end group
+../tar_texi/tar.texi(,6915) @end smallexample
+../tar_texi/tar.texi(,6916)
+../tar_texi/tar.texi(,6917) @item locale
+../tar_texi/tar.texi(,6918) Control characters, single quote and backslash are
printed using
+../tar_texi/tar.texi(,6919) backslash notation. All names are quoted using
left and right
+../tar_texi/tar.texi(,6920) quotation marks, appropriate to the current
locale. If it does not
+../tar_texi/tar.texi(,6921) define quotation marks, use @samp{`} as left and
@samp{'} as right
+../tar_texi/tar.texi(,6922) quotation marks. Any occurrences of the right
quotation mark in a
+../tar_texi/tar.texi(,6923) name are escaped with @samp{\}, for example:
+../tar_texi/tar.texi(,6924)
+../tar_texi/tar.texi(,6925) For example:
+../tar_texi/tar.texi(,6926)
+../tar_texi/tar.texi(,6927) @smallexample
+../tar_texi/tar.texi(,6928) @group
+../tar_texi/tar.texi(,6929) $ @kbd{tar tf arch.tar --quoting-style=locale}
+../tar_texi/tar.texi(,6930) `./'
+../tar_texi/tar.texi(,6931) `./a space'
+../tar_texi/tar.texi(,6932) `./a\'single\'quote'
+../tar_texi/tar.texi(,6933) `./a"double"quote'
+../tar_texi/tar.texi(,6934) `./a\\backslash'
+../tar_texi/tar.texi(,6935) `./a\ttab'
+../tar_texi/tar.texi(,6936) `./a\nnewline'
+../tar_texi/tar.texi(,6937) @end group
+../tar_texi/tar.texi(,6938) @end smallexample
+../tar_texi/tar.texi(,6939)
+../tar_texi/tar.texi(,6940) @item clocale
+../tar_texi/tar.texi(,6941) Same as @samp{locale}, but @samp{"} is used for
both left and right
+../tar_texi/tar.texi(,6942) quotation marks, if not provided by the currently
selected locale:
+../tar_texi/tar.texi(,6943)
+../tar_texi/tar.texi(,6944) @smallexample
+../tar_texi/tar.texi(,6945) @group
+../tar_texi/tar.texi(,6946) $ @kbd{tar tf arch.tar --quoting-style=clocale}
+../tar_texi/tar.texi(,6947) "./"
+../tar_texi/tar.texi(,6948) "./a space"
+../tar_texi/tar.texi(,6949) "./a'single'quote"
+../tar_texi/tar.texi(,6950) "./a\"double\"quote"
+../tar_texi/tar.texi(,6951) "./a\\backslash"
+../tar_texi/tar.texi(,6952) "./a\ttab"
+../tar_texi/tar.texi(,6953) "./a\nnewline"
+../tar_texi/tar.texi(,6954) @end group
+../tar_texi/tar.texi(,6955) @end smallexample
+../tar_texi/tar.texi(,6956) @end table
+../tar_texi/tar.texi(,6957)
+../tar_texi/tar.texi(,6958) You can specify which characters should be quoted
in addition to those
+../tar_texi/tar.texi(,6959) implied by the current quoting style:
+../tar_texi/tar.texi(,6960)
+../tar_texi/tar.texi(,6961) @table @option
+../tar_texi/tar.texi(,6962) @item address@hidden
+../tar_texi/tar.texi(,6963) Always quote characters from @var{string}, even if
the selected
+../tar_texi/tar.texi(,6964) quoting style would not quote them.
+../tar_texi/tar.texi(,6965) @end table
+../tar_texi/tar.texi(,6966)
+../tar_texi/tar.texi(,6967) For example, using @samp{escape} quoting (compare
with the usual
+../tar_texi/tar.texi(,6968) escape listing above):
+../tar_texi/tar.texi(,6969)
+../tar_texi/tar.texi(,6970) @smallexample
+../tar_texi/tar.texi(,6971) @group
+../tar_texi/tar.texi(,6972) $ @kbd{tar tf arch.tar --quoting-style=escape
--quote-chars=' "'}
+../tar_texi/tar.texi(,6973) ./
+../tar_texi/tar.texi(,6974) ./a\ space
+../tar_texi/tar.texi(,6975) ./a'single'quote
+../tar_texi/tar.texi(,6976) ./a\"double\"quote
+../tar_texi/tar.texi(,6977) ./a\\backslash
+../tar_texi/tar.texi(,6978) ./a\ttab
+../tar_texi/tar.texi(,6979) ./a\nnewline
+../tar_texi/tar.texi(,6980) @end group
+../tar_texi/tar.texi(,6981) @end smallexample
+../tar_texi/tar.texi(,6982)
+../tar_texi/tar.texi(,6983) To disable quoting of such additional characters,
use the following
+../tar_texi/tar.texi(,6984) option:
+../tar_texi/tar.texi(,6985)
+../tar_texi/tar.texi(,6986) @table @option
+../tar_texi/tar.texi(,6987) @item address@hidden
+../tar_texi/tar.texi(,6988) Remove characters listed in @var{string} from the
list of quoted
+../tar_texi/tar.texi(,6989) characters set by the previous
@option{--quote-chars} option.
+../tar_texi/tar.texi(,6990) @end table
+../tar_texi/tar.texi(,6991)
+../tar_texi/tar.texi(,6992) This option is particularly useful if you have
added
+../tar_texi/tar.texi(,6993) @option{--quote-chars} to your @env{TAR_OPTIONS}
(@pxref{TAR_OPTIONS})
+../tar_texi/tar.texi(,6994) and wish to disable it for the current invocation.
+../tar_texi/tar.texi(,6995)
+../tar_texi/tar.texi(,6996) Note, that @option{--no-quote-chars} does
@emph{not} disable those
+../tar_texi/tar.texi(,6997) characters that are quoted by default in the
selected quoting style.
+../tar_texi/tar.texi(,6998)
+../tar_texi/tar.texi(,6999) @node transform
+../tar_texi/tar.texi(,7000) @section Modifying File and Member Names
+../tar_texi/tar.texi(,7001)
+../tar_texi/tar.texi(,7002) @command{Tar} archives contain detailed
information about files stored
+../tar_texi/tar.texi(,7003) in them and full file names are part of that
information. When
+../tar_texi/tar.texi(,7004) storing file to an archive, its file name is
recorded in the archive
+../tar_texi/tar.texi(,7005) along with the actual file contents. When
restoring from an archive,
+../tar_texi/tar.texi(,7006) a file is created on disk with exactly the same
name as that stored
+../tar_texi/tar.texi(,7007) in the archive. In the majority of cases this is
the desired behavior
+../tar_texi/tar.texi(,7008) of a file archiver. However, there are some cases
when it is not.
+../tar_texi/tar.texi(,7009)
+../tar_texi/tar.texi(,7010) First of all, it is often unsafe to extract
archive members with
+../tar_texi/tar.texi(GNUTAR,7011) absolute file names or those that begin with
a @file{../}. ../tar_texi/tar.texi(GNUTAR,7011) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7011)
+../tar_texi/tar.texi(,7012) takes special precautions when extracting such
names and provides a
+../tar_texi/tar.texi(,7013) special option for handling them, which is
described in
+../tar_texi/tar.texi(,7014) @ref{absolute}.
+../tar_texi/tar.texi(,7015)
+../tar_texi/tar.texi(,7016) Secondly, you may wish to extract file names
without some leading
+../tar_texi/tar.texi(,7017) directory components, or with otherwise modified
names. In other
+../tar_texi/tar.texi(,7018) cases it is desirable to store files under
differing names in the
+../tar_texi/tar.texi(,7019) archive.
+../tar_texi/tar.texi(,7020)
+../tar_texi/tar.texi(GNUTAR,7021) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7021) provides two options for these
needs.
+../tar_texi/tar.texi(,7022)
+../tar_texi/tar.texi(,7023) @table @option
+../tar_texi/tar.texi(,7024) @opindex strip-components
+../tar_texi/tar.texi(,7025) @item address@hidden
+../tar_texi/tar.texi(,7026) Strip given @var{number} of leading components
from file names before
+../tar_texi/tar.texi(,7027) extraction.
+../tar_texi/tar.texi(,7028) @end table
+../tar_texi/tar.texi(,7029)
+../tar_texi/tar.texi(,7030) For example, suppose you have archived whole
@file{/usr} hierarchy to
+../tar_texi/tar.texi(,7031) a tar archive named @file{usr.tar}. Among other
files, this archive
+../tar_texi/tar.texi(,7032) contains @file{usr/include/stdlib.h}, which you
wish to extract to
+../tar_texi/tar.texi(,7033) the current working directory. To do so, you type:
+../tar_texi/tar.texi(,7034)
+../tar_texi/tar.texi(,7035) @smallexample
+../tar_texi/tar.texi(,7036) $ @kbd{tar -xf usr.tar --strip=2
usr/include/stdlib.h}
+../tar_texi/tar.texi(,7037) @end smallexample
+../tar_texi/tar.texi(,7038)
+../tar_texi/tar.texi(,7039) The option @option{--strip=2} instructs
@command{tar} to strip the
+../tar_texi/tar.texi(,7040) two leading components (@file{usr/} and
@file{include/}) off the file
+../tar_texi/tar.texi(,7041) name.
+../tar_texi/tar.texi(,7042)
+../tar_texi/tar.texi(,7043) If you add to the above invocation
@option{--verbose} (@option{-v})
+../tar_texi/tar.texi(,7044) option, you will note that the verbose listing
still contains the
+../tar_texi/tar.texi(,7045) full file name, with the two removed components
still in place. This
+../tar_texi/tar.texi(,7046) can be inconvenient, so @command{tar} provides a
special option for
+../tar_texi/tar.texi(,7047) altering this behavior:
+../tar_texi/tar.texi(,7048)
+../tar_texi/tar.texi(,7049) @anchor{show-transformed-names}
+../tar_texi/tar.texi(,7050) @table @option
+../tar_texi/tar.texi(,7051) @opindex show-transformed-names
+../tar_texi/tar.texi(,7052) @item --show-transformed-names
+../tar_texi/tar.texi(,7053) Display file or member names with all requested
transformations
+../tar_texi/tar.texi(,7054) applied.
+../tar_texi/tar.texi(,7055) @end table
+../tar_texi/tar.texi(,7056)
+../tar_texi/tar.texi(,7057) @noindent
+../tar_texi/tar.texi(,7058) For example:
+../tar_texi/tar.texi(,7059)
+../tar_texi/tar.texi(,7060) @smallexample
+../tar_texi/tar.texi(,7061) @group
+../tar_texi/tar.texi(,7062) $ @kbd{tar -xf usr.tar -v --strip=2
usr/include/stdlib.h}
+../tar_texi/tar.texi(,7063) usr/include/stdlib.h
+../tar_texi/tar.texi(,7064) $ @kbd{tar -xf usr.tar -v --strip=2
--show-transformed usr/include/stdlib.h}
+../tar_texi/tar.texi(,7065) stdlib.h
+../tar_texi/tar.texi(,7066) @end group
+../tar_texi/tar.texi(,7067) @end smallexample
+../tar_texi/tar.texi(,7068)
+../tar_texi/tar.texi(,7069) Notice that in both cases the file is
@file{stdlib.h} extracted to the
+../tar_texi/tar.texi(,7070) current working directory,
@option{--show-transformed-names} affects
+../tar_texi/tar.texi(,7071) only the way its name is displayed.
+../tar_texi/tar.texi(,7072)
+../tar_texi/tar.texi(,7073) This option is especially useful for verifying
whether the invocation
+../tar_texi/tar.texi(,7074) will have the desired effect. Thus, before running
+../tar_texi/tar.texi(,7075)
+../tar_texi/tar.texi(,7076) @smallexample
+../tar_texi/tar.texi(,7077) $ @kbd{tar -x address@hidden
+../tar_texi/tar.texi(,7078) @end smallexample
+../tar_texi/tar.texi(,7079)
+../tar_texi/tar.texi(,7080) @noindent
+../tar_texi/tar.texi(,7081) it is often advisable to run
+../tar_texi/tar.texi(,7082)
+../tar_texi/tar.texi(,7083) @smallexample
+../tar_texi/tar.texi(,7084) $ @kbd{tar -t -v --show-transformed address@hidden
+../tar_texi/tar.texi(,7085) @end smallexample
+../tar_texi/tar.texi(,7086)
+../tar_texi/tar.texi(,7087) @noindent
+../tar_texi/tar.texi(,7088) to make sure the command will produce the intended
results.
+../tar_texi/tar.texi(,7089)
+../tar_texi/tar.texi(,7090) In case you need to apply more complex
modifications to the file name,
+../tar_texi/tar.texi(GNUTAR,7091) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7091) provides a general-purpose
transformation option:
+../tar_texi/tar.texi(,7092)
+../tar_texi/tar.texi(,7093) @table @option
+../tar_texi/tar.texi(,7094) @opindex transform
+../tar_texi/tar.texi(,7095) @item address@hidden
+../tar_texi/tar.texi(,7096) Modify file names using supplied @var{expression}.
+../tar_texi/tar.texi(,7097) @end table
+../tar_texi/tar.texi(,7098)
+../tar_texi/tar.texi(,7099) @noindent
+../tar_texi/tar.texi(,7100) The @var{expression} is a @command{sed}-like
replace expression of the
+../tar_texi/tar.texi(,7101) form:
+../tar_texi/tar.texi(,7102)
+../tar_texi/tar.texi(,7103) @smallexample
+../tar_texi/tar.texi(,7104) s/@var{regexp}/@var{replace}/address@hidden
+../tar_texi/tar.texi(,7105) @end smallexample
+../tar_texi/tar.texi(,7106)
+../tar_texi/tar.texi(,7107) @noindent
+../tar_texi/tar.texi(,7108) where @var{regexp} is a @dfn{regular expression},
@var{replace} is a
+../tar_texi/tar.texi(,7109) replacement for each file name part that matches
@var{regexp}. Both
+../tar_texi/tar.texi(,7110) @var{regexp} and @var{replace} are described in
detail in
+../tar_texi/tar.texi(,7111) @ref{The "s" Command, The "s" Command, The `s'
Command, sed, GNU sed}.
+../tar_texi/tar.texi(,7112)
+../tar_texi/tar.texi(,7113) Supported @var{flags} are:
+../tar_texi/tar.texi(,7114)
+../tar_texi/tar.texi(,7115) @table @samp
+../tar_texi/tar.texi(,7116) @item g
+../tar_texi/tar.texi(,7117) Apply the replacement to @emph{all} matches to the
@var{regexp}, not
+../tar_texi/tar.texi(,7118) just the first.
+../tar_texi/tar.texi(,7119)
+../tar_texi/tar.texi(,7120) @item i
+../tar_texi/tar.texi(,7121) Use case-insensitive matching
+../tar_texi/tar.texi(,7122)
+../tar_texi/tar.texi(,7123) @item x
+../tar_texi/tar.texi(,7124) @var{regexp} is an @dfn{extended regular
expression} (@pxref{Extended
+../tar_texi/tar.texi(,7125) regexps, Extended regular expressions, Extended
regular expressions,
+../tar_texi/tar.texi(,7126) sed, GNU sed}).
+../tar_texi/tar.texi(,7127)
+../tar_texi/tar.texi(,7128) @item @var{number}
+../tar_texi/tar.texi(,7129) Only replace the @var{number}th match of the
@var{regexp}.
+../tar_texi/tar.texi(,7130)
+../tar_texi/tar.texi(,7131) Note: the @var{posix} standard does not specify
what should happen
+../tar_texi/tar.texi(GNUTAR,7132) when you mix the @samp{g} and @var{number}
modifiers. ../tar_texi/tar.texi(GNUTAR,7132) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7132)
+../tar_texi/tar.texi(,7133) follows the GNU @command{sed} implementation in
this regard, so
+../tar_texi/tar.texi(,7134) the the interaction is defined to be: ignore
matches before the
+../tar_texi/tar.texi(,7135) @var{number}th, and then match and replace all
matches from the
+../tar_texi/tar.texi(,7136) @var{number}th on.
+../tar_texi/tar.texi(,7137)
+../tar_texi/tar.texi(,7138) @end table
+../tar_texi/tar.texi(,7139)
+../tar_texi/tar.texi(,7140) Any delimiter can be used in lieue of @samp{/},
the only requirement being
+../tar_texi/tar.texi(,7141) that it be used consistently throughout the
expression. For example,
+../tar_texi/tar.texi(,7142) the following two expressions are equivalent:
+../tar_texi/tar.texi(,7143)
+../tar_texi/tar.texi(,7144) @smallexample
+../tar_texi/tar.texi(,7145) @group
+../tar_texi/tar.texi(,7146) s/one/two/
+../tar_texi/tar.texi(,7147) s,one,two,
+../tar_texi/tar.texi(,7148) @end group
+../tar_texi/tar.texi(,7149) @end smallexample
+../tar_texi/tar.texi(,7150)
+../tar_texi/tar.texi(,7151) Changing delimiters is often useful when the
@var{regex} contains
+../tar_texi/tar.texi(,7152) slashes. For example, it is more convenient to
write @code{s,/,-,} than
+../tar_texi/tar.texi(,7153) @code{s/\//-/}.
+../tar_texi/tar.texi(,7154)
+../tar_texi/tar.texi(,7155) Here are several examples of @option{--transform}
usage:
+../tar_texi/tar.texi(,7156)
+../tar_texi/tar.texi(,7157) @enumerate
+../tar_texi/tar.texi(,7158) @item Extract @file{usr/} hierarchy into
@file{usr/local/}:
+../tar_texi/tar.texi(,7159)
+../tar_texi/tar.texi(,7160) @smallexample
+../tar_texi/tar.texi(,7161) $ @kbd{tar --transform='s,usr/,usr/local/,' -x -f
arch.tar}
+../tar_texi/tar.texi(,7162) @end smallexample
+../tar_texi/tar.texi(,7163)
+../tar_texi/tar.texi(,7164) @item Strip two leading directory components
(equivalent to
+../tar_texi/tar.texi(,7165) @option{--strip-components=2}):
+../tar_texi/tar.texi(,7166)
+../tar_texi/tar.texi(,7167) @smallexample
+../tar_texi/tar.texi(,7168) $ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f
arch.tar}
+../tar_texi/tar.texi(,7169) @end smallexample
+../tar_texi/tar.texi(,7170)
+../tar_texi/tar.texi(,7171) @item Prepend @file{/prefix/} to each file name:
+../tar_texi/tar.texi(,7172)
+../tar_texi/tar.texi(,7173) @smallexample
+../tar_texi/tar.texi(,7174) $ @kbd{tar --transform 's,^,/prefix/,' -x -f
arch.tar}
+../tar_texi/tar.texi(,7175) @end smallexample
+../tar_texi/tar.texi(,7176)
+../tar_texi/tar.texi(,7177) @item Convert each file name to lower case:
+../tar_texi/tar.texi(,7178)
+../tar_texi/tar.texi(,7179) @smallexample
+../tar_texi/tar.texi(,7180) $ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+../tar_texi/tar.texi(,7181) @end smallexample
+../tar_texi/tar.texi(,7182)
+../tar_texi/tar.texi(,7183) @end enumerate
+../tar_texi/tar.texi(,7184)
+../tar_texi/tar.texi(,7185) Unlike @option{--strip-components},
@option{--transform} can be used
+../tar_texi/tar.texi(GNUTAR,7186) in any ../tar_texi/tar.texi(GNUTAR,7186)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,7186) operation mode.
For example, the following command
+../tar_texi/tar.texi(,7187) adds files to the archive while replacing the
leading @file{usr/}
+../tar_texi/tar.texi(,7188) component with @file{var/}:
+../tar_texi/tar.texi(,7189)
+../tar_texi/tar.texi(,7190) @smallexample
+../tar_texi/tar.texi(,7191) $ @kbd{tar -cf arch.tar
--transform='s,^usr/,var/,' /}
+../tar_texi/tar.texi(,7192) @end smallexample
+../tar_texi/tar.texi(,7193)
+../tar_texi/tar.texi(,7194) To test @option{--transform} effect we suggest
using
+../tar_texi/tar.texi(,7195) @option{--show-transformed-names} option:
+../tar_texi/tar.texi(,7196)
+../tar_texi/tar.texi(,7197) @smallexample
+../tar_texi/tar.texi(,7198) $ @kbd{tar -cf arch.tar
--transform='s,^usr/,var/,' \
+../tar_texi/tar.texi(,7199) --verbose --show-transformed-names /}
+../tar_texi/tar.texi(,7200) @end smallexample
+../tar_texi/tar.texi(,7201)
+../tar_texi/tar.texi(,7202) If both @option{--strip-components} and
@option{--transform} are used
+../tar_texi/tar.texi(,7203) together, then @option{--transform} is applied
first, and the required
+../tar_texi/tar.texi(,7204) number of components is then stripped from its
result.
+../tar_texi/tar.texi(,7205)
+../tar_texi/tar.texi(,7206) @node after
+../tar_texi/tar.texi(,7207) @section Operating Only on New Files
+../tar_texi/tar.texi(UNREVISED,7208) @quotation
+../tar_texi/tar.texi(UNREVISED,7208) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7208) @end quotation
+../tar_texi/tar.texi(UNREVISED,7208)
+../tar_texi/tar.texi(,7209)
+../tar_texi/tar.texi(,7210) @cindex Excluding file by age
+../tar_texi/tar.texi(,7211) @cindex Data Modification time, excluding files by
+../tar_texi/tar.texi(,7212) @cindex Modification time, excluding files by
+../tar_texi/tar.texi(,7213) @cindex Age, excluding files by
+../tar_texi/tar.texi(,7214) The @address@hidden (@address@hidden,
+../tar_texi/tar.texi(,7215) @option{-N @var{date}}) option causes
@command{tar} to only work on
+../tar_texi/tar.texi(,7216) files whose data modification or status change
times are newer than
+../tar_texi/tar.texi(,7217) the @var{date} given. If @var{date} starts with
@samp{/} or @samp{.},
+../tar_texi/tar.texi(,7218) it is taken to be a file name; the data
modification time of that file
+../tar_texi/tar.texi(,7219) is used as the date. If you use this option when
creating or appending
+../tar_texi/tar.texi(,7220) to an archive, the archive will only include new
files. If you use
+../tar_texi/tar.texi(,7221) @option{--after-date} when extracting an archive,
@command{tar} will
+../tar_texi/tar.texi(,7222) only extract files newer than the @var{date} you
specify.
+../tar_texi/tar.texi(,7223)
+../tar_texi/tar.texi(,7224) If you only want @command{tar} to make the date
comparison based on
+../tar_texi/tar.texi(,7225) modification of the file's data (rather than status
+../tar_texi/tar.texi(,7226) changes), then use the @address@hidden option.
+../tar_texi/tar.texi(,7227)
+../tar_texi/tar.texi(,7228) You may use these options with any operation.
Note that these options
+../tar_texi/tar.texi(,7229) differ from the @option{--update} (@option{-u})
operation in that they
+../tar_texi/tar.texi(,7230) allow you to specify a particular date against
which @command{tar} can
+../tar_texi/tar.texi(,7231) compare when deciding whether or not to archive
the files.
+../tar_texi/tar.texi(,7232)
+../tar_texi/tar.texi(,7233) @table @option
+../tar_texi/tar.texi(,7234) @opindex after-date
+../tar_texi/tar.texi(,7235) @opindex newer
+../tar_texi/tar.texi(,7236) @item address@hidden
+../tar_texi/tar.texi(,7237) @itemx address@hidden
+../tar_texi/tar.texi(,7238) @itemx -N @var{date}
+../tar_texi/tar.texi(,7239) Only store files newer than @var{date}.
+../tar_texi/tar.texi(,7240)
+../tar_texi/tar.texi(,7241) Acts on files only if their data modification or
status change times are
+../tar_texi/tar.texi(,7242) later than @var{date}. Use in conjunction with
any operation.
+../tar_texi/tar.texi(,7243)
+../tar_texi/tar.texi(,7244) If @var{date} starts with @samp{/} or @samp{.}, it
is taken to be a file
+../tar_texi/tar.texi(,7245) name; the data modification time of that file is
used as the date.
+../tar_texi/tar.texi(,7246)
+../tar_texi/tar.texi(,7247) @opindex newer-mtime
+../tar_texi/tar.texi(,7248) @item address@hidden
+../tar_texi/tar.texi(,7249) Acts like @option{--after-date}, but only looks at
data modification times.
+../tar_texi/tar.texi(,7250) @end table
+../tar_texi/tar.texi(,7251)
+../tar_texi/tar.texi(,7252) These options limit @command{tar} to operate only
on files which have
+../tar_texi/tar.texi(,7253) been modified after the date specified. A file's
status is considered to have
+../tar_texi/tar.texi(,7254) changed if its contents have been modified, or if
its owner,
+../tar_texi/tar.texi(,7255) permissions, and so forth, have been changed.
(For more information on
+../tar_texi/tar.texi(,7256) how to specify a date, see @ref{Date input
formats}; remember that the
+../tar_texi/tar.texi(,7257) entire date argument must be quoted if it contains
any spaces.)
+../tar_texi/tar.texi(,7258)
+../tar_texi/tar.texi(,7259) Gurus would say that @option{--after-date} tests
both the data
+../tar_texi/tar.texi(,7260) modification time (@code{mtime}, the time the
contents of the file
+../tar_texi/tar.texi(,7261) were last modified) and the status change time
(@code{ctime}, the time
+../tar_texi/tar.texi(,7262) the file's status was last changed: owner,
permissions, etc.@:)
+../tar_texi/tar.texi(,7263) fields, while @option{--newer-mtime} tests only
the @code{mtime}
+../tar_texi/tar.texi(,7264) field.
+../tar_texi/tar.texi(,7265)
+../tar_texi/tar.texi(,7266) To be precise, @option{--after-date} checks
@emph{both} @code{mtime} and
+../tar_texi/tar.texi(,7267) @code{ctime} and processes the file if either one
is more recent than
+../tar_texi/tar.texi(,7268) @var{date}, while @option{--newer-mtime} only
checks @code{mtime} and
+../tar_texi/tar.texi(,7269) disregards @code{ctime}. Neither does it use
@code{atime} (the last time the
+../tar_texi/tar.texi(,7270) contents of the file were looked at).
+../tar_texi/tar.texi(,7271)
+../tar_texi/tar.texi(,7272) Date specifiers can have embedded spaces. Because
of this, you may need
+../tar_texi/tar.texi(,7273) to quote date arguments to keep the shell from
parsing them as separate
+../tar_texi/tar.texi(,7274) arguments. For example, the following command
will add to the archive
+../tar_texi/tar.texi(,7275) all the files modified less than two days ago:
+../tar_texi/tar.texi(,7276)
+../tar_texi/tar.texi(,7277) @smallexample
+../tar_texi/tar.texi(,7278) $ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
+../tar_texi/tar.texi(,7279) @end smallexample
+../tar_texi/tar.texi(,7280)
+../tar_texi/tar.texi(,7281) When any of these options is used with the option
@option{--verbose}
+../tar_texi/tar.texi(GNUTAR,7282) (@pxref{verbose tutorial})
../tar_texi/tar.texi(GNUTAR,7282) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7282) will try to convert the
specified
+../tar_texi/tar.texi(,7283) date back to its textual representation and
compare that with the
+../tar_texi/tar.texi(,7284) one given with the option. If the two dates
differ, @command{tar} will
+../tar_texi/tar.texi(,7285) print a warning saying what date it will use.
This is to help user
+../tar_texi/tar.texi(,7286) ensure he is using the right date. For example:
+../tar_texi/tar.texi(,7287)
+../tar_texi/tar.texi(,7288) @smallexample
+../tar_texi/tar.texi(,7289) @group
+../tar_texi/tar.texi(,7290) $ @kbd{tar -c -f archive.tar --after-date='10 days
ago' .}
+../tar_texi/tar.texi(,7291) tar: Option --after-date: Treating date `10 days
ago' as 2006-06-11
+../tar_texi/tar.texi(,7292) 13:19:37.232434
+../tar_texi/tar.texi(,7293) @end group
+../tar_texi/tar.texi(,7294) @end smallexample
+../tar_texi/tar.texi(,7295)
+../tar_texi/tar.texi(,7296) @quotation
+../tar_texi/tar.texi(,7297) @strong{Please Note:} @option{--after-date} and
@option{--newer-mtime}
+../tar_texi/tar.texi(,7298) should not be used for incremental backups.
@xref{Incremental Dumps},
+../tar_texi/tar.texi(,7299) for proper way of creating incremental backups.
+../tar_texi/tar.texi(,7300) @end quotation
+../tar_texi/tar.texi(,7301)
+../tar_texi/tar.texi(,7302) @node recurse
+../tar_texi/tar.texi(,7303) @section Descending into Directories
+../tar_texi/tar.texi(UNREVISED,7304) @quotation
+../tar_texi/tar.texi(UNREVISED,7304) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7304) @end quotation
+../tar_texi/tar.texi(UNREVISED,7304)
+../tar_texi/tar.texi(,7305) @cindex Avoiding recursion in directories
+../tar_texi/tar.texi(,7306) @cindex Descending directories, avoiding
+../tar_texi/tar.texi(,7307) @cindex Directories, avoiding recursion
+../tar_texi/tar.texi(,7308) @cindex Recursion in directories, avoiding
+../tar_texi/tar.texi(,7309)
+../tar_texi/tar.texi(FIXME,7310) @allow-recursion
+../tar_texi/tar.texi(FIXME,7310) @quote-arg
+../tar_texi/tar.texi(FIXME,7310)
+../tar_texi/tar.texi(,7311)
+../tar_texi/tar.texi(,7312) Usually, @command{tar} will recursively explore
all directories (either
+../tar_texi/tar.texi(,7313) those given on the command line or through the
@option{--files-from}
+../tar_texi/tar.texi(,7314) option) for the various files they contain.
However, you may not always
+../tar_texi/tar.texi(,7315) want @command{tar} to act this way.
+../tar_texi/tar.texi(,7316)
+../tar_texi/tar.texi(,7317) @opindex no-recursion
+../tar_texi/tar.texi(,7318) The @option{--no-recursion} option inhibits
@command{tar}'s recursive descent
+../tar_texi/tar.texi(,7319) into specified directories. If you specify
@option{--no-recursion}, you can
+../tar_texi/tar.texi(,7320) use the @command{find} utility for hunting through
levels of directories to
+../tar_texi/tar.texi(,7321) construct a list of file names which you could
then pass to @command{tar}.
+../tar_texi/tar.texi(,7322) @command{find} allows you to be more selective
when choosing which files to
+../tar_texi/tar.texi(,7323) archive; see @ref{files}, for more information on
using @command{find} with
+../tar_texi/tar.texi(,7324) @command{tar}, or look.
+../tar_texi/tar.texi(,7325)
+../tar_texi/tar.texi(,7326) @table @option
+../tar_texi/tar.texi(,7327) @item --no-recursion
+../tar_texi/tar.texi(,7328) Prevents @command{tar} from recursively descending
directories.
+../tar_texi/tar.texi(,7329)
+../tar_texi/tar.texi(,7330) @opindex recursion
+../tar_texi/tar.texi(,7331) @item --recursion
+../tar_texi/tar.texi(,7332) Requires @command{tar} to recursively descend
directories.
+../tar_texi/tar.texi(,7333) This is the default.
+../tar_texi/tar.texi(,7334) @end table
+../tar_texi/tar.texi(,7335)
+../tar_texi/tar.texi(GNUTAR,7336) When you use @option{--no-recursion},
../tar_texi/tar.texi(GNUTAR,7336) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7336) grabs
+../tar_texi/tar.texi(,7337) directory entries themselves, but does not descend
on them
+../tar_texi/tar.texi(,7338) recursively. Many people use @command{find} for
locating files they
+../tar_texi/tar.texi(,7339) want to back up, and since @command{tar}
@emph{usually} recursively
+../tar_texi/tar.texi(,7340) descends on directories, they have to use the
@address@hidden -type d}}
+../tar_texi/tar.texi(,7341) test in their @command{find} invocation
(@pxref{Type, Type, Type test,
+../tar_texi/tar.texi(,7342) find, Finding Files}), as they usually do not want
all the files in a
+../tar_texi/tar.texi(,7343) directory. They then use the @option{--files-from}
option to archive
+../tar_texi/tar.texi(,7344) the files located via @command{find}.
+../tar_texi/tar.texi(,7345)
+../tar_texi/tar.texi(,7346) The problem when restoring files archived in this
manner is that the
+../tar_texi/tar.texi(,7347) directories themselves are not in the archive; so
the
+../tar_texi/tar.texi(,7348) @option{--same-permissions}
(@option{--preserve-permissions},
+../tar_texi/tar.texi(,7349) @option{-p}) option does not affect them---while
users might really
+../tar_texi/tar.texi(,7350) like it to. Specifying @option{--no-recursion} is
a way to tell
+../tar_texi/tar.texi(,7351) @command{tar} to grab only the directory entries
given to it, adding
+../tar_texi/tar.texi(,7352) no new files on its own. To summarize, if you use
@command{find} to
+../tar_texi/tar.texi(,7353) create a list of files to be stored in an archive,
use it as follows:
+../tar_texi/tar.texi(,7354)
+../tar_texi/tar.texi(,7355) @smallexample
+../tar_texi/tar.texi(,7356) @group
+../tar_texi/tar.texi(,7357) $ @kbd{find @var{dir} @var{tests} | \
+../tar_texi/tar.texi(,7358) tar -cf @var{archive} -T - --no-recursion}
+../tar_texi/tar.texi(,7359) @end group
+../tar_texi/tar.texi(,7360) @end smallexample
+../tar_texi/tar.texi(,7361)
+../tar_texi/tar.texi(,7362) The @option{--no-recursion} option also applies
when extracting: it
+../tar_texi/tar.texi(,7363) causes @command{tar} to extract only the matched
directory entries, not
+../tar_texi/tar.texi(,7364) the files under those directories.
+../tar_texi/tar.texi(,7365)
+../tar_texi/tar.texi(,7366) The @option{--no-recursion} option also affects
how globbing patterns
+../tar_texi/tar.texi(,7367) are interpreted (@pxref{controlling
pattern-matching}).
+../tar_texi/tar.texi(,7368)
+../tar_texi/tar.texi(,7369) The @option{--no-recursion} and
@option{--recursion} options apply to
+../tar_texi/tar.texi(,7370) later options and operands, and can be overridden
by later occurrences
+../tar_texi/tar.texi(,7371) of @option{--no-recursion} and
@option{--recursion}. For example:
+../tar_texi/tar.texi(,7372)
+../tar_texi/tar.texi(,7373) @smallexample
+../tar_texi/tar.texi(,7374) $ @kbd{tar -cf jams.tar --no-recursion grape
--recursion grape/concord}
+../tar_texi/tar.texi(,7375) @end smallexample
+../tar_texi/tar.texi(,7376)
+../tar_texi/tar.texi(,7377) @noindent
+../tar_texi/tar.texi(,7378) creates an archive with one entry for
@file{grape}, and the recursive
+../tar_texi/tar.texi(,7379) contents of @file{grape/concord}, but no entries
under @file{grape}
+../tar_texi/tar.texi(,7380) other than @file{grape/concord}.
+../tar_texi/tar.texi(,7381)
+../tar_texi/tar.texi(,7382) @node one
+../tar_texi/tar.texi(,7383) @section Crossing File System Boundaries
+../tar_texi/tar.texi(,7384) @cindex File system boundaries, not crossing
+../tar_texi/tar.texi(UNREVISED,7385) @quotation
+../tar_texi/tar.texi(UNREVISED,7385) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7385) @end quotation
+../tar_texi/tar.texi(UNREVISED,7385)
+../tar_texi/tar.texi(,7386)
+../tar_texi/tar.texi(,7387) @command{tar} will normally automatically cross
file system boundaries in
+../tar_texi/tar.texi(,7388) order to archive files which are part of a
directory tree. You can
+../tar_texi/tar.texi(,7389) change this behavior by running @command{tar} and
specifying
+../tar_texi/tar.texi(,7390) @option{--one-file-system}. This option only
affects files that are
+../tar_texi/tar.texi(,7391) archived because they are in a directory that is
being archived;
+../tar_texi/tar.texi(,7392) @command{tar} will still archive files explicitly
named on the command line
+../tar_texi/tar.texi(,7393) or through @option{--files-from}, regardless of
where they reside.
+../tar_texi/tar.texi(,7394)
+../tar_texi/tar.texi(,7395) @table @option
+../tar_texi/tar.texi(,7396) @opindex one-file-system
+../tar_texi/tar.texi(,7397) @item --one-file-system
+../tar_texi/tar.texi(,7398) Prevents @command{tar} from crossing file system
boundaries when
+../tar_texi/tar.texi(,7399) archiving. Use in conjunction with any write
operation.
+../tar_texi/tar.texi(,7400) @end table
+../tar_texi/tar.texi(,7401)
+../tar_texi/tar.texi(,7402) The @option{--one-file-system} option causes
@command{tar} to modify its
+../tar_texi/tar.texi(,7403) normal behavior in archiving the contents of
directories. If a file in
+../tar_texi/tar.texi(,7404) a directory is not on the same file system as the
directory itself, then
+../tar_texi/tar.texi(,7405) @command{tar} will not archive that file. If the
file is a directory
+../tar_texi/tar.texi(,7406) itself, @command{tar} will not archive anything
beneath it; in other words,
+../tar_texi/tar.texi(,7407) @command{tar} will not cross mount points.
+../tar_texi/tar.texi(,7408)
+../tar_texi/tar.texi(,7409) This option is useful for making full or
incremental archival backups of
+../tar_texi/tar.texi(,7410) a file system. If this option is used in
conjunction with
+../tar_texi/tar.texi(,7411) @option{--verbose} (@option{-v}), files that are
excluded are
+../tar_texi/tar.texi(,7412) mentioned by name on the standard error.
+../tar_texi/tar.texi(,7413)
+../tar_texi/tar.texi(,7414) @menu
+../tar_texi/tar.texi(,7415) * directory:: Changing Directory
+../tar_texi/tar.texi(,7416) * absolute:: Absolute File Names
+../tar_texi/tar.texi(,7417) @end menu
+../tar_texi/tar.texi(,7418)
+../tar_texi/tar.texi(,7419) @node directory
+../tar_texi/tar.texi(,7420) @subsection Changing the Working Directory
+../tar_texi/tar.texi(UNREVISED,7421) @quotation
+../tar_texi/tar.texi(UNREVISED,7421) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7421) @end quotation
+../tar_texi/tar.texi(UNREVISED,7421)
+../tar_texi/tar.texi(,7422)
+../tar_texi/tar.texi(FIXME,7424) @allow-recursion
+../tar_texi/tar.texi(FIXME,7424) @quote-arg
+../tar_texi/tar.texi(FIXME,7424)
+../tar_texi/tar.texi(,7425)
+../tar_texi/tar.texi(,7426) @cindex Changing directory mid-stream
+../tar_texi/tar.texi(,7427) @cindex Directory, changing mid-stream
+../tar_texi/tar.texi(,7428) @cindex Working directory, specifying
+../tar_texi/tar.texi(,7429) To change the working directory in the middle of a
list of file names,
+../tar_texi/tar.texi(,7430) either on the command line or in a file specified
using
+../tar_texi/tar.texi(,7431) @option{--files-from} (@option{-T}), use
@option{--directory} (@option{-C}).
+../tar_texi/tar.texi(,7432) This will change the working directory to the
specified directory
+../tar_texi/tar.texi(,7433) after that point in the list.
+../tar_texi/tar.texi(,7434)
+../tar_texi/tar.texi(,7435) @table @option
+../tar_texi/tar.texi(,7436) @opindex directory
+../tar_texi/tar.texi(,7437) @item address@hidden
+../tar_texi/tar.texi(,7438) @itemx -C @var{directory}
+../tar_texi/tar.texi(,7439) Changes the working directory in the middle of a
command line.
+../tar_texi/tar.texi(,7440) @end table
+../tar_texi/tar.texi(,7441)
+../tar_texi/tar.texi(,7442) For example,
+../tar_texi/tar.texi(,7443)
+../tar_texi/tar.texi(,7444) @smallexample
+../tar_texi/tar.texi(,7445) $ @kbd{tar -c -f jams.tar grape prune -C food
cherry}
+../tar_texi/tar.texi(,7446) @end smallexample
+../tar_texi/tar.texi(,7447)
+../tar_texi/tar.texi(,7448) @noindent
+../tar_texi/tar.texi(,7449) will place the files @file{grape} and @file{prune}
from the current
+../tar_texi/tar.texi(,7450) directory into the archive @file{jams.tar},
followed by the file
+../tar_texi/tar.texi(,7451) @file{cherry} from the directory @file{food}.
This option is especially
+../tar_texi/tar.texi(,7452) useful when you have several widely separated
files that you want to
+../tar_texi/tar.texi(,7453) store in the same archive.
+../tar_texi/tar.texi(,7454)
+../tar_texi/tar.texi(,7455) Note that the file @file{cherry} is recorded in
the archive under the
+../tar_texi/tar.texi(,7456) precise name @file{cherry}, @emph{not}
@file{food/cherry}. Thus, the
+../tar_texi/tar.texi(,7457) archive will contain three files that all appear
to have come from the
+../tar_texi/tar.texi(,7458) same directory; if the archive is extracted with
plain @samp{tar
+../tar_texi/tar.texi(,7459) --extract}, all three files will be written in the
current directory.
+../tar_texi/tar.texi(,7460)
+../tar_texi/tar.texi(,7461) Contrast this with the command,
+../tar_texi/tar.texi(,7462)
+../tar_texi/tar.texi(,7463) @smallexample
+../tar_texi/tar.texi(,7464) $ @kbd{tar -c -f jams.tar grape prune -C food
red/cherry}
+../tar_texi/tar.texi(,7465) @end smallexample
+../tar_texi/tar.texi(,7466)
+../tar_texi/tar.texi(,7467) @noindent
+../tar_texi/tar.texi(,7468) which records the third file in the archive under
the name
+../tar_texi/tar.texi(,7469) @file{red/cherry} so that, if the archive is
extracted using
+../tar_texi/tar.texi(,7470) @samp{tar --extract}, the third file will be
written in a subdirectory
+../tar_texi/tar.texi(,7471) named @file{orange-colored}.
+../tar_texi/tar.texi(,7472)
+../tar_texi/tar.texi(,7473) You can use the @option{--directory} option to
make the archive
+../tar_texi/tar.texi(,7474) independent of the original name of the directory
holding the files.
+../tar_texi/tar.texi(,7475) The following command places the files
@file{/etc/passwd},
+../tar_texi/tar.texi(,7476) @file{/etc/hosts}, and @file{/lib/libc.a} into the
archive
+../tar_texi/tar.texi(,7477) @file{foo.tar}:
+../tar_texi/tar.texi(,7478)
+../tar_texi/tar.texi(,7479) @smallexample
+../tar_texi/tar.texi(,7480) $ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C
/lib libc.a}
+../tar_texi/tar.texi(,7481) @end smallexample
+../tar_texi/tar.texi(,7482)
+../tar_texi/tar.texi(,7483) @noindent
+../tar_texi/tar.texi(,7484) However, the names of the archive members will be
exactly what they were
+../tar_texi/tar.texi(,7485) on the command line: @file{passwd}, @file{hosts},
and @file{libc.a}.
+../tar_texi/tar.texi(,7486) They will not appear to be related by file name to
the original
+../tar_texi/tar.texi(,7487) directories where those files were located.
+../tar_texi/tar.texi(,7488)
+../tar_texi/tar.texi(,7489) Note that @option{--directory} options are
interpreted consecutively. If
+../tar_texi/tar.texi(,7490) @option{--directory} specifies a relative file
name, it is interpreted
+../tar_texi/tar.texi(,7491) relative to the then current directory, which
might not be the same as
+../tar_texi/tar.texi(,7492) the original current working directory of
@command{tar}, due to a previous
+../tar_texi/tar.texi(,7493) @option{--directory} option.
+../tar_texi/tar.texi(,7494)
+../tar_texi/tar.texi(,7495) When using @option{--files-from} (@pxref{files}),
you can put various
+../tar_texi/tar.texi(,7496) @command{tar} options (including @option{-C}) in
the file list. Notice,
+../tar_texi/tar.texi(,7497) however, that in this case the option and its
argument may not be
+../tar_texi/tar.texi(,7498) separated by whitespace. If you use short option,
its argument must
+../tar_texi/tar.texi(,7499) either follow the option letter immediately,
without any intervening
+../tar_texi/tar.texi(,7500) whitespace, or occupy the next line. Otherwise,
if you use long
+../tar_texi/tar.texi(,7501) option, separate its argument by an equal sign.
+../tar_texi/tar.texi(,7502)
+../tar_texi/tar.texi(,7503) For instance, the file list for the above example
will be:
+../tar_texi/tar.texi(,7504)
+../tar_texi/tar.texi(,7505) @smallexample
+../tar_texi/tar.texi(,7506) @group
+../tar_texi/tar.texi(,7507) -C
+../tar_texi/tar.texi(,7508) /etc
+../tar_texi/tar.texi(,7509) passwd
+../tar_texi/tar.texi(,7510) hosts
+../tar_texi/tar.texi(,7511) -C
+../tar_texi/tar.texi(,7512) /lib
+../tar_texi/tar.texi(,7513) libc.a
+../tar_texi/tar.texi(,7514) @end group
+../tar_texi/tar.texi(,7515) @end smallexample
+../tar_texi/tar.texi(,7516)
+../tar_texi/tar.texi(,7517) @noindent
+../tar_texi/tar.texi(,7518) To use it, you would invoke @command{tar} as
follows:
+../tar_texi/tar.texi(,7519)
+../tar_texi/tar.texi(,7520) @smallexample
+../tar_texi/tar.texi(,7521) $ @kbd{tar -c -f foo.tar --files-from list}
+../tar_texi/tar.texi(,7522) @end smallexample
+../tar_texi/tar.texi(,7523)
+../tar_texi/tar.texi(,7524) Notice also that you can only use the short option
variant in the file
+../tar_texi/tar.texi(,7525) list, i.e., always use @option{-C}, not
@option{--directory}.
+../tar_texi/tar.texi(,7526)
+../tar_texi/tar.texi(,7527) The interpretation of @option{--directory} is
disabled by
+../tar_texi/tar.texi(,7528) @option{--null} option.
+../tar_texi/tar.texi(,7529)
+../tar_texi/tar.texi(,7530) @node absolute
+../tar_texi/tar.texi(,7531) @subsection Absolute File Names
+../tar_texi/tar.texi(UNREVISED,7532) @quotation
+../tar_texi/tar.texi(UNREVISED,7532) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,7532) @end quotation
+../tar_texi/tar.texi(UNREVISED,7532)
+../tar_texi/tar.texi(,7533)
+../tar_texi/tar.texi(,7534) @table @option
+../tar_texi/tar.texi(,7535) @opindex absolute-names
+../tar_texi/tar.texi(,7536) @item --absolute-names
+../tar_texi/tar.texi(,7537) @itemx -P
+../tar_texi/tar.texi(,7538) Do not strip leading slashes from file names, and
permit file names
+../tar_texi/tar.texi(,7539) containing a @file{..} file name component.
+../tar_texi/tar.texi(,7540) @end table
+../tar_texi/tar.texi(,7541)
+../tar_texi/tar.texi(GNUTAR,7542) By default,
../tar_texi/tar.texi(GNUTAR,7542) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7542) drops a leading @samp{/} on
+../tar_texi/tar.texi(,7543) input or output, and complains about file names
containing a @file{..}
+../tar_texi/tar.texi(,7544) component. This option turns off this behavior.
+../tar_texi/tar.texi(,7545)
+../tar_texi/tar.texi(,7546) When @command{tar} extracts archive members from
an archive, it strips any
+../tar_texi/tar.texi(,7547) leading slashes (@samp{/}) from the member name.
This causes absolute
+../tar_texi/tar.texi(,7548) member names in the archive to be treated as
relative file names. This
+../tar_texi/tar.texi(,7549) allows you to have such members extracted wherever
you want, instead of
+../tar_texi/tar.texi(,7550) being restricted to extracting the member in the
exact directory named
+../tar_texi/tar.texi(,7551) in the archive. For example, if the archive
member has the name
+../tar_texi/tar.texi(,7552) @file{/etc/passwd}, @command{tar} will extract it
as if the name were
+../tar_texi/tar.texi(,7553) really @file{etc/passwd}.
+../tar_texi/tar.texi(,7554)
+../tar_texi/tar.texi(,7555) File names containing @file{..} can cause problems
when extracting, so
+../tar_texi/tar.texi(,7556) @command{tar} normally warns you about such files
when creating an
+../tar_texi/tar.texi(,7557) archive, and rejects attempts to extracts such
files.
+../tar_texi/tar.texi(,7558)
+../tar_texi/tar.texi(,7559) Other @command{tar} programs do not do this. As a
result, if you
+../tar_texi/tar.texi(,7560) create an archive whose member names start with a
slash, they will be
+../tar_texi/tar.texi(GNUTAR,7561) difficult for other people with a
non-../tar_texi/tar.texi(GNUTAR,7561) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7561)
+../tar_texi/tar.texi(GNUTAR,7562) program to use. Therefore,
../tar_texi/tar.texi(GNUTAR,7562) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7562) also strips
+../tar_texi/tar.texi(,7563) leading slashes from member names when putting
members into the
+../tar_texi/tar.texi(,7564) archive. For example, if you ask @command{tar} to
add the file
+../tar_texi/tar.texi(,7565) @file{/bin/ls} to an archive, it will do so, but
the member name will
+../tar_texi/tar.texi(,7566) be @file{bin/address@hidden side effect of this is
that when
+../tar_texi/tar.texi(,7567) @option{--create} is used with @option{--verbose}
the resulting output
+../tar_texi/tar.texi(,7568) is not, generally speaking, the same as the one
you'd get running
+../tar_texi/tar.texi(,7569) @kbd{tar --list} command. This may be important
if you use some
+../tar_texi/tar.texi(,7570) scripts for comparing both outputs. @xref{listing
member and file names},
+../tar_texi/tar.texi(,7571) for the information on how to handle this case.}
+../tar_texi/tar.texi(,7572)
+../tar_texi/tar.texi(,7573) If you use the @option{--absolute-names}
(@option{-P}) option,
+../tar_texi/tar.texi(,7574) @command{tar} will do none of these
transformations.
+../tar_texi/tar.texi(,7575)
+../tar_texi/tar.texi(,7576) To archive or extract files relative to the root
directory, specify
+../tar_texi/tar.texi(,7577) the @option{--absolute-names} (@option{-P}) option.
+../tar_texi/tar.texi(,7578)
+../tar_texi/tar.texi(,7579) Normally, @command{tar} acts on files relative to
the working
+../tar_texi/tar.texi(,7580) directory---ignoring superior directory names when
archiving, and
+../tar_texi/tar.texi(,7581) ignoring leading slashes when extracting.
+../tar_texi/tar.texi(,7582)
+../tar_texi/tar.texi(,7583) When you specify @option{--absolute-names}
(@option{-P}),
+../tar_texi/tar.texi(,7584) @command{tar} stores file names including all
superior directory
+../tar_texi/tar.texi(,7585) names, and preserves leading slashes. If you only
invoked
+../tar_texi/tar.texi(,7586) @command{tar} from the root directory you would
never need the
+../tar_texi/tar.texi(,7587) @option{--absolute-names} option, but using this
option
+../tar_texi/tar.texi(,7588) may be more convenient than switching to root.
+../tar_texi/tar.texi(,7589)
+../tar_texi/tar.texi(FIXME,7591) @allow-recursion
+../tar_texi/tar.texi(FIXME,7591) @quote-arg
+../tar_texi/tar.texi(FIXME,7591)
+../tar_texi/tar.texi(,7592)
+../tar_texi/tar.texi(FIXME,7593) @allow-recursion
+../tar_texi/tar.texi(FIXME,7593) @quote-arg
+../tar_texi/tar.texi(FIXME,7593)
+../tar_texi/tar.texi(,7594)
+../tar_texi/tar.texi(,7595) @table @option
+../tar_texi/tar.texi(,7596) @item --absolute-names
+../tar_texi/tar.texi(,7597) Preserves full file names (including superior
directory names) when
+../tar_texi/tar.texi(,7598) archiving files. Preserves leading slash when
extracting files.
+../tar_texi/tar.texi(,7599)
+../tar_texi/tar.texi(,7600) @end table
+../tar_texi/tar.texi(,7601)
+../tar_texi/tar.texi(FIXME,7602) @allow-recursion
+../tar_texi/tar.texi(FIXME,7602) @quote-arg
+../tar_texi/tar.texi(FIXME,7602)
+../tar_texi/tar.texi(,7603)
+../tar_texi/tar.texi(,7604) @command{tar} prints out a message about removing
the @samp{/} from
+../tar_texi/tar.texi(GNUTAR,7605) file names. This message appears once per
../tar_texi/tar.texi(GNUTAR,7605) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7605)
+../tar_texi/tar.texi(,7606) invocation. It represents something which ought
to be told; ignoring
+../tar_texi/tar.texi(,7607) what it means can cause very serious surprises,
later.
+../tar_texi/tar.texi(,7608)
+../tar_texi/tar.texi(,7609) Some people, nevertheless, do not want to see this
message. Wanting to
+../tar_texi/tar.texi(,7610) play really dangerously, one may of course
redirect @command{tar} standard
+../tar_texi/tar.texi(,7611) error to the sink. For example, under
@command{sh}:
+../tar_texi/tar.texi(,7612)
+../tar_texi/tar.texi(,7613) @smallexample
+../tar_texi/tar.texi(,7614) $ @kbd{tar -c -f archive.tar /home 2> /dev/null}
+../tar_texi/tar.texi(,7615) @end smallexample
+../tar_texi/tar.texi(,7616)
+../tar_texi/tar.texi(,7617) @noindent
+../tar_texi/tar.texi(,7618) Another solution, both nicer and simpler, would be
to change to
+../tar_texi/tar.texi(,7619) the @file{/} directory first, and then avoid
absolute notation.
+../tar_texi/tar.texi(,7620) For example:
+../tar_texi/tar.texi(,7621)
+../tar_texi/tar.texi(,7622) @smallexample
+../tar_texi/tar.texi(,7623) $ @kbd{(cd / && tar -c -f archive.tar home)}
+../tar_texi/tar.texi(,7624) # @i{or}:
+../tar_texi/tar.texi(,7625) $ @kbd{tar -c -f archive.tar -C / home}
+../tar_texi/tar.texi(,7626) @end smallexample
+../tar_texi/tar.texi(,7627)
+../tar_texi/getdate.texi(,1) @c GNU date syntax documentation
+../tar_texi/getdate.texi(,2)
+../tar_texi/getdate.texi(,3) @c Copyright (C) 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002,
+../tar_texi/getdate.texi(,4) @c 2003, 2004, 2005, 2006 Free Software
Foundation, Inc.
+../tar_texi/getdate.texi(,5)
+../tar_texi/getdate.texi(,6) @c Permission is granted to copy, distribute
and/or modify this document
+../tar_texi/getdate.texi(,7) @c under the terms of the GNU Free Documentation
License, Version 1.1 or
+../tar_texi/getdate.texi(,8) @c any later version published by the Free
Software Foundation; with no
+../tar_texi/getdate.texi(,9) @c Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover
+../tar_texi/getdate.texi(,10) @c Texts. A copy of the license is included in
the ``GNU Free
+../tar_texi/getdate.texi(,11) @c Documentation License'' file as part of this
distribution.
+../tar_texi/getdate.texi(,12)
+../tar_texi/getdate.texi(,13) @node Date input formats
+../tar_texi/getdate.texi(,14) @chapter Date input formats
+../tar_texi/getdate.texi(,15)
+../tar_texi/getdate.texi(,16) @cindex date input formats
+../tar_texi/getdate.texi(,17) @findex get_date
+../tar_texi/getdate.texi(,18)
+../tar_texi/getdate.texi(,19) First, a quote:
+../tar_texi/getdate.texi(,20)
+../tar_texi/getdate.texi(,21) @quotation
+../tar_texi/getdate.texi(,22) Our units of temporal measurement, from seconds
on up to months, are so
+../tar_texi/getdate.texi(,23) complicated, asymmetrical and disjunctive so as
to make coherent mental
+../tar_texi/getdate.texi(,24) reckoning in time all but impossible. Indeed,
had some tyrannical god
+../tar_texi/getdate.texi(,25) contrived to enslave our minds to time, to make
it all but impossible
+../tar_texi/getdate.texi(,26) for us to escape subjection to sodden routines
and unpleasant surprises,
+../tar_texi/getdate.texi(,27) he could hardly have done better than handing
down our present system.
+../tar_texi/getdate.texi(,28) It is like a set of trapezoidal building blocks,
with no vertical or
+../tar_texi/getdate.texi(,29) horizontal surfaces, like a language in which
the simplest thought
+../tar_texi/getdate.texi(,30) demands ornate constructions, useless particles
and lengthy
+../tar_texi/getdate.texi(,31) circumlocutions. Unlike the more successful
patterns of language and
+../tar_texi/getdate.texi(,32) science, which enable us to face experience
boldly or at least
+../tar_texi/getdate.texi(,33) level-headedly, our system of temporal
calculation silently and
+../tar_texi/getdate.texi(,34) persistently encourages our terror of time.
+../tar_texi/getdate.texi(,35)
+../tar_texi/getdate.texi(,36) @dots{} It is as though architects had to
measure length in feet, width
+../tar_texi/getdate.texi(,37) in meters and height in ells; as though basic
instruction manuals
+../tar_texi/getdate.texi(,38) demanded a knowledge of five different
languages. It is no wonder then
+../tar_texi/getdate.texi(,39) that we often look into our own immediate past
or future, last Tuesday
+../tar_texi/getdate.texi(,40) or a week from Sunday, with feelings of helpless
confusion. @dots{}
+../tar_texi/getdate.texi(,41)
+../tar_texi/getdate.texi(,42) --- Robert Grudin, @cite{Time and the Art of
Living}.
+../tar_texi/getdate.texi(,43) @end quotation
+../tar_texi/getdate.texi(,44)
+../tar_texi/getdate.texi(,45) This section describes the textual date
representations that @sc{gnu}
+../tar_texi/getdate.texi(,46) programs accept. These are the strings you, as
a user, can supply as
+../tar_texi/getdate.texi(,47) arguments to the various programs. The C
interface (via the
+../tar_texi/getdate.texi(,48) @code{get_date} function) is not described here.
+../tar_texi/getdate.texi(,49)
+../tar_texi/getdate.texi(,50) @menu
+../tar_texi/getdate.texi(,51) * General date syntax:: Common rules.
+../tar_texi/getdate.texi(,52) * Calendar date items:: 19 Dec 1994.
+../tar_texi/getdate.texi(,53) * Time of day items:: 9:20pm.
+../tar_texi/getdate.texi(,54) * Time zone items:: @sc{est},
@sc{pdt}, @sc{gmt}.
+../tar_texi/getdate.texi(,55) * Day of week items:: Monday and
others.
+../tar_texi/getdate.texi(,56) * Relative items in date strings:: next tuesday,
2 years ago.
+../tar_texi/getdate.texi(,57) * Pure numbers in date strings:: 19931219,
1440.
+../tar_texi/getdate.texi(,58) * Seconds since the Epoch:: @@1078100502.
+../tar_texi/getdate.texi(,59) * Specifying time zone rules::
TZ="America/New_York", TZ="UTC0".
+../tar_texi/getdate.texi(,60) * Authors of get_date:: Bellovin,
Eggert, Salz, Berets, et al.
+../tar_texi/getdate.texi(,61) @end menu
+../tar_texi/getdate.texi(,62)
+../tar_texi/getdate.texi(,63)
+../tar_texi/getdate.texi(,64) @node General date syntax
+../tar_texi/getdate.texi(,65) @section General date syntax
+../tar_texi/getdate.texi(,66)
+../tar_texi/getdate.texi(,67) @cindex general date syntax
+../tar_texi/getdate.texi(,68)
+../tar_texi/getdate.texi(,69) @cindex items in date strings
+../tar_texi/getdate.texi(,70) A @dfn{date} is a string, possibly empty,
containing many items
+../tar_texi/getdate.texi(,71) separated by whitespace. The whitespace may be
omitted when no
+../tar_texi/getdate.texi(,72) ambiguity arises. The empty string means the
beginning of today (i.e.,
+../tar_texi/getdate.texi(,73) midnight). Order of the items is immaterial. A
date string may contain
+../tar_texi/getdate.texi(,74) many flavors of items:
+../tar_texi/getdate.texi(,75)
+../tar_texi/getdate.texi(,76) @itemize @bullet
+../tar_texi/getdate.texi(,77) @item calendar date items
+../tar_texi/getdate.texi(,78) @item time of day items
+../tar_texi/getdate.texi(,79) @item time zone items
+../tar_texi/getdate.texi(,80) @item day of the week items
+../tar_texi/getdate.texi(,81) @item relative items
+../tar_texi/getdate.texi(,82) @item pure numbers.
+../tar_texi/getdate.texi(,83) @end itemize
+../tar_texi/getdate.texi(,84)
+../tar_texi/getdate.texi(,85) @noindent We describe each of these item types
in turn, below.
+../tar_texi/getdate.texi(,86)
+../tar_texi/getdate.texi(,87) @cindex numbers, written-out
+../tar_texi/getdate.texi(,88) @cindex ordinal numbers
+../tar_texi/getdate.texi(,89) @findex first @r{in date strings}
+../tar_texi/getdate.texi(,90) @findex next @r{in date strings}
+../tar_texi/getdate.texi(,91) @findex last @r{in date strings}
+../tar_texi/getdate.texi(,92) A few ordinal numbers may be written out in
words in some contexts. This is
+../tar_texi/getdate.texi(,93) most useful for specifying day of the week items
or relative items (see
+../tar_texi/getdate.texi(,94) below). Among the most commonly used ordinal
numbers, the word
+../tar_texi/getdate.texi(,95) @samp{last} stands for @math{-1}, @samp{this}
stands for 0, and
+../tar_texi/getdate.texi(,96) @samp{first} and @samp{next} both stand for 1.
Because the word
+../tar_texi/getdate.texi(,97) @samp{second} stands for the unit of time there
is no way to write the
+../tar_texi/getdate.texi(,98) ordinal number 2, but for convenience
@samp{third} stands for 3,
+../tar_texi/getdate.texi(,99) @samp{fourth} for 4, @samp{fifth} for 5,
+../tar_texi/getdate.texi(,100) @samp{sixth} for 6, @samp{seventh} for 7,
@samp{eighth} for 8,
+../tar_texi/getdate.texi(,101) @samp{ninth} for 9, @samp{tenth} for 10,
@samp{eleventh} for 11 and
+../tar_texi/getdate.texi(,102) @samp{twelfth} for 12.
+../tar_texi/getdate.texi(,103)
+../tar_texi/getdate.texi(,104) @cindex months, written-out
+../tar_texi/getdate.texi(,105) When a month is written this way, it is still
considered to be written
+../tar_texi/getdate.texi(,106) numerically, instead of being ``spelled in
full''; this changes the
+../tar_texi/getdate.texi(,107) allowed strings.
+../tar_texi/getdate.texi(,108)
+../tar_texi/getdate.texi(,109) @cindex language, in dates
+../tar_texi/getdate.texi(,110) In the current implementation, only English is
supported for words and
+../tar_texi/getdate.texi(,111) abbreviations like @samp{AM}, @samp{DST},
@samp{EST}, @samp{first},
+../tar_texi/getdate.texi(,112) @samp{January}, @samp{Sunday}, @samp{tomorrow},
and @samp{year}.
+../tar_texi/getdate.texi(,113)
+../tar_texi/getdate.texi(,114) @cindex language, in dates
+../tar_texi/getdate.texi(,115) @cindex time zone item
+../tar_texi/getdate.texi(,116) The output of the @command{date} command
+../tar_texi/getdate.texi(,117) is not always acceptable as a date string,
+../tar_texi/getdate.texi(,118) not only because of the language problem, but
also because there is no
+../tar_texi/getdate.texi(,119) standard meaning for time zone items like
@samp{IST}. When using
+../tar_texi/getdate.texi(,120) @command{date} to generate a date string
intended to be parsed later,
+../tar_texi/getdate.texi(,121) specify a date format that is independent of
language and that does not
+../tar_texi/getdate.texi(,122) use time zone items other than @samp{UTC} and
@samp{Z}. Here are some
+../tar_texi/getdate.texi(,123) ways to do this:
+../tar_texi/getdate.texi(,124)
+../tar_texi/getdate.texi(,125) @example
+../tar_texi/getdate.texi(,126) $ LC_ALL=C TZ=UTC0 date
+../tar_texi/getdate.texi(,127) Mon Mar 1 00:21:42 UTC 2004
+../tar_texi/getdate.texi(,128) $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+../tar_texi/getdate.texi(,129) 2004-03-01 00:21:42Z
+../tar_texi/getdate.texi(,130) $ date --iso-8601=ns | tr T ' ' # --iso-8601
is a GNU extension.
+../tar_texi/getdate.texi(,131) 2004-02-29 16:21:42,692722128-0800
+../tar_texi/getdate.texi(,132) $ date --rfc-2822 # a GNU extension
+../tar_texi/getdate.texi(,133) Sun, 29 Feb 2004 16:21:42 -0800
+../tar_texi/getdate.texi(,134) $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU
extension.
+../tar_texi/getdate.texi(,135) 2004-02-29 16:21:42 -0800
+../tar_texi/getdate.texi(,136) $ date +'@@%s.%N' # %s and %N are GNU
extensions.
+../tar_texi/getdate.texi(,137) @@1078100502.692722128
+../tar_texi/getdate.texi(,138) @end example
+../tar_texi/getdate.texi(,139)
+../tar_texi/getdate.texi(,140) @cindex case, ignored in dates
+../tar_texi/getdate.texi(,141) @cindex comments, in dates
+../tar_texi/getdate.texi(,142) Alphabetic case is completely ignored in dates.
Comments may be introduced
+../tar_texi/getdate.texi(,143) between round parentheses, as long as included
parentheses are properly
+../tar_texi/getdate.texi(,144) nested. Hyphens not followed by a digit are
currently ignored. Leading
+../tar_texi/getdate.texi(,145) zeros on numbers are ignored.
+../tar_texi/getdate.texi(,146)
+../tar_texi/getdate.texi(,147) Invalid dates like @samp{2005-02-29} or times
like @samp{24:00} are
+../tar_texi/getdate.texi(,148) rejected. In the typical case of a host that
does not support leap
+../tar_texi/getdate.texi(,149) seconds, a time like @samp{23:59:60} is
rejected even if it
+../tar_texi/getdate.texi(,150) corresponds to a valid leap second.
+../tar_texi/getdate.texi(,151)
+../tar_texi/getdate.texi(,152)
+../tar_texi/getdate.texi(,153) @node Calendar date items
+../tar_texi/getdate.texi(,154) @section Calendar date items
+../tar_texi/getdate.texi(,155)
+../tar_texi/getdate.texi(,156) @cindex calendar date item
+../tar_texi/getdate.texi(,157)
+../tar_texi/getdate.texi(,158) A @dfn{calendar date item} specifies a day of
the year. It is
+../tar_texi/getdate.texi(,159) specified differently, depending on whether the
month is specified
+../tar_texi/getdate.texi(,160) numerically or literally. All these strings
specify the same calendar date:
+../tar_texi/getdate.texi(,161)
+../tar_texi/getdate.texi(,162) @example
+../tar_texi/getdate.texi(,163) 1972-09-24 # @sc{iso} 8601.
+../tar_texi/getdate.texi(,164) 72-9-24 # Assume 19xx for 69 through 99,
+../tar_texi/getdate.texi(,165) # 20xx for 00 through 68.
+../tar_texi/getdate.texi(,166) 72-09-24 # Leading zeros are ignored.
+../tar_texi/getdate.texi(,167) 9/24/72 # Common U.S. writing.
+../tar_texi/getdate.texi(,168) 24 September 1972
+../tar_texi/getdate.texi(,169) 24 Sept 72 # September has a special
abbreviation.
+../tar_texi/getdate.texi(,170) 24 Sep 72 # Three-letter abbreviations
always allowed.
+../tar_texi/getdate.texi(,171) Sep 24, 1972
+../tar_texi/getdate.texi(,172) 24-sep-72
+../tar_texi/getdate.texi(,173) 24sep72
+../tar_texi/getdate.texi(,174) @end example
+../tar_texi/getdate.texi(,175)
+../tar_texi/getdate.texi(,176) The year can also be omitted. In this case,
the last specified year is
+../tar_texi/getdate.texi(,177) used, or the current year if none. For example:
+../tar_texi/getdate.texi(,178)
+../tar_texi/getdate.texi(,179) @example
+../tar_texi/getdate.texi(,180) 9/24
+../tar_texi/getdate.texi(,181) sep 24
+../tar_texi/getdate.texi(,182) @end example
+../tar_texi/getdate.texi(,183)
+../tar_texi/getdate.texi(,184) Here are the rules.
+../tar_texi/getdate.texi(,185)
+../tar_texi/getdate.texi(,186) @cindex @sc{iso} 8601 date format
+../tar_texi/getdate.texi(,187) @cindex date format, @sc{iso} 8601
+../tar_texi/getdate.texi(,188) For numeric months, the @sc{iso} 8601 format
+../tar_texi/getdate.texi(,189) @address@hidden@address@hidden is allowed,
where @var{year} is
+../tar_texi/getdate.texi(,190) any positive number, @var{month} is a number
between 01 and 12, and
+../tar_texi/getdate.texi(,191) @var{day} is a number between 01 and 31. A
leading zero must be present
+../tar_texi/getdate.texi(,192) if a number is less than ten. If @var{year} is
68 or smaller, then 2000
+../tar_texi/getdate.texi(,193) is added to it; otherwise, if @var{year} is
less than 100,
+../tar_texi/getdate.texi(,194) then 1900 is added to it. The construct
+../tar_texi/getdate.texi(,195) @address@hidden/@var{day}/@var{year}}, popular
in the United States,
+../tar_texi/getdate.texi(,196) is accepted. Also @address@hidden/@var{day}},
omitting the year.
+../tar_texi/getdate.texi(,197)
+../tar_texi/getdate.texi(,198) @cindex month names in date strings
+../tar_texi/getdate.texi(,199) @cindex abbreviations for months
+../tar_texi/getdate.texi(,200) Literal months may be spelled out in full:
@samp{January},
+../tar_texi/getdate.texi(,201) @samp{February}, @samp{March}, @samp{April},
@samp{May}, @samp{June},
+../tar_texi/getdate.texi(,202) @samp{July}, @samp{August}, @samp{September},
@samp{October},
+../tar_texi/getdate.texi(,203) @samp{November} or @samp{December}. Literal
months may be abbreviated
+../tar_texi/getdate.texi(,204) to their first three letters, possibly followed
by an abbreviating dot.
+../tar_texi/getdate.texi(,205) It is also permitted to write @samp{Sept}
instead of @samp{September}.
+../tar_texi/getdate.texi(,206)
+../tar_texi/getdate.texi(,207) When months are written literally, the calendar
date may be given as any
+../tar_texi/getdate.texi(,208) of the following:
+../tar_texi/getdate.texi(,209)
+../tar_texi/getdate.texi(,210) @example
+../tar_texi/getdate.texi(,211) @var{day} @var{month} @var{year}
+../tar_texi/getdate.texi(,212) @var{day} @var{month}
+../tar_texi/getdate.texi(,213) @var{month} @var{day} @var{year}
+../tar_texi/getdate.texi(,214) @address@hidden@var{year}
+../tar_texi/getdate.texi(,215) @end example
+../tar_texi/getdate.texi(,216)
+../tar_texi/getdate.texi(,217) Or, omitting the year:
+../tar_texi/getdate.texi(,218)
+../tar_texi/getdate.texi(,219) @example
+../tar_texi/getdate.texi(,220) @var{month} @var{day}
+../tar_texi/getdate.texi(,221) @end example
+../tar_texi/getdate.texi(,222)
+../tar_texi/getdate.texi(,223)
+../tar_texi/getdate.texi(,224) @node Time of day items
+../tar_texi/getdate.texi(,225) @section Time of day items
+../tar_texi/getdate.texi(,226)
+../tar_texi/getdate.texi(,227) @cindex time of day item
+../tar_texi/getdate.texi(,228)
+../tar_texi/getdate.texi(,229) A @dfn{time of day item} in date strings
specifies the time on a given
+../tar_texi/getdate.texi(,230) day. Here are some examples, all of which
represent the same time:
+../tar_texi/getdate.texi(,231)
+../tar_texi/getdate.texi(,232) @example
+../tar_texi/getdate.texi(,233) 20:02:00.000000
+../tar_texi/getdate.texi(,234) 20:02
+../tar_texi/getdate.texi(,235) 8:02pm
+../tar_texi/getdate.texi(,236) 20:02-0500 # In @sc{est} (U.S. Eastern
Standard Time).
+../tar_texi/getdate.texi(,237) @end example
+../tar_texi/getdate.texi(,238)
+../tar_texi/getdate.texi(,239) More generally, the time of day may be given as
+../tar_texi/getdate.texi(,240) @address@hidden:@var{minute}:@var{second}},
where @var{hour} is
+../tar_texi/getdate.texi(,241) a number between 0 and 23, @var{minute} is a
number between 0 and
+../tar_texi/getdate.texi(,242) 59, and @var{second} is a number between 0 and
59 possibly followed by
+../tar_texi/getdate.texi(,243) @samp{.} or @samp{,} and a fraction containing
one or more digits.
+../tar_texi/getdate.texi(,244) Alternatively,
+../tar_texi/getdate.texi(,245) @samp{:@var{second}} can be omitted, in which
case it is taken to
+../tar_texi/getdate.texi(,246) be zero. On the rare hosts that support leap
seconds, @var{second}
+../tar_texi/getdate.texi(,247) may be 60.
+../tar_texi/getdate.texi(,248)
+../tar_texi/getdate.texi(,249) @findex am @r{in date strings}
+../tar_texi/getdate.texi(,250) @findex pm @r{in date strings}
+../tar_texi/getdate.texi(,251) @findex midnight @r{in date strings}
+../tar_texi/getdate.texi(,252) @findex noon @r{in date strings}
+../tar_texi/getdate.texi(,253) If the time is followed by @samp{am} or
@samp{pm} (or @samp{a.m.}
+../tar_texi/getdate.texi(,254) or @samp{p.m.}), @var{hour} is restricted to
run from 1 to 12, and
+../tar_texi/getdate.texi(,255) @samp{:@var{minute}} may be omitted (taken to
be zero). @samp{am}
+../tar_texi/getdate.texi(,256) indicates the first half of the day, @samp{pm}
indicates the second
+../tar_texi/getdate.texi(,257) half of the day. In this notation, 12 is the
predecessor of 1:
+../tar_texi/getdate.texi(,258) midnight is @samp{12am} while noon is
@samp{12pm}.
+../tar_texi/getdate.texi(,259) (This is the zero-oriented interpretation of
@samp{12am} and @samp{12pm},
+../tar_texi/getdate.texi(,260) as opposed to the old tradition derived from
Latin
+../tar_texi/getdate.texi(,261) which uses @samp{12m} for noon and @samp{12pm}
for midnight.)
+../tar_texi/getdate.texi(,262)
+../tar_texi/getdate.texi(,263) @cindex time zone correction
+../tar_texi/getdate.texi(,264) @cindex minutes, time zone correction by
+../tar_texi/getdate.texi(,265) The time may alternatively be followed by a
time zone correction,
+../tar_texi/getdate.texi(,266) expressed as @address@hidden@address@hidden,
where @var{s} is @samp{+}
+../tar_texi/getdate.texi(,267) or @samp{-}, @var{hh} is a number of zone hours
and @var{mm} is a number
+../tar_texi/getdate.texi(,268) of zone minutes. You can also separate
@var{hh} from @var{mm} with a colon.
+../tar_texi/getdate.texi(,269) When a time zone correction is given this way,
it
+../tar_texi/getdate.texi(,270) forces interpretation of the time relative to
+../tar_texi/getdate.texi(,271) Coordinated Universal Time (@sc{utc}),
overriding any previous
+../tar_texi/getdate.texi(,272) specification for the time zone or the local
time zone. For example,
+../tar_texi/getdate.texi(,273) @samp{+0530} and @samp{+05:30} both stand for
the time zone 5.5 hours
+../tar_texi/getdate.texi(,274) ahead of @sc{utc} (e.g., India). The
@var{minute}
+../tar_texi/getdate.texi(,275) part of the time of day may not be elided when
a time zone correction
+../tar_texi/getdate.texi(,276) is used. This is the best way to specify a
time zone correction by
+../tar_texi/getdate.texi(,277) fractional parts of an hour.
+../tar_texi/getdate.texi(,278)
+../tar_texi/getdate.texi(,279) Either @samp{am}/@samp{pm} or a time zone
correction may be specified,
+../tar_texi/getdate.texi(,280) but not both.
+../tar_texi/getdate.texi(,281)
+../tar_texi/getdate.texi(,282)
+../tar_texi/getdate.texi(,283) @node Time zone items
+../tar_texi/getdate.texi(,284) @section Time zone items
+../tar_texi/getdate.texi(,285)
+../tar_texi/getdate.texi(,286) @cindex time zone item
+../tar_texi/getdate.texi(,287)
+../tar_texi/getdate.texi(,288) A @dfn{time zone item} specifies an
international time zone, indicated
+../tar_texi/getdate.texi(,289) by a small set of letters, e.g., @samp{UTC} or
@samp{Z}
+../tar_texi/getdate.texi(,290) for Coordinated Universal
+../tar_texi/getdate.texi(,291) Time. Any included periods are ignored. By
following a
+../tar_texi/getdate.texi(,292) non-daylight-saving time zone by the string
@samp{DST} in a separate
+../tar_texi/getdate.texi(,293) word (that is, separated by some white space),
the corresponding
+../tar_texi/getdate.texi(,294) daylight saving time zone may be specified.
+../tar_texi/getdate.texi(,295) Alternatively, a non-daylight-saving time zone
can be followed by a
+../tar_texi/getdate.texi(,296) time zone correction, to add the two values.
This is normally done
+../tar_texi/getdate.texi(,297) only for @samp{UTC}; for example,
@samp{UTC+05:30} is equivalent to
+../tar_texi/getdate.texi(,298) @samp{+05:30}.
+../tar_texi/getdate.texi(,299)
+../tar_texi/getdate.texi(,300) Time zone items other than @samp{UTC} and
@samp{Z}
+../tar_texi/getdate.texi(,301) are obsolescent and are not recommended,
because they
+../tar_texi/getdate.texi(,302) are ambiguous; for example, @samp{EST} has a
different meaning in
+../tar_texi/getdate.texi(,303) Australia than in the United States. Instead,
it's better to use
+../tar_texi/getdate.texi(,304) unambiguous numeric time zone corrections like
@samp{-0500}, as
+../tar_texi/getdate.texi(,305) described in the previous section.
+../tar_texi/getdate.texi(,306)
+../tar_texi/getdate.texi(,307) If neither a time zone item nor a time zone
correction is supplied,
+../tar_texi/getdate.texi(,308) time stamps are interpreted using the rules of
the default time zone
+../tar_texi/getdate.texi(,309) (@pxref{Specifying time zone rules}).
+../tar_texi/getdate.texi(,310)
+../tar_texi/getdate.texi(,311)
+../tar_texi/getdate.texi(,312) @node Day of week items
+../tar_texi/getdate.texi(,313) @section Day of week items
+../tar_texi/getdate.texi(,314)
+../tar_texi/getdate.texi(,315) @cindex day of week item
+../tar_texi/getdate.texi(,316)
+../tar_texi/getdate.texi(,317) The explicit mention of a day of the week will
forward the date
+../tar_texi/getdate.texi(,318) (only if necessary) to reach that day of the
week in the future.
+../tar_texi/getdate.texi(,319)
+../tar_texi/getdate.texi(,320) Days of the week may be spelled out in full:
@samp{Sunday},
+../tar_texi/getdate.texi(,321) @samp{Monday}, @samp{Tuesday},
@samp{Wednesday}, @samp{Thursday},
+../tar_texi/getdate.texi(,322) @samp{Friday} or @samp{Saturday}. Days may be
abbreviated to their
+../tar_texi/getdate.texi(,323) first three letters, optionally followed by a
period. The special
+../tar_texi/getdate.texi(,324) abbreviations @samp{Tues} for @samp{Tuesday},
@samp{Wednes} for
+../tar_texi/getdate.texi(,325) @samp{Wednesday} and @samp{Thur} or
@samp{Thurs} for @samp{Thursday} are
+../tar_texi/getdate.texi(,326) also allowed.
+../tar_texi/getdate.texi(,327)
+../tar_texi/getdate.texi(,328) @findex next @var{day}
+../tar_texi/getdate.texi(,329) @findex last @var{day}
+../tar_texi/getdate.texi(,330) A number may precede a day of the week item to
move forward
+../tar_texi/getdate.texi(,331) supplementary weeks. It is best used in
expression like @samp{third
+../tar_texi/getdate.texi(,332) monday}. In this context, @samp{last
@var{day}} or @samp{next
+../tar_texi/getdate.texi(,333) @var{day}} is also acceptable; they move one
week before or after
+../tar_texi/getdate.texi(,334) the day that @var{day} by itself would
represent.
+../tar_texi/getdate.texi(,335)
+../tar_texi/getdate.texi(,336) A comma following a day of the week item is
ignored.
+../tar_texi/getdate.texi(,337)
+../tar_texi/getdate.texi(,338)
+../tar_texi/getdate.texi(,339) @node Relative items in date strings
+../tar_texi/getdate.texi(,340) @section Relative items in date strings
+../tar_texi/getdate.texi(,341)
+../tar_texi/getdate.texi(,342) @cindex relative items in date strings
+../tar_texi/getdate.texi(,343) @cindex displacement of dates
+../tar_texi/getdate.texi(,344)
+../tar_texi/getdate.texi(,345) @dfn{Relative items} adjust a date (or the
current date if none) forward
+../tar_texi/getdate.texi(,346) or backward. The effects of relative items
accumulate. Here are some
+../tar_texi/getdate.texi(,347) examples:
+../tar_texi/getdate.texi(,348)
+../tar_texi/getdate.texi(,349) @example
+../tar_texi/getdate.texi(,350) 1 year
+../tar_texi/getdate.texi(,351) 1 year ago
+../tar_texi/getdate.texi(,352) 3 years
+../tar_texi/getdate.texi(,353) 2 days
+../tar_texi/getdate.texi(,354) @end example
+../tar_texi/getdate.texi(,355)
+../tar_texi/getdate.texi(,356) @findex year @r{in date strings}
+../tar_texi/getdate.texi(,357) @findex month @r{in date strings}
+../tar_texi/getdate.texi(,358) @findex fortnight @r{in date strings}
+../tar_texi/getdate.texi(,359) @findex week @r{in date strings}
+../tar_texi/getdate.texi(,360) @findex day @r{in date strings}
+../tar_texi/getdate.texi(,361) @findex hour @r{in date strings}
+../tar_texi/getdate.texi(,362) @findex minute @r{in date strings}
+../tar_texi/getdate.texi(,363) The unit of time displacement may be selected
by the string @samp{year}
+../tar_texi/getdate.texi(,364) or @samp{month} for moving by whole years or
months. These are fuzzy
+../tar_texi/getdate.texi(,365) units, as years and months are not all of equal
duration. More precise
+../tar_texi/getdate.texi(,366) units are @samp{fortnight} which is worth 14
days, @samp{week} worth 7
+../tar_texi/getdate.texi(,367) days, @samp{day} worth 24 hours, @samp{hour}
worth 60 minutes,
+../tar_texi/getdate.texi(,368) @samp{minute} or @samp{min} worth 60 seconds,
and @samp{second} or
+../tar_texi/getdate.texi(,369) @samp{sec} worth one second. An @samp{s}
suffix on these units is
+../tar_texi/getdate.texi(,370) accepted and ignored.
+../tar_texi/getdate.texi(,371)
+../tar_texi/getdate.texi(,372) @findex ago @r{in date strings}
+../tar_texi/getdate.texi(,373) The unit of time may be preceded by a
multiplier, given as an optionally
+../tar_texi/getdate.texi(,374) signed number. Unsigned numbers are taken as
positively signed. No
+../tar_texi/getdate.texi(,375) number at all implies 1 for a multiplier.
Following a relative item by
+../tar_texi/getdate.texi(,376) the string @samp{ago} is equivalent to
preceding the unit by a
+../tar_texi/getdate.texi(,377) multiplier with value @math{-1}.
+../tar_texi/getdate.texi(,378)
+../tar_texi/getdate.texi(,379) @findex day @r{in date strings}
+../tar_texi/getdate.texi(,380) @findex tomorrow @r{in date strings}
+../tar_texi/getdate.texi(,381) @findex yesterday @r{in date strings}
+../tar_texi/getdate.texi(,382) The string @samp{tomorrow} is worth one day in
the future (equivalent
+../tar_texi/getdate.texi(,383) to @samp{day}), the string @samp{yesterday} is
worth
+../tar_texi/getdate.texi(,384) one day in the past (equivalent to @samp{day
ago}).
+../tar_texi/getdate.texi(,385)
+../tar_texi/getdate.texi(,386) @findex now @r{in date strings}
+../tar_texi/getdate.texi(,387) @findex today @r{in date strings}
+../tar_texi/getdate.texi(,388) @findex this @r{in date strings}
+../tar_texi/getdate.texi(,389) The strings @samp{now} or @samp{today} are
relative items corresponding
+../tar_texi/getdate.texi(,390) to zero-valued time displacement, these strings
come from the fact
+../tar_texi/getdate.texi(,391) a zero-valued time displacement represents the
current time when not
+../tar_texi/getdate.texi(,392) otherwise changed by previous items. They may
be used to stress other
+../tar_texi/getdate.texi(,393) items, like in @samp{12:00 today}. The string
@samp{this} also has
+../tar_texi/getdate.texi(,394) the meaning of a zero-valued time displacement,
but is preferred in
+../tar_texi/getdate.texi(,395) date strings like @samp{this thursday}.
+../tar_texi/getdate.texi(,396)
+../tar_texi/getdate.texi(,397) When a relative item causes the resulting date
to cross a boundary
+../tar_texi/getdate.texi(,398) where the clocks were adjusted, typically for
daylight saving time,
+../tar_texi/getdate.texi(,399) the resulting date and time are adjusted
accordingly.
+../tar_texi/getdate.texi(,400)
+../tar_texi/getdate.texi(,401) The fuzz in units can cause problems with
relative items. For
+../tar_texi/getdate.texi(,402) example, @samp{2003-07-31 -1 month} might
evaluate to 2003-07-01,
+../tar_texi/getdate.texi(,403) because 2003-06-31 is an invalid date. To
determine the previous
+../tar_texi/getdate.texi(,404) month more reliably, you can ask for the month
before the 15th of the
+../tar_texi/getdate.texi(,405) current month. For example:
+../tar_texi/getdate.texi(,406)
+../tar_texi/getdate.texi(,407) @example
+../tar_texi/getdate.texi(,408) $ date -R
+../tar_texi/getdate.texi(,409) Thu, 31 Jul 2003 13:02:39 -0700
+../tar_texi/getdate.texi(,410) $ date --date='-1 month' +'Last month was %B?'
+../tar_texi/getdate.texi(,411) Last month was July?
+../tar_texi/getdate.texi(,412) $ date --date="$(date +%Y-%m-15) -1 month"
+'Last month was %B!'
+../tar_texi/getdate.texi(,413) Last month was June!
+../tar_texi/getdate.texi(,414) @end example
+../tar_texi/getdate.texi(,415)
+../tar_texi/getdate.texi(,416) Also, take care when manipulating dates around
clock changes such as
+../tar_texi/getdate.texi(,417) daylight saving leaps. In a few cases these
have added or subtracted
+../tar_texi/getdate.texi(,418) as much as 24 hours from the clock, so it is
often wise to adopt
+../tar_texi/getdate.texi(,419) universal time by setting the @env{TZ}
environment variable to
+../tar_texi/getdate.texi(,420) @samp{UTC0} before embarking on calendrical
calculations.
+../tar_texi/getdate.texi(,421)
+../tar_texi/getdate.texi(,422) @node Pure numbers in date strings
+../tar_texi/getdate.texi(,423) @section Pure numbers in date strings
+../tar_texi/getdate.texi(,424)
+../tar_texi/getdate.texi(,425) @cindex pure numbers in date strings
+../tar_texi/getdate.texi(,426)
+../tar_texi/getdate.texi(,427) The precise interpretation of a pure decimal
number depends
+../tar_texi/getdate.texi(,428) on the context in the date string.
+../tar_texi/getdate.texi(,429)
+../tar_texi/getdate.texi(,430) If the decimal number is of the form
@address@hidden@var{dd} and no
+../tar_texi/getdate.texi(,431) other calendar date item (@pxref{Calendar date
items}) appears before it
+../tar_texi/getdate.texi(,432) in the date string, then @var{yyyy} is read as
the year, @var{mm} as the
+../tar_texi/getdate.texi(,433) month number and @var{dd} as the day of the
month, for the specified
+../tar_texi/getdate.texi(,434) calendar date.
+../tar_texi/getdate.texi(,435)
+../tar_texi/getdate.texi(,436) If the decimal number is of the form
@address@hidden and no other time
+../tar_texi/getdate.texi(,437) of day item appears before it in the date
string, then @var{hh} is read
+../tar_texi/getdate.texi(,438) as the hour of the day and @var{mm} as the
minute of the hour, for the
+../tar_texi/getdate.texi(,439) specified time of day. @var{mm} can also be
omitted.
+../tar_texi/getdate.texi(,440)
+../tar_texi/getdate.texi(,441) If both a calendar date and a time of day
appear to the left of a number
+../tar_texi/getdate.texi(,442) in the date string, but no relative item, then
the number overrides the
+../tar_texi/getdate.texi(,443) year.
+../tar_texi/getdate.texi(,444)
+../tar_texi/getdate.texi(,445)
+../tar_texi/getdate.texi(,446) @node Seconds since the Epoch
+../tar_texi/getdate.texi(,447) @section Seconds since the Epoch
+../tar_texi/getdate.texi(,448)
+../tar_texi/getdate.texi(,449) If you precede a number with @samp{@@}, it
represents an internal time
+../tar_texi/getdate.texi(,450) stamp as a count of seconds. The number can
contain an internal
+../tar_texi/getdate.texi(,451) decimal point (either @samp{.} or @samp{,});
any excess precision not
+../tar_texi/getdate.texi(,452) supported by the internal representation is
truncated toward minus
+../tar_texi/getdate.texi(,453) infinity. Such a number cannot be combined
with any other date
+../tar_texi/getdate.texi(,454) item, as it specifies a complete time stamp.
+../tar_texi/getdate.texi(,455)
+../tar_texi/getdate.texi(,456) @cindex beginning of time, for @acronym{POSIX}
+../tar_texi/getdate.texi(,457) @cindex epoch, for @acronym{POSIX}
+../tar_texi/getdate.texi(,458) Internally, computer times are represented as a
count of seconds since
+../tar_texi/getdate.texi(,459) an epoch---a well-defined point of time. On
@acronym{GNU} and
+../tar_texi/getdate.texi(,460) @acronym{POSIX} systems, the epoch is
1970-01-01 00:00:00 @sc{utc}, so
+../tar_texi/getdate.texi(,461) @samp{@@0} represents this time, @samp{@@1}
represents 1970-01-01
+../tar_texi/getdate.texi(,462) 00:00:01 @sc{utc}, and so forth. @acronym{GNU}
and most other
+../tar_texi/getdate.texi(,463) @acronym{POSIX}-compliant systems support such
times as an extension
+../tar_texi/getdate.texi(,464) to @acronym{POSIX}, using negative counts, so
that @samp{@@-1}
+../tar_texi/getdate.texi(,465) represents 1969-12-31 23:59:59 @sc{utc}.
+../tar_texi/getdate.texi(,466)
+../tar_texi/getdate.texi(,467) Traditional Unix systems count seconds with
32-bit two's-complement
+../tar_texi/getdate.texi(,468) integers and can represent times from
1901-12-13 20:45:52 through
+../tar_texi/getdate.texi(,469) 2038-01-19 03:14:07 @sc{utc}. More modern
systems use 64-bit counts
+../tar_texi/getdate.texi(,470) of seconds with nanosecond subcounts, and can
represent all the times
+../tar_texi/getdate.texi(,471) in the known lifetime of the universe to a
resolution of 1 nanosecond.
+../tar_texi/getdate.texi(,472)
+../tar_texi/getdate.texi(,473) On most hosts, these counts ignore the presence
of leap seconds.
+../tar_texi/getdate.texi(,474) For example, on most hosts @samp{@@915148799}
represents 1998-12-31
+../tar_texi/getdate.texi(,475) 23:59:59 @sc{utc}, @samp{@@915148800}
represents 1999-01-01 00:00:00
+../tar_texi/getdate.texi(,476) @sc{utc}, and there is no way to represent the
intervening leap second
+../tar_texi/getdate.texi(,477) 1998-12-31 23:59:60 @sc{utc}.
+../tar_texi/getdate.texi(,478)
+../tar_texi/getdate.texi(,479) @node Specifying time zone rules
+../tar_texi/getdate.texi(,480) @section Specifying time zone rules
+../tar_texi/getdate.texi(,481)
+../tar_texi/getdate.texi(,482) @vindex TZ
+../tar_texi/getdate.texi(,483) Normally, dates are interpreted using the rules
of the current time
+../tar_texi/getdate.texi(,484) zone, which in turn are specified by the
@env{TZ} environment
+../tar_texi/getdate.texi(,485) variable, or by a system default if @env{TZ} is
not set. To specify a
+../tar_texi/getdate.texi(,486) different set of default time zone rules that
apply just to one date,
+../tar_texi/getdate.texi(,487) start the date with a string of the form
@samp{TZ="@var{rule}"}. The
+../tar_texi/getdate.texi(,488) two quote characters (@samp{"}) must be present
in the date, and any
+../tar_texi/getdate.texi(,489) quotes or backslashes within @var{rule} must be
escaped by a
+../tar_texi/getdate.texi(,490) backslash.
+../tar_texi/getdate.texi(,491)
+../tar_texi/getdate.texi(,492) For example, with the @acronym{GNU}
@command{date} command you can
+../tar_texi/getdate.texi(,493) answer the question ``What time is it in New
York when a Paris clock
+../tar_texi/getdate.texi(,494) shows 6:30am on October 31, 2004?'' by using a
date beginning with
+../tar_texi/getdate.texi(,495) @samp{TZ="Europe/Paris"} as shown in the
following shell transcript:
+../tar_texi/getdate.texi(,496)
+../tar_texi/getdate.texi(,497) @example
+../tar_texi/getdate.texi(,498) $ export TZ="America/New_York"
+../tar_texi/getdate.texi(,499) $ date --date='TZ="Europe/Paris" 2004-10-31
06:30'
+../tar_texi/getdate.texi(,500) Sun Oct 31 01:30:00 EDT 2004
+../tar_texi/getdate.texi(,501) @end example
+../tar_texi/getdate.texi(,502)
+../tar_texi/getdate.texi(,503) In this example, the @option{--date} operand
begins with its own
+../tar_texi/getdate.texi(,504) @env{TZ} setting, so the rest of that operand
is processed according
+../tar_texi/getdate.texi(,505) to @samp{Europe/Paris} rules, treating the
string @samp{2004-10-31
+../tar_texi/getdate.texi(,506) 06:30} as if it were in Paris. However, since
the output of the
+../tar_texi/getdate.texi(,507) @command{date} command is processed according
to the overall time zone
+../tar_texi/getdate.texi(,508) rules, it uses New York time. (Paris was
normally six hours ahead of
+../tar_texi/getdate.texi(,509) New York in 2004, but this example refers to a
brief Halloween period
+../tar_texi/getdate.texi(,510) when the gap was five hours.)
+../tar_texi/getdate.texi(,511)
+../tar_texi/getdate.texi(,512) A @env{TZ} value is a rule that typically names
a location in the
+../tar_texi/getdate.texi(,513) @uref{http://www.twinsun.com/tz/tz-link.htm,
@samp{tz} database}.
+../tar_texi/getdate.texi(,514) A recent catalog of location names appears in
the
+../tar_texi/getdate.texi(,515) @uref{http://twiki.org/cgi-bin/xtra/tzdate,
TWiki Date and Time
+../tar_texi/getdate.texi(,516) Gateway}. A few address@hidden hosts require a
colon before a
+../tar_texi/getdate.texi(,517) location name in a @env{TZ} setting, e.g.,
+../tar_texi/getdate.texi(,518) @samp{TZ=":America/New_York"}.
+../tar_texi/getdate.texi(,519)
+../tar_texi/getdate.texi(,520) The @samp{tz} database includes a wide variety
of locations ranging
+../tar_texi/getdate.texi(,521) from @samp{Arctic/Longyearbyen} to
@samp{Antarctica/South_Pole}, but
+../tar_texi/getdate.texi(,522) if you are at sea and have your own private
time zone, or if you are
+../tar_texi/getdate.texi(,523) using a address@hidden host that does not
support the @samp{tz}
+../tar_texi/getdate.texi(,524) database, you may need to use a @acronym{POSIX}
rule instead. Simple
+../tar_texi/getdate.texi(,525) @acronym{POSIX} rules like @samp{UTC0} specify
a time zone without
+../tar_texi/getdate.texi(,526) daylight saving time; other rules can specify
simple daylight saving
+../tar_texi/getdate.texi(,527) regimes. @xref{TZ Variable,, Specifying the
Time Zone with @code{TZ},
+../tar_texi/getdate.texi(,528) libc, The GNU C Library}.
+../tar_texi/getdate.texi(,529)
+../tar_texi/getdate.texi(,530) @node Authors of get_date
+../tar_texi/getdate.texi(,531) @section Authors of @code{get_date}
+../tar_texi/getdate.texi(,532)
+../tar_texi/getdate.texi(,533) @cindex authors of @code{get_date}
+../tar_texi/getdate.texi(,534)
+../tar_texi/getdate.texi(,535) @cindex Bellovin, Steven M.
+../tar_texi/getdate.texi(,536) @cindex Salz, Rich
+../tar_texi/getdate.texi(,537) @cindex Berets, Jim
+../tar_texi/getdate.texi(,538) @cindex MacKenzie, David
+../tar_texi/getdate.texi(,539) @cindex Meyering, Jim
+../tar_texi/getdate.texi(,540) @cindex Eggert, Paul
+../tar_texi/getdate.texi(,541) @code{get_date} was originally implemented by
Steven M. Bellovin
+../tar_texi/getdate.texi(,542) (@email{smb@@research.att.com}) while at the
University of North Carolina
+../tar_texi/getdate.texi(,543) at Chapel Hill. The code was later tweaked by
a couple of people on
+../tar_texi/getdate.texi(,544) Usenet, then completely overhauled by Rich $alz
(@email{rsalz@@bbn.com})
+../tar_texi/getdate.texi(,545) and Jim Berets (@email{jberets@@bbn.com}) in
August, 1990. Various
+../tar_texi/getdate.texi(,546) revisions for the @sc{gnu} system were made by
David MacKenzie, Jim Meyering,
+../tar_texi/getdate.texi(,547) Paul Eggert and others.
+../tar_texi/getdate.texi(,548)
+../tar_texi/getdate.texi(,549) @cindex Pinard, F.
+../tar_texi/getdate.texi(,550) @cindex Berry, K.
+../tar_texi/getdate.texi(,551) This chapter was originally produced by
address@hidden Pinard
+../tar_texi/getdate.texi(,552) (@email{pinard@@iro.umontreal.ca}) from the
@file{getdate.y} source code,
+../tar_texi/getdate.texi(,553) and then edited by K.@: Berry
(@email{kb@@cs.umb.edu}).
+../tar_texi/tar.texi(,7629)
+../tar_texi/tar.texi(,7630) @node Formats
+../tar_texi/tar.texi(,7631) @chapter Controlling the Archive Format
+../tar_texi/tar.texi(,7632)
+../tar_texi/tar.texi(,7633) @cindex Tar archive formats
+../tar_texi/tar.texi(,7634) Due to historical reasons, there are several
formats of tar archives.
+../tar_texi/tar.texi(,7635) All of them are based on the same principles, but
have some subtle
+../tar_texi/tar.texi(,7636) differences that often make them incompatible with
each other.
+../tar_texi/tar.texi(,7637)
+../tar_texi/tar.texi(,7638) GNU tar is able to create and handle archives in a
variety of formats.
+../tar_texi/tar.texi(,7639) The most frequently used formats are (in
alphabetical order):
+../tar_texi/tar.texi(,7640)
+../tar_texi/tar.texi(,7641) @table @asis
+../tar_texi/tar.texi(,7642) @item gnu
+../tar_texi/tar.texi(GNUTAR,7643) Format used by
../tar_texi/tar.texi(GNUTAR,7643) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7643) versions up to 1.13.25. This
format derived
+../tar_texi/tar.texi(,7644) from an early @acronym{POSIX} standard, adding
some improvements such as
+../tar_texi/tar.texi(,7645) sparse file handling and incremental archives.
Unfortunately these
+../tar_texi/tar.texi(,7646) features were implemented in a way incompatible
with other archive
+../tar_texi/tar.texi(,7647) formats.
+../tar_texi/tar.texi(,7648)
+../tar_texi/tar.texi(,7649) Archives in @samp{gnu} format are able to hold
pathnames of unlimited
+../tar_texi/tar.texi(,7650) length.
+../tar_texi/tar.texi(,7651)
+../tar_texi/tar.texi(,7652) @item oldgnu
+../tar_texi/tar.texi(GNUTAR,7653) Format used by
../tar_texi/tar.texi(GNUTAR,7653) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7653) of versions prior to 1.12.
+../tar_texi/tar.texi(,7654)
+../tar_texi/tar.texi(,7655) @item v7
+../tar_texi/tar.texi(,7656) Archive format, compatible with the V7
implementation of tar. This
+../tar_texi/tar.texi(,7657) format imposes a number of limitations. The most
important of them
+../tar_texi/tar.texi(,7658) are:
+../tar_texi/tar.texi(,7659)
+../tar_texi/tar.texi(,7660) @enumerate
+../tar_texi/tar.texi(,7661) @item The maximum length of a file name is limited
to 99 characters.
+../tar_texi/tar.texi(,7662) @item The maximum length of a symbolic link is
limited to 99 characters.
+../tar_texi/tar.texi(,7663) @item It is impossible to store special files
(block and character
+../tar_texi/tar.texi(,7664) devices, fifos etc.)
+../tar_texi/tar.texi(,7665) @item Maximum value of user or group ID is limited
to 2097151 (7777777
+../tar_texi/tar.texi(,7666) octal)
+../tar_texi/tar.texi(,7667) @item V7 archives do not contain symbolic
ownership information (user
+../tar_texi/tar.texi(,7668) and group name of the file owner).
+../tar_texi/tar.texi(,7669) @end enumerate
+../tar_texi/tar.texi(,7670)
+../tar_texi/tar.texi(,7671) This format has traditionally been used by
Automake when producing
+../tar_texi/tar.texi(,7672) Makefiles. This practice will change in the
future, in the meantime,
+../tar_texi/tar.texi(,7673) however this means that projects containing
filenames more than 99
+../tar_texi/tar.texi(GNUTAR,7674) characters long will not be able to use
../tar_texi/tar.texi(GNUTAR,7674) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7674) 1.15.92 and
+../tar_texi/tar.texi(,7675) Automake prior to 1.9.
+../tar_texi/tar.texi(,7676)
+../tar_texi/tar.texi(,7677) @item ustar
+../tar_texi/tar.texi(,7678) Archive format defined by @acronym{POSIX.1-1988}
specification. It stores
+../tar_texi/tar.texi(,7679) symbolic ownership information. It is also able
to store
+../tar_texi/tar.texi(,7680) special files. However, it imposes several
restrictions as well:
+../tar_texi/tar.texi(,7681)
+../tar_texi/tar.texi(,7682) @enumerate
+../tar_texi/tar.texi(,7683) @item The maximum length of a file name is limited
to 256 characters,
+../tar_texi/tar.texi(,7684) provided that the filename can be split at
directory separator in
+../tar_texi/tar.texi(,7685) two parts, first of them being at most 155 bytes
long. So, in most
+../tar_texi/tar.texi(,7686) cases the maximum file name length will be shorter
than 256
+../tar_texi/tar.texi(,7687) characters.
+../tar_texi/tar.texi(,7688) @item The maximum length of a symbolic link name
is limited to
+../tar_texi/tar.texi(,7689) 100 characters.
+../tar_texi/tar.texi(,7690) @item Maximum size of a file the archive is able
to accomodate
+../tar_texi/tar.texi(,7691) is 8GB
+../tar_texi/tar.texi(,7692) @item Maximum value of UID/GID is 2097151.
+../tar_texi/tar.texi(,7693) @item Maximum number of bits in device major and
minor numbers is 21.
+../tar_texi/tar.texi(,7694) @end enumerate
+../tar_texi/tar.texi(,7695)
+../tar_texi/tar.texi(,7696) @item star
+../tar_texi/tar.texi(,7697) Format used by J@"org Schilling @command{star}
+../tar_texi/tar.texi(GNUTAR,7698) implementation.
../tar_texi/tar.texi(GNUTAR,7698) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7698) is able to read @samp{star}
archives but
+../tar_texi/tar.texi(,7699) currently does not produce them.
+../tar_texi/tar.texi(,7700)
+../tar_texi/tar.texi(,7701) @item posix
+../tar_texi/tar.texi(,7702) Archive format defined by @acronym{POSIX.1-2001}
specification. This is the
+../tar_texi/tar.texi(,7703) most flexible and feature-rich format. It does
not impose any
+../tar_texi/tar.texi(,7704) restrictions on file sizes or filename lengths.
This format is quite
+../tar_texi/tar.texi(,7705) recent, so not all tar implementations are able to
handle it properly.
+../tar_texi/tar.texi(,7706) However, this format is designed in such a way
that any tar
+../tar_texi/tar.texi(,7707) implementation able to read @samp{ustar} archives
will be able to read
+../tar_texi/tar.texi(,7708) most @samp{posix} archives as well, with the only
exception that any
+../tar_texi/tar.texi(,7709) additional information (such as long file names
etc.) will in such
+../tar_texi/tar.texi(,7710) case be extracted as plain text files along with
the files it refers to.
+../tar_texi/tar.texi(,7711)
+../tar_texi/tar.texi(,7712) This archive format will be the default format for
future versions
+../tar_texi/tar.texi(GNUTAR,7713) of ../tar_texi/tar.texi(GNUTAR,7713)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,7713) .
+../tar_texi/tar.texi(,7714)
+../tar_texi/tar.texi(,7715) @end table
+../tar_texi/tar.texi(,7716)
+../tar_texi/tar.texi(,7717) The following table summarizes the limitations of
each of these
+../tar_texi/tar.texi(,7718) formats:
+../tar_texi/tar.texi(,7719)
+../tar_texi/tar.texi(,7720) @multitable @columnfractions .10 .20 .20 .20 .20
+../tar_texi/tar.texi(,7721) @headitem Format @tab UID @tab File Size @tab Path
Name @tab Devn
+../tar_texi/tar.texi(,7722) @item gnu @tab 1.8e19 @tab Unlimited @tab
Unlimited @tab 63
+../tar_texi/tar.texi(,7723) @item oldgnu @tab 1.8e19 @tab Unlimited @tab
Unlimited @tab 63
+../tar_texi/tar.texi(,7724) @item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
+../tar_texi/tar.texi(,7725) @item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
+../tar_texi/tar.texi(,7726) @item posix @tab Unlimited @tab Unlimited @tab
Unlimited @tab Unlimited
+../tar_texi/tar.texi(,7727) @end multitable
+../tar_texi/tar.texi(,7728)
+../tar_texi/tar.texi(GNUTAR,7729) The default format for
../tar_texi/tar.texi(GNUTAR,7729) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7729) is defined at compilation
+../tar_texi/tar.texi(,7730) time. You may check it by running @command{tar
--help}, and examining
+../tar_texi/tar.texi(GNUTAR,7731) the last lines of its output. Usually,
../tar_texi/tar.texi(GNUTAR,7731) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7731) is configured
+../tar_texi/tar.texi(,7732) to create archives in @samp{gnu} format, however,
future version will
+../tar_texi/tar.texi(,7733) switch to @samp{posix}.
+../tar_texi/tar.texi(,7734)
+../tar_texi/tar.texi(,7735) @menu
+../tar_texi/tar.texi(,7736) * Compression:: Using Less Space
through Compression
+../tar_texi/tar.texi(,7737) * Attributes:: Handling File
Attributes
+../tar_texi/tar.texi(,7738) * Portability:: Making
@command{tar} Archives More Portable
+../tar_texi/tar.texi(,7739) * cpio:: Comparison of
@command{tar} and @command{cpio}
+../tar_texi/tar.texi(,7740) @end menu
+../tar_texi/tar.texi(,7741)
+../tar_texi/tar.texi(,7742) @node Compression
+../tar_texi/tar.texi(,7743) @section Using Less Space through Compression
+../tar_texi/tar.texi(,7744)
+../tar_texi/tar.texi(,7745) @menu
+../tar_texi/tar.texi(,7746) * gzip:: Creating and
Reading Compressed Archives
+../tar_texi/tar.texi(,7747) * sparse:: Archiving Sparse
Files
+../tar_texi/tar.texi(,7748) @end menu
+../tar_texi/tar.texi(,7749)
+../tar_texi/tar.texi(,7750) @node gzip
+../tar_texi/tar.texi(,7751) @subsection Creating and Reading Compressed
Archives
+../tar_texi/tar.texi(,7752) @cindex Compressed archives
+../tar_texi/tar.texi(,7753) @cindex Storing archives in compressed format
+../tar_texi/tar.texi(,7754)
+../tar_texi/tar.texi(GNUTAR,7755) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7755) is able to create and read
compressed archives. It supports
+../tar_texi/tar.texi(,7756) @command{gzip} and @command{bzip2} compression
programs. For backward
+../tar_texi/tar.texi(,7757) compatibilty, it also supports @command{compress}
command, although
+../tar_texi/tar.texi(,7758) we strongly recommend against using it, since
there is a patent
+../tar_texi/tar.texi(,7759) covering the algorithm it uses and you could be
sued for patent
+../tar_texi/tar.texi(,7760) infringement merely by running @command{compress}!
Besides, it is less
+../tar_texi/tar.texi(,7761) effective than @command{gzip} and @command{bzip2}.
+../tar_texi/tar.texi(,7762)
+../tar_texi/tar.texi(,7763) Creating a compressed archive is simple: you just
specify a
+../tar_texi/tar.texi(,7764) @dfn{compression option} along with the usual
archive creation
+../tar_texi/tar.texi(,7765) commands. The compression option is @option{-z}
(@option{--gzip}) to
+../tar_texi/tar.texi(,7766) create a @command{gzip} compressed archive,
@option{-j}
+../tar_texi/tar.texi(,7767) (@option{--bzip2}) to create a @command{bzip2}
compressed archive, and
+../tar_texi/tar.texi(,7768) @option{-Z} (@option{--compress}) to use
@command{compress} program.
+../tar_texi/tar.texi(,7769) For example:
+../tar_texi/tar.texi(,7770)
+../tar_texi/tar.texi(,7771) @smallexample
+../tar_texi/tar.texi(,7772) $ @kbd{tar cfz archive.tar.gz .}
+../tar_texi/tar.texi(,7773) @end smallexample
+../tar_texi/tar.texi(,7774)
+../tar_texi/tar.texi(,7775) Reading compressed archive is even simpler: you
don't need to specify
+../tar_texi/tar.texi(GNUTAR,7776) any additional options as
../tar_texi/tar.texi(GNUTAR,7776) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7776) recognizes its format
+../tar_texi/tar.texi(,7777) automatically. Thus, the following commands will
list and extract the
+../tar_texi/tar.texi(,7778) archive created in previous example:
+../tar_texi/tar.texi(,7779)
+../tar_texi/tar.texi(,7780) @smallexample
+../tar_texi/tar.texi(,7781) # List the compressed archive
+../tar_texi/tar.texi(,7782) $ @kbd{tar tf archive.tar.gz}
+../tar_texi/tar.texi(,7783) # Extract the compressed archive
+../tar_texi/tar.texi(,7784) $ @kbd{tar xf archive.tar.gz}
+../tar_texi/tar.texi(,7785) @end smallexample
+../tar_texi/tar.texi(,7786)
+../tar_texi/tar.texi(,7787) The only case when you have to specify a
decompression option while
+../tar_texi/tar.texi(,7788) reading the archive is when reading from a pipe or
from a tape drive
+../tar_texi/tar.texi(GNUTAR,7789) that does not support random access.
However, in this case ../tar_texi/tar.texi(GNUTAR,7789) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7789)
+../tar_texi/tar.texi(,7790) will indicate which option you should use. For
example:
+../tar_texi/tar.texi(,7791)
+../tar_texi/tar.texi(,7792) @smallexample
+../tar_texi/tar.texi(,7793) $ @kbd{cat archive.tar.gz | tar tf -}
+../tar_texi/tar.texi(,7794) tar: Archive is compressed. Use -z option
+../tar_texi/tar.texi(,7795) tar: Error is not recoverable: exiting now
+../tar_texi/tar.texi(,7796) @end smallexample
+../tar_texi/tar.texi(,7797)
+../tar_texi/tar.texi(,7798) If you see such diagnostics, just add the
suggested option to the
+../tar_texi/tar.texi(GNUTAR,7799) invocation of
../tar_texi/tar.texi(GNUTAR,7799) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7799) :
+../tar_texi/tar.texi(,7800)
+../tar_texi/tar.texi(,7801) @smallexample
+../tar_texi/tar.texi(,7802) $ @kbd{cat archive.tar.gz | tar tfz -}
+../tar_texi/tar.texi(,7803) @end smallexample
+../tar_texi/tar.texi(,7804)
+../tar_texi/tar.texi(,7805) Notice also, that there are several restrictions
on operations on
+../tar_texi/tar.texi(,7806) compressed archives. First of all, compressed
archives cannot be
+../tar_texi/tar.texi(,7807) modified, i.e., you cannot update
(@option{--update} (@option{-u})) them or delete
+../tar_texi/tar.texi(,7808) (@option{--delete}) members from them. Likewise,
you cannot append
+../tar_texi/tar.texi(,7809) another @command{tar} archive to a compressed
archive using
+../tar_texi/tar.texi(,7810) @option{--append} (@option{-r})). Secondly,
multi-volume archives cannot be
+../tar_texi/tar.texi(,7811) compressed.
+../tar_texi/tar.texi(,7812)
+../tar_texi/tar.texi(GNUTAR,7813) The following table summarizes compression
options used by ../tar_texi/tar.texi(GNUTAR,7813) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7813) .
+../tar_texi/tar.texi(,7814)
+../tar_texi/tar.texi(,7815) @table @option
+../tar_texi/tar.texi(,7816) @opindex gzip
+../tar_texi/tar.texi(,7817) @opindex ungzip
+../tar_texi/tar.texi(,7818) @item -z
+../tar_texi/tar.texi(,7819) @itemx --gzip
+../tar_texi/tar.texi(,7820) @itemx --ungzip
+../tar_texi/tar.texi(,7821) Filter the archive through @command{gzip}.
+../tar_texi/tar.texi(,7822)
+../tar_texi/tar.texi(,7823) You can use @option{--gzip} and @option{--gunzip}
on physical devices
+../tar_texi/tar.texi(,7824) (tape drives, etc.) and remote files as well as on
normal files; data
+../tar_texi/tar.texi(,7825) to or from such devices or remote files is
reblocked by another copy
+../tar_texi/tar.texi(,7826) of the @command{tar} program to enforce the
specified (or default) record
+../tar_texi/tar.texi(,7827) size. The default compression parameters are
used; if you need to
+../tar_texi/tar.texi(,7828) override them, set @env{GZIP} environment
variable, e.g.:
+../tar_texi/tar.texi(,7829)
+../tar_texi/tar.texi(,7830) @smallexample
+../tar_texi/tar.texi(,7831) $ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
+../tar_texi/tar.texi(,7832) @end smallexample
+../tar_texi/tar.texi(,7833)
+../tar_texi/tar.texi(,7834) @noindent
+../tar_texi/tar.texi(,7835) Another way would be to avoid the @option{--gzip}
(@option{--gunzip}, @option{--ungzip}, @option{-z}) option and run
+../tar_texi/tar.texi(,7836) @command{gzip} explicitly:
+../tar_texi/tar.texi(,7837)
+../tar_texi/tar.texi(,7838) @smallexample
+../tar_texi/tar.texi(,7839) $ @kbd{tar cf - subdir | gzip --best -c - >
archive.tar.gz}
+../tar_texi/tar.texi(,7840) @end smallexample
+../tar_texi/tar.texi(,7841)
+../tar_texi/tar.texi(,7842) @cindex corrupted archives
+../tar_texi/tar.texi(,7843) About corrupted compressed archives:
@command{gzip}'ed files have no
+../tar_texi/tar.texi(,7844) redundancy, for maximum compression. The adaptive
nature of the
+../tar_texi/tar.texi(,7845) compression scheme means that the compression
tables are implicitly
+../tar_texi/tar.texi(,7846) spread all over the archive. If you lose a few
blocks, the dynamic
+../tar_texi/tar.texi(,7847) construction of the compression tables becomes
unsynchronized, and there
+../tar_texi/tar.texi(,7848) is little chance that you could recover later in
the archive.
+../tar_texi/tar.texi(,7849)
+../tar_texi/tar.texi(,7850) There are pending suggestions for having a
per-volume or per-file
+../tar_texi/tar.texi(GNUTAR,7851) compression in
../tar_texi/tar.texi(GNUTAR,7851) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7851) . This would allow for viewing
the
+../tar_texi/tar.texi(,7852) contents without decompression, and for
resynchronizing decompression at
+../tar_texi/tar.texi(,7853) every volume or file, in case of corrupted
archives. Doing so, we might
+../tar_texi/tar.texi(,7854) lose some compressibility. But this would have
make recovering easier.
+../tar_texi/tar.texi(,7855) So, there are pros and cons. We'll see!
+../tar_texi/tar.texi(,7856)
+../tar_texi/tar.texi(,7857) @opindex bzip2
+../tar_texi/tar.texi(,7858) @item -j
+../tar_texi/tar.texi(,7859) @itemx --bzip2
+../tar_texi/tar.texi(,7860) Filter the archive through @code{bzip2}.
Otherwise like @option{--gzip}.
+../tar_texi/tar.texi(,7861)
+../tar_texi/tar.texi(,7862) @opindex compress
+../tar_texi/tar.texi(,7863) @opindex uncompress
+../tar_texi/tar.texi(,7864) @item -Z
+../tar_texi/tar.texi(,7865) @itemx --compress
+../tar_texi/tar.texi(,7866) @itemx --uncompress
+../tar_texi/tar.texi(,7867) Filter the archive through @command{compress}.
Otherwise like @option{--gzip}.
+../tar_texi/tar.texi(,7868)
+../tar_texi/tar.texi(,7869) The @acronym{GNU} Project recommends you not use
+../tar_texi/tar.texi(,7870) @command{compress}, because there is a patent
covering the algorithm it
+../tar_texi/tar.texi(,7871) uses. You could be sued for patent infringement
merely by running
+../tar_texi/tar.texi(,7872) @command{compress}.
+../tar_texi/tar.texi(,7873)
+../tar_texi/tar.texi(,7874) @opindex use-compress-program
+../tar_texi/tar.texi(,7875) @item address@hidden
+../tar_texi/tar.texi(,7876) Use external compression program @var{prog}. Use
this option if you
+../tar_texi/tar.texi(GNUTAR,7877) have a compression program that
../tar_texi/tar.texi(GNUTAR,7877) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,7877) does not support. There
+../tar_texi/tar.texi(,7878) are two requirements to which @var{prog} should
comply:
+../tar_texi/tar.texi(,7879)
+../tar_texi/tar.texi(,7880) First, when called without options, it should read
data from standard
+../tar_texi/tar.texi(,7881) input, compress it and output it on standard
output.
+../tar_texi/tar.texi(,7882)
+../tar_texi/tar.texi(,7883) Secondly, if called with @option{-d} argument, it
should do exactly
+../tar_texi/tar.texi(,7884) the opposite, i.e., read the compressed data from
the standard input
+../tar_texi/tar.texi(,7885) and produce uncompressed data on the standard
output.
+../tar_texi/tar.texi(,7886) @end table
+../tar_texi/tar.texi(,7887)
+../tar_texi/tar.texi(,7888) @cindex gpg, using with tar
+../tar_texi/tar.texi(,7889) @cindex gnupg, using with tar
+../tar_texi/tar.texi(,7890) @cindex Using encrypted archives
+../tar_texi/tar.texi(,7891) The @option{--use-compress-program} option, in
particular, lets you
+../tar_texi/tar.texi(,7892) implement your own filters, not necessarily
dealing with
+../tar_texi/tar.texi(,7893) compression/decomression. For example, suppose
you wish to implement
+../tar_texi/tar.texi(,7894) PGP encryption on top of compression, using
@command{gpg} (@pxref{Top,
+../tar_texi/tar.texi(,7895) gpg, gpg ---- encryption and signing tool, gpg,
GNU Privacy Guard
+../tar_texi/tar.texi(,7896) Manual}). The following script does that:
+../tar_texi/tar.texi(,7897)
+../tar_texi/tar.texi(,7898) @smallexample
+../tar_texi/tar.texi(,7899) @group
+../tar_texi/tar.texi(,7900) #! /bin/sh
+../tar_texi/tar.texi(,7901) case $1 in
+../tar_texi/tar.texi(,7902) -d) gpg --decrypt - | gzip -d -c;;
+../tar_texi/tar.texi(,7903) '') gzip -c | gpg -s ;;
+../tar_texi/tar.texi(,7904) *) echo "Unknown option $1">&2; exit 1;;
+../tar_texi/tar.texi(,7905) esac
+../tar_texi/tar.texi(,7906) @end group
+../tar_texi/tar.texi(,7907) @end smallexample
+../tar_texi/tar.texi(,7908)
+../tar_texi/tar.texi(,7909) Suppose you name it @file{gpgz} and save it
somewhere in your
+../tar_texi/tar.texi(,7910) @env{PATH}. Then the following command will
create a commpressed
+../tar_texi/tar.texi(,7911) archive signed with your private key:
+../tar_texi/tar.texi(,7912)
+../tar_texi/tar.texi(,7913) @smallexample
+../tar_texi/tar.texi(,7914) $ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
+../tar_texi/tar.texi(,7915) @end smallexample
+../tar_texi/tar.texi(,7916)
+../tar_texi/tar.texi(,7917) @noindent
+../tar_texi/tar.texi(,7918) Likewise, the following command will list its
contents:
+../tar_texi/tar.texi(,7919)
+../tar_texi/tar.texi(,7920) @smallexample
+../tar_texi/tar.texi(,7921) $ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
+../tar_texi/tar.texi(,7922) @end smallexample
+../tar_texi/tar.texi(,7923)
+../tar_texi/tar.texi(,7962)
+../tar_texi/tar.texi(,7963) @node sparse
+../tar_texi/tar.texi(,7964) @subsection Archiving Sparse Files
+../tar_texi/tar.texi(,7965) @cindex Sparse Files
+../tar_texi/tar.texi(,7966)
+../tar_texi/tar.texi(,7967) Files in the file system occasionally have
@dfn{holes}. A @dfn{hole}
+../tar_texi/tar.texi(,7968) in a file is a section of the file's contents
which was never written.
+../tar_texi/tar.texi(,7969) The contents of a hole reads as all zeros. On
many operating systems,
+../tar_texi/tar.texi(,7970) actual disk storage is not allocated for holes,
but they are counted
+../tar_texi/tar.texi(,7971) in the length of the file. If you archive such a
file, @command{tar}
+../tar_texi/tar.texi(,7972) could create an archive longer than the original.
To have @command{tar}
+../tar_texi/tar.texi(,7973) attempt to recognize the holes in a file, use
@option{--sparse}
+../tar_texi/tar.texi(,7974) (@option{-S}). When you use this option, then,
for any file using
+../tar_texi/tar.texi(,7975) less disk space than would be expected from its
length, @command{tar}
+../tar_texi/tar.texi(,7976) searches the file for consecutive stretches of
zeros. It then records
+../tar_texi/tar.texi(,7977) in the archive for the file where the consecutive
stretches of zeros
+../tar_texi/tar.texi(,7978) are, and only archives the ``real contents'' of
the file. On
+../tar_texi/tar.texi(,7979) extraction (using @option{--sparse} is not needed
on extraction) any
+../tar_texi/tar.texi(,7980) such files have holes created wherever the
continuous stretches of zeros
+../tar_texi/tar.texi(,7981) were found. Thus, if you use @option{--sparse},
@command{tar} archives
+../tar_texi/tar.texi(,7982) won't take more space than the original.
+../tar_texi/tar.texi(,7983)
+../tar_texi/tar.texi(,7984) @table @option
+../tar_texi/tar.texi(,7985) @opindex sparse
+../tar_texi/tar.texi(,7986) @item -S
+../tar_texi/tar.texi(,7987) @itemx --sparse
+../tar_texi/tar.texi(,7988) This option istructs @command{tar} to test each
file for sparseness
+../tar_texi/tar.texi(,7989) before attempting to archive it. If the file is
found to be sparse it
+../tar_texi/tar.texi(,7990) is treated specially, thus allowing to decrease
the amount of space
+../tar_texi/tar.texi(,7991) used by its image in the archive.
+../tar_texi/tar.texi(,7992)
+../tar_texi/tar.texi(,7993) This option is meaningful only when creating or
updating archives. It
+../tar_texi/tar.texi(,7994) has no effect on extraction.
+../tar_texi/tar.texi(,7995) @end table
+../tar_texi/tar.texi(,7996)
+../tar_texi/tar.texi(,7997) Consider using @option{--sparse} when performing
file system backups,
+../tar_texi/tar.texi(,7998) to avoid archiving the expanded forms of files
stored sparsely in the
+../tar_texi/tar.texi(,7999) system.
+../tar_texi/tar.texi(,8000)
+../tar_texi/tar.texi(,8001) Even if your system has no sparse files currently,
some may be
+../tar_texi/tar.texi(,8002) created in the future. If you use
@option{--sparse} while making file
+../tar_texi/tar.texi(,8003) system backups as a matter of course, you can be
assured the archive
+../tar_texi/tar.texi(,8004) will never take more space on the media than the
files take on disk
+../tar_texi/tar.texi(,8005) (otherwise, archiving a disk filled with sparse
files might take
+../tar_texi/tar.texi(,8006) hundreds of tapes). @xref{Incremental Dumps}.
+../tar_texi/tar.texi(,8007)
+../tar_texi/tar.texi(,8008) However, be aware that @option{--sparse} option
presents a serious
+../tar_texi/tar.texi(,8009) drawback. Namely, in order to determine if the
file is sparse
+../tar_texi/tar.texi(,8010) @command{tar} has to read it before trying to
archive it, so in total
+../tar_texi/tar.texi(,8011) the file is read @strong{twice}. So, always bear
in mind that the
+../tar_texi/tar.texi(,8012) time needed to process all files with this option
is roughly twice
+../tar_texi/tar.texi(,8013) the time needed to archive them without it.
+../tar_texi/tar.texi(FIXME,8038) @allow-recursion
+../tar_texi/tar.texi(FIXME,8038) @quote-arg
+../tar_texi/tar.texi(FIXME,8038)
+../tar_texi/tar.texi(,8039)
+../tar_texi/tar.texi(,8040) @cindex sparse formats, defined
+../tar_texi/tar.texi(GNUTAR,8041) When using @samp{POSIX} archive format,
../tar_texi/tar.texi(GNUTAR,8041) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8041) is able to store
+../tar_texi/tar.texi(,8042) sparse files using in three distinct ways, called
@dfn{sparse
+../tar_texi/tar.texi(,8043) formats}. A sparse format is identified by its
@dfn{number},
+../tar_texi/tar.texi(,8044) consisting, as usual of two decimal numbers,
delimited by a dot. By
+../tar_texi/tar.texi(,8045) default, format @samp{1.0} is used. If, for some
reason, you wish to
+../tar_texi/tar.texi(,8046) use an earlier format, you can select it using
+../tar_texi/tar.texi(,8047) @option{--sparse-version} option.
+../tar_texi/tar.texi(,8048)
+../tar_texi/tar.texi(,8049) @table @option
+../tar_texi/tar.texi(,8050) @opindex sparse-version
+../tar_texi/tar.texi(,8051) @item address@hidden
+../tar_texi/tar.texi(,8052)
+../tar_texi/tar.texi(,8053) Select the format to store sparse files in. Valid
@var{version} values
+../tar_texi/tar.texi(,8054) are: @samp{0.0}, @samp{0.1} and @samp{1.0}.
@xref{Sparse Formats},
+../tar_texi/tar.texi(,8055) for a detailed description of each format.
+../tar_texi/tar.texi(,8056) @end table
+../tar_texi/tar.texi(,8057)
+../tar_texi/tar.texi(,8058) Using @option{--sparse-format} option implies
@option{--sparse}.
+../tar_texi/tar.texi(,8059)
+../tar_texi/tar.texi(,8060) @node Attributes
+../tar_texi/tar.texi(,8061) @section Handling File Attributes
+../tar_texi/tar.texi(UNREVISED,8062) @quotation
+../tar_texi/tar.texi(UNREVISED,8062) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,8062) @end quotation
+../tar_texi/tar.texi(UNREVISED,8062)
+../tar_texi/tar.texi(,8063)
+../tar_texi/tar.texi(,8064) When @command{tar} reads files, it updates their
access times. To
+../tar_texi/tar.texi(,8065) avoid this, use the
@option{--atime-preserve[=METHOD]} option, which can either
+../tar_texi/tar.texi(,8066) reset the access time retroactively or avoid
changing it in the first
+../tar_texi/tar.texi(,8067) place.
+../tar_texi/tar.texi(,8068)
+../tar_texi/tar.texi(,8069) Handling of file attributes
+../tar_texi/tar.texi(,8070)
+../tar_texi/tar.texi(,8071) @table @option
+../tar_texi/tar.texi(,8072) @opindex atime-preserve
+../tar_texi/tar.texi(,8073) @item --atime-preserve
+../tar_texi/tar.texi(,8074) @itemx --atime-preserve=replace
+../tar_texi/tar.texi(,8075) @itemx --atime-preserve=system
+../tar_texi/tar.texi(,8076) Preserve the access times of files that are read.
This works only for
+../tar_texi/tar.texi(,8077) files that you own, unless you have superuser
privileges.
+../tar_texi/tar.texi(,8078)
+../tar_texi/tar.texi(,8079) @option{--atime-preserve=replace} works on most
systems, but it also
+../tar_texi/tar.texi(,8080) restores the data modification time and updates
the status change
+../tar_texi/tar.texi(,8081) time. Hence it doesn't interact with incremental
dumps nicely
+../tar_texi/tar.texi(,8082) (@pxref{Incremental Dumps}), and it can set access
or data modification times
+../tar_texi/tar.texi(,8083) incorrectly if other programs access the file
while @command{tar} is
+../tar_texi/tar.texi(,8084) running.
+../tar_texi/tar.texi(,8085)
+../tar_texi/tar.texi(,8086) @option{--atime-preserve=system} avoids changing
the access time in
+../tar_texi/tar.texi(,8087) the first place, if the operating system supports
this.
+../tar_texi/tar.texi(,8088) Unfortunately, this may or may not work on any
given operating system
+../tar_texi/tar.texi(,8089) or file system. If @command{tar} knows for sure
it won't work, it
+../tar_texi/tar.texi(,8090) complains right away.
+../tar_texi/tar.texi(,8091)
+../tar_texi/tar.texi(,8092) Currently @option{--atime-preserve} with no
operand defaults to
+../tar_texi/tar.texi(,8093) @option{--atime-preserve=replace}, but this is
intended to change to
+../tar_texi/tar.texi(,8094) @option{--atime-preserve=system} when the latter
is better-supported.
+../tar_texi/tar.texi(,8095)
+../tar_texi/tar.texi(,8096) @opindex touch
+../tar_texi/tar.texi(,8097) @item -m
+../tar_texi/tar.texi(,8098) @itemx --touch
+../tar_texi/tar.texi(,8099) Do not extract data modification time.
+../tar_texi/tar.texi(,8100)
+../tar_texi/tar.texi(,8101) When this option is used, @command{tar} leaves the
data modification times
+../tar_texi/tar.texi(,8102) of the files it extracts as the times when the
files were extracted,
+../tar_texi/tar.texi(,8103) instead of setting it to the times recorded in the
archive.
+../tar_texi/tar.texi(,8104)
+../tar_texi/tar.texi(,8105) This option is meaningless with @option{--list}
(@option{-t}).
+../tar_texi/tar.texi(,8106)
+../tar_texi/tar.texi(,8107) @opindex same-owner
+../tar_texi/tar.texi(,8108) @item --same-owner
+../tar_texi/tar.texi(,8109) Create extracted files with the same ownership
they have in the
+../tar_texi/tar.texi(,8110) archive.
+../tar_texi/tar.texi(,8111)
+../tar_texi/tar.texi(,8112) This is the default behavior for the superuser,
+../tar_texi/tar.texi(,8113) so this option is meaningful only for non-root
users, when @command{tar}
+../tar_texi/tar.texi(,8114) is executed on those systems able to give files
away. This is
+../tar_texi/tar.texi(,8115) considered as a security flaw by many people, at
least because it
+../tar_texi/tar.texi(,8116) makes quite difficult to correctly account users
for the disk space
+../tar_texi/tar.texi(,8117) they occupy. Also, the @code{suid} or @code{sgid}
attributes of
+../tar_texi/tar.texi(,8118) files are easily and silently lost when files are
given away.
+../tar_texi/tar.texi(,8119)
+../tar_texi/tar.texi(,8120) When writing an archive, @command{tar} writes the
user id and user name
+../tar_texi/tar.texi(,8121) separately. If it can't find a user name (because
the user id is not
+../tar_texi/tar.texi(,8122) in @file{/etc/passwd}), then it does not write
one. When restoring,
+../tar_texi/tar.texi(,8123) it tries to look the name (if one was written) up
in
+../tar_texi/tar.texi(,8124) @file{/etc/passwd}. If it fails, then it uses the
user id stored in
+../tar_texi/tar.texi(,8125) the archive instead.
+../tar_texi/tar.texi(,8126)
+../tar_texi/tar.texi(,8127) @opindex no-same-owner
+../tar_texi/tar.texi(,8128) @item --no-same-owner
+../tar_texi/tar.texi(,8129) @itemx -o
+../tar_texi/tar.texi(,8130) Do not attempt to restore ownership when
extracting. This is the
+../tar_texi/tar.texi(,8131) default behavior for ordinary users, so this
option has an effect
+../tar_texi/tar.texi(,8132) only for the superuser.
+../tar_texi/tar.texi(,8133)
+../tar_texi/tar.texi(,8134) @opindex numeric-owner
+../tar_texi/tar.texi(,8135) @item --numeric-owner
+../tar_texi/tar.texi(,8136) The @option{--numeric-owner} option allows (ANSI)
archives to be written
+../tar_texi/tar.texi(,8137) without user/group name information or such
information to be ignored
+../tar_texi/tar.texi(,8138) when extracting. It effectively disables the
generation and/or use
+../tar_texi/tar.texi(,8139) of user/group name information. This option
forces extraction using
+../tar_texi/tar.texi(,8140) the numeric ids from the archive, ignoring the
names.
+../tar_texi/tar.texi(,8141)
+../tar_texi/tar.texi(,8142) This is useful in certain circumstances, when
restoring a backup from
+../tar_texi/tar.texi(,8143) an emergency floppy with different passwd/group
files for example.
+../tar_texi/tar.texi(,8144) It is otherwise impossible to extract files with
the right ownerships
+../tar_texi/tar.texi(,8145) if the password file in use during the extraction
does not match the
+../tar_texi/tar.texi(,8146) one belonging to the file system(s) being
extracted. This occurs,
+../tar_texi/tar.texi(,8147) for example, if you are restoring your files after
a major crash and
+../tar_texi/tar.texi(,8148) had booted from an emergency floppy with no
password file or put your
+../tar_texi/tar.texi(,8149) disk into another machine to do the restore.
+../tar_texi/tar.texi(,8150)
+../tar_texi/tar.texi(,8151) The numeric ids are @emph{always} saved into
@command{tar} archives.
+../tar_texi/tar.texi(,8152) The identifying names are added at create time
when provided by the
+../tar_texi/tar.texi(,8153) system, unless @option{--old-archive}
(@option{-o}) is used. Numeric ids could be
+../tar_texi/tar.texi(,8154) used when moving archives between a collection of
machines using
+../tar_texi/tar.texi(,8155) a centralized management for attribution of
numeric ids to users
+../tar_texi/tar.texi(,8156) and groups. This is often made through using the
NIS capabilities.
+../tar_texi/tar.texi(,8157)
+../tar_texi/tar.texi(,8158) When making a @command{tar} file for distribution
to other sites, it
+../tar_texi/tar.texi(,8159) is sometimes cleaner to use a single owner for all
files in the
+../tar_texi/tar.texi(,8160) distribution, and nicer to specify the write
permission bits of the
+../tar_texi/tar.texi(,8161) files as stored in the archive independently of
their actual value on
+../tar_texi/tar.texi(,8162) the file system. The way to prepare a clean
distribution is usually
+../tar_texi/tar.texi(,8163) to have some Makefile rule creating a directory,
copying all needed
+../tar_texi/tar.texi(,8164) files in that directory, then setting ownership
and permissions as
+../tar_texi/tar.texi(,8165) wanted (there are a lot of possible schemes), and
only then making a
+../tar_texi/tar.texi(,8166) @command{tar} archive out of this directory,
before cleaning
+../tar_texi/tar.texi(,8167) everything out. Of course, we could add a lot of
options to
+../tar_texi/tar.texi(GNUTAR,8168) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8168) for fine tuning permissions and
ownership.
+../tar_texi/tar.texi(GNUTAR,8169) This is not the good way, I think.
../tar_texi/tar.texi(GNUTAR,8169) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8169) is
+../tar_texi/tar.texi(,8170) already crowded with options and moreover, the
approach just explained
+../tar_texi/tar.texi(,8171) gives you a great deal of control already.
+../tar_texi/tar.texi(,8172)
+../tar_texi/tar.texi(xopindex,8173) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,8173)
+../tar_texi/tar.texi(xopindex,8174) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,8174)
+../tar_texi/tar.texi(,8175) @item -p
+../tar_texi/tar.texi(,8176) @itemx --same-permissions
+../tar_texi/tar.texi(,8177) @itemx --preserve-permissions
+../tar_texi/tar.texi(,8178) Extract all protection information.
+../tar_texi/tar.texi(,8179)
+../tar_texi/tar.texi(,8180) This option causes @command{tar} to set the modes
(access permissions) of
+../tar_texi/tar.texi(,8181) extracted files exactly as recorded in the
archive. If this option
+../tar_texi/tar.texi(,8182) is not used, the current @code{umask} setting
limits the permissions
+../tar_texi/tar.texi(,8183) on extracted files. This option is by default
enabled when
+../tar_texi/tar.texi(,8184) @command{tar} is executed by a superuser.
+../tar_texi/tar.texi(,8185)
+../tar_texi/tar.texi(,8186)
+../tar_texi/tar.texi(,8187) This option is meaningless with @option{--list}
(@option{-t}).
+../tar_texi/tar.texi(,8188)
+../tar_texi/tar.texi(,8189) @opindex preserve
+../tar_texi/tar.texi(,8190) @item --preserve
+../tar_texi/tar.texi(,8191) Same as both @option{--same-permissions} and
@option{--same-order}.
+../tar_texi/tar.texi(,8192)
+../tar_texi/tar.texi(,8193) The @option{--preserve} option has no equivalent
short option name.
+../tar_texi/tar.texi(,8194) It is equivalent to @option{--same-permissions}
plus @option{--same-order}.
+../tar_texi/tar.texi(,8195)
+../tar_texi/tar.texi(FIXME,8197) @allow-recursion
+../tar_texi/tar.texi(FIXME,8197) @quote-arg
+../tar_texi/tar.texi(FIXME,8197)
+../tar_texi/tar.texi(,8198)
+../tar_texi/tar.texi(,8199) @end table
+../tar_texi/tar.texi(,8200)
+../tar_texi/tar.texi(,8201) @node Portability
+../tar_texi/tar.texi(,8202) @section Making @command{tar} Archives More
Portable
+../tar_texi/tar.texi(,8203)
+../tar_texi/tar.texi(,8204) Creating a @command{tar} archive on a particular
system that is meant to be
+../tar_texi/tar.texi(,8205) useful later on many other machines and with other
versions of @command{tar}
+../tar_texi/tar.texi(,8206) is more challenging than you might think.
@command{tar} archive formats
+../tar_texi/tar.texi(,8207) have been evolving since the first versions of
Unix. Many such formats
+../tar_texi/tar.texi(,8208) are around, and are not always compatible with
each other. This section
+../tar_texi/tar.texi(,8209) discusses a few problems, and gives some advice
about making @command{tar}
+../tar_texi/tar.texi(,8210) archives more portable.
+../tar_texi/tar.texi(,8211)
+../tar_texi/tar.texi(,8212) One golden rule is simplicity. For example, limit
your @command{tar}
+../tar_texi/tar.texi(,8213) archives to contain only regular files and
directories, avoiding
+../tar_texi/tar.texi(,8214) other kind of special files. Do not attempt to
save sparse files or
+../tar_texi/tar.texi(,8215) contiguous files as such. Let's discuss a few
more problems, in turn.
+../tar_texi/tar.texi(,8216)
+../tar_texi/tar.texi(FIXME,8218) @allow-recursion
+../tar_texi/tar.texi(FIXME,8218) @quote-arg
+../tar_texi/tar.texi(FIXME,8218)
+../tar_texi/tar.texi(,8219)
+../tar_texi/tar.texi(,8220) @menu
+../tar_texi/tar.texi(,8221) * Portable Names:: Portable Names
+../tar_texi/tar.texi(,8222) * dereference:: Symbolic Links
+../tar_texi/tar.texi(,8223) * old:: Old V7 Archives
+../tar_texi/tar.texi(,8224) * ustar:: Ustar Archives
+../tar_texi/tar.texi(,8225) * gnu:: GNU and old GNU
format archives.
+../tar_texi/tar.texi(,8226) * posix:: @acronym{POSIX}
archives
+../tar_texi/tar.texi(,8227) * Checksumming:: Checksumming
Problems
+../tar_texi/tar.texi(,8228) * Large or Negative Values:: Large files,
negative time stamps, etc.
+../tar_texi/tar.texi(,8229) * Other Tars:: How to Extract
GNU-Specific Data Using
+../tar_texi/tar.texi(,8230) Other
@command{tar} Implementations
+../tar_texi/tar.texi(,8231) @end menu
+../tar_texi/tar.texi(,8232)
+../tar_texi/tar.texi(,8233) @node Portable Names
+../tar_texi/tar.texi(,8234) @subsection Portable Names
+../tar_texi/tar.texi(,8235)
+../tar_texi/tar.texi(,8236) Use portable file and member names. A name is
portable if it contains
+../tar_texi/tar.texi(,8237) only ASCII letters and digits, @samp{/}, @samp{.},
@samp{_}, and
+../tar_texi/tar.texi(,8238) @samp{-}; it cannot be empty, start with @samp{-}
or @samp{//}, or
+../tar_texi/tar.texi(,8239) contain @samp{/-}. Avoid deep directory nesting.
For portability to
+../tar_texi/tar.texi(,8240) old Unix hosts, limit your file name components to
14 characters or
+../tar_texi/tar.texi(,8241) less.
+../tar_texi/tar.texi(,8242)
+../tar_texi/tar.texi(,8243) If you intend to have your @command{tar} archives
to be read under
+../tar_texi/tar.texi(,8244) MSDOS, you should not rely on case distinction for
file names, and you
+../tar_texi/tar.texi(,8245) might use the @acronym{GNU} @command{doschk}
program for helping you
+../tar_texi/tar.texi(,8246) further diagnosing illegal MSDOS names, which are
even more limited
+../tar_texi/tar.texi(,8247) than System V's.
+../tar_texi/tar.texi(,8248)
+../tar_texi/tar.texi(,8249) @node dereference
+../tar_texi/tar.texi(,8250) @subsection Symbolic Links
+../tar_texi/tar.texi(,8251) @cindex File names, using symbolic links
+../tar_texi/tar.texi(,8252) @cindex Symbolic link as file name
+../tar_texi/tar.texi(,8253)
+../tar_texi/tar.texi(,8254) @opindex dereference
+../tar_texi/tar.texi(,8255) Normally, when @command{tar} archives a symbolic
link, it writes a
+../tar_texi/tar.texi(,8256) block to the archive naming the target of the
link. In that way, the
+../tar_texi/tar.texi(,8257) @command{tar} archive is a faithful record of the
file system contents.
+../tar_texi/tar.texi(,8258) @option{--dereference} (@option{-h}) is used with
@option{--create} (@option{-c}), and causes
+../tar_texi/tar.texi(,8259) @command{tar} to archive the files symbolic links
point to, instead of
+../tar_texi/tar.texi(,8260) the links themselves. When this option is used,
when @command{tar}
+../tar_texi/tar.texi(,8261) encounters a symbolic link, it will archive the
linked-to file,
+../tar_texi/tar.texi(,8262) instead of simply recording the presence of a
symbolic link.
+../tar_texi/tar.texi(,8263)
+../tar_texi/tar.texi(,8264) The name under which the file is stored in the
file system is not
+../tar_texi/tar.texi(,8265) recorded in the archive. To record both the
symbolic link name and
+../tar_texi/tar.texi(,8266) the file name in the system, archive the file
under both names. If
+../tar_texi/tar.texi(,8267) all links were recorded automatically by
@command{tar}, an extracted file
+../tar_texi/tar.texi(,8268) might be linked to a file name that no longer
exists in the file
+../tar_texi/tar.texi(,8269) system.
+../tar_texi/tar.texi(,8270)
+../tar_texi/tar.texi(,8271) If a linked-to file is encountered again by
@command{tar} while creating
+../tar_texi/tar.texi(,8272) the same archive, an entire second copy of it will
be stored. (This
+../tar_texi/tar.texi(,8273) @emph{might} be considered a bug.)
+../tar_texi/tar.texi(,8274)
+../tar_texi/tar.texi(,8275) So, for portable archives, do not archive symbolic
links as such,
+../tar_texi/tar.texi(,8276) and use @option{--dereference} (@option{-h}): many
systems do not support
+../tar_texi/tar.texi(,8277) symbolic links, and moreover, your distribution
might be unusable if
+../tar_texi/tar.texi(,8278) it contains unresolved symbolic links.
+../tar_texi/tar.texi(,8279)
+../tar_texi/tar.texi(,8280) @node old
+../tar_texi/tar.texi(,8281) @subsection Old V7 Archives
+../tar_texi/tar.texi(,8282) @cindex Format, old style
+../tar_texi/tar.texi(,8283) @cindex Old style format
+../tar_texi/tar.texi(,8284) @cindex Old style archives
+../tar_texi/tar.texi(,8285) @cindex v7 archive format
+../tar_texi/tar.texi(,8286)
+../tar_texi/tar.texi(,8287) Certain old versions of @command{tar} cannot
handle additional
+../tar_texi/tar.texi(,8288) information recorded by newer @command{tar}
programs. To create an
+../tar_texi/tar.texi(,8289) archive in V7 format (not ANSI), which can be read
by these old
+../tar_texi/tar.texi(,8290) versions, specify the @option{--format=v7} option
in
+../tar_texi/tar.texi(,8291) conjunction with the @option{--create}
(@option{-c}) (@command{tar} also
+../tar_texi/tar.texi(,8292) accepts @option{--portability} or
@option{--old-archive} for this
+../tar_texi/tar.texi(,8293) option). When you specify it,
+../tar_texi/tar.texi(,8294) @command{tar} leaves out information about
directories, pipes, fifos,
+../tar_texi/tar.texi(,8295) contiguous files, and device files, and specifies
file ownership by
+../tar_texi/tar.texi(,8296) group and user IDs instead of group and user names.
+../tar_texi/tar.texi(,8297)
+../tar_texi/tar.texi(,8298) When updating an archive, do not use
@option{--format=v7}
+../tar_texi/tar.texi(,8299) unless the archive was created using this option.
+../tar_texi/tar.texi(,8300)
+../tar_texi/tar.texi(,8301) In most cases, a @emph{new} format archive can be
read by an @emph{old}
+../tar_texi/tar.texi(,8302) @command{tar} program without serious trouble, so
this option should
+../tar_texi/tar.texi(,8303) seldom be needed. On the other hand, most modern
@command{tar}s are
+../tar_texi/tar.texi(,8304) able to read old format archives, so it might be
safer for you to
+../tar_texi/tar.texi(,8305) always use @option{--format=v7} for your
distributions. Notice,
+../tar_texi/tar.texi(,8306) however, that @samp{ustar} format is a better
alternative, as it is
+../tar_texi/tar.texi(,8307) free from many of @samp{v7}'s drawbacks.
+../tar_texi/tar.texi(,8308)
+../tar_texi/tar.texi(,8309) @node ustar
+../tar_texi/tar.texi(,8310) @subsection Ustar Archive Format
+../tar_texi/tar.texi(,8311)
+../tar_texi/tar.texi(,8312) @cindex ustar archive format
+../tar_texi/tar.texi(,8313) Archive format defined by @acronym{POSIX}.1-1988
specification is called
+../tar_texi/tar.texi(,8314) @code{ustar}. Although it is more flexible than
the V7 format, it
+../tar_texi/tar.texi(,8315) still has many restrictions (@xref{Formats,ustar},
for the detailed
+../tar_texi/tar.texi(,8316) description of @code{ustar} format). Along with
V7 format,
+../tar_texi/tar.texi(,8317) @code{ustar} format is a good choice for archives
intended to be read
+../tar_texi/tar.texi(,8318) with other implementations of @command{tar}.
+../tar_texi/tar.texi(,8319)
+../tar_texi/tar.texi(,8320) To create archive in @code{ustar} format, use
@option{--format=ustar}
+../tar_texi/tar.texi(,8321) option in conjunction with the @option{--create}
(@option{-c}).
+../tar_texi/tar.texi(,8322)
+../tar_texi/tar.texi(,8323) @node gnu
+../tar_texi/tar.texi(GNUTAR,8324) @subsection @acronym{GNU} and old
../tar_texi/tar.texi(GNUTAR,8324) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8324) format
+../tar_texi/tar.texi(,8325)
+../tar_texi/tar.texi(,8326) @cindex GNU archive format
+../tar_texi/tar.texi(,8327) @cindex Old GNU archive format
+../tar_texi/tar.texi(GNUTAR,8328) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8328) was based on an early draft of
the
+../tar_texi/tar.texi(,8329) @acronym{POSIX} 1003.1 @code{ustar} standard.
@acronym{GNU} extensions to
+../tar_texi/tar.texi(,8330) @command{tar}, such as the support for file names
longer than 100
+../tar_texi/tar.texi(,8331) characters, use portions of the @command{tar}
header record which were
+../tar_texi/tar.texi(,8332) specified in that @acronym{POSIX} draft as unused.
Subsequent changes in
+../tar_texi/tar.texi(,8333) @acronym{POSIX} have allocated the same parts of
the header record for
+../tar_texi/tar.texi(GNUTAR,8334) other purposes. As a result,
../tar_texi/tar.texi(GNUTAR,8334) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8334) format is
+../tar_texi/tar.texi(,8335) incompatible with the current @acronym{POSIX}
specification, and with
+../tar_texi/tar.texi(,8336) @command{tar} programs that follow it.
+../tar_texi/tar.texi(,8337)
+../tar_texi/tar.texi(,8338) In the majority of cases, @command{tar} will be
configured to create
+../tar_texi/tar.texi(,8339) this format by default. This will change in the
future releases, since
+../tar_texi/tar.texi(,8340) we plan to make @samp{POSIX} format the default.
+../tar_texi/tar.texi(,8341)
+../tar_texi/tar.texi(GNUTAR,8342) To force creation a
../tar_texi/tar.texi(GNUTAR,8342) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8342) archive, use option
+../tar_texi/tar.texi(,8343) @option{--format=gnu}.
+../tar_texi/tar.texi(,8344)
+../tar_texi/tar.texi(,8345) @node posix
+../tar_texi/tar.texi(GNUTAR,8346) @subsection
../tar_texi/tar.texi(GNUTAR,8346) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8346) and @acronym{POSIX}
@command{tar}
+../tar_texi/tar.texi(,8347)
+../tar_texi/tar.texi(,8348) @cindex POSIX archive format
+../tar_texi/tar.texi(,8349) @cindex PAX archive format
+../tar_texi/tar.texi(GNUTAR,8350) Starting from version 1.14
../tar_texi/tar.texi(GNUTAR,8350) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8350) features full support for
+../tar_texi/tar.texi(,8351) @acronym{POSIX.1-2001} archives.
+../tar_texi/tar.texi(,8352)
+../tar_texi/tar.texi(,8353) A @acronym{POSIX} conformant archive will be
created if @command{tar}
+../tar_texi/tar.texi(,8354) was given @option{--format=posix}
(@option{--format=pax}) option. No
+../tar_texi/tar.texi(,8355) special option is required to read and extract
from a @acronym{POSIX}
+../tar_texi/tar.texi(,8356) archive.
+../tar_texi/tar.texi(,8357)
+../tar_texi/tar.texi(,8358) @menu
+../tar_texi/tar.texi(,8359) * PAX keywords:: Controlling Extended Header
Keywords.
+../tar_texi/tar.texi(,8360) @end menu
+../tar_texi/tar.texi(,8361)
+../tar_texi/tar.texi(,8362) @node PAX keywords
+../tar_texi/tar.texi(,8363) @subsubsection Controlling Extended Header Keywords
+../tar_texi/tar.texi(,8364)
+../tar_texi/tar.texi(,8365) @table @option
+../tar_texi/tar.texi(,8366) @opindex pax-option
+../tar_texi/tar.texi(,8367) @item address@hidden
+../tar_texi/tar.texi(,8368) Handle keywords in @acronym{PAX} extended headers.
This option is
+../tar_texi/tar.texi(,8369) equivalent to @option{-o} option of the
@command{pax} utility.
+../tar_texi/tar.texi(,8370) @end table
+../tar_texi/tar.texi(,8371)
+../tar_texi/tar.texi(,8372) @var{Keyword-list} is a comma-separated
+../tar_texi/tar.texi(,8373) list of keyword options, each keyword option
taking one of
+../tar_texi/tar.texi(,8374) the following forms:
+../tar_texi/tar.texi(,8375)
+../tar_texi/tar.texi(,8376) @table @code
+../tar_texi/tar.texi(,8377) @item address@hidden
+../tar_texi/tar.texi(,8378) When used with one of archive-creation commands,
+../tar_texi/tar.texi(,8379) this option instructs @command{tar} to omit from
extended header records
+../tar_texi/tar.texi(,8380) that it produces any keywords matching the string
@var{pattern}.
+../tar_texi/tar.texi(,8381)
+../tar_texi/tar.texi(,8382) When used in extract or list mode, this option
instructs tar
+../tar_texi/tar.texi(,8383) to ignore any keywords matching the given
@var{pattern} in the extended
+../tar_texi/tar.texi(,8384) header records. In both cases, matching is
performed using the pattern
+../tar_texi/tar.texi(,8385) matching notation described in @acronym{POSIX
1003.2}, 3.13
+../tar_texi/tar.texi(,8386) (@pxref{wildcards}). For example:
+../tar_texi/tar.texi(,8387)
+../tar_texi/tar.texi(,8388) @smallexample
+../tar_texi/tar.texi(,8389) --pax-option delete=security.*
+../tar_texi/tar.texi(,8390) @end smallexample
+../tar_texi/tar.texi(,8391)
+../tar_texi/tar.texi(,8392) would suppress security-related information.
+../tar_texi/tar.texi(,8393)
+../tar_texi/tar.texi(,8394) @item address@hidden
+../tar_texi/tar.texi(,8395)
+../tar_texi/tar.texi(,8396) This keyword allows user control over the name
that is written into the
+../tar_texi/tar.texi(,8397) ustar header blocks for the extended headers. The
name is obtained
+../tar_texi/tar.texi(,8398) from @var{string} after making the following
substitutions:
+../tar_texi/tar.texi(,8399)
+../tar_texi/tar.texi(,8400) @multitable @columnfractions .25 .55
+../tar_texi/tar.texi(,8401) @headitem Meta-character @tab Replaced By
+../tar_texi/tar.texi(,8402) @item %d @tab The directory name of the file,
equivalent to the
+../tar_texi/tar.texi(,8403) result of the @command{dirname} utility on the
translated pathname.
+../tar_texi/tar.texi(,8404) @item %f @tab The filename of the file,
equivalent to the result
+../tar_texi/tar.texi(,8405) of the @command{basename} utility on the
translated pathname.
+../tar_texi/tar.texi(,8406) @item %p @tab The process ID of the @command{tar}
process.
+../tar_texi/tar.texi(,8407) @item %% @tab A @samp{%} character.
+../tar_texi/tar.texi(,8408) @end multitable
+../tar_texi/tar.texi(,8409)
+../tar_texi/tar.texi(,8410) Any other @samp{%} characters in @var{string}
produce undefined
+../tar_texi/tar.texi(,8411) results.
+../tar_texi/tar.texi(,8412)
+../tar_texi/tar.texi(,8413) If no option @samp{exthdr.name=string} is
specified, @command{tar}
+../tar_texi/tar.texi(,8414) will use the following default value:
+../tar_texi/tar.texi(,8415)
+../tar_texi/tar.texi(,8416) @smallexample
+../tar_texi/tar.texi(,8417) %d/PaxHeaders.%p/%f
+../tar_texi/tar.texi(,8418) @end smallexample
+../tar_texi/tar.texi(,8419)
+../tar_texi/tar.texi(,8420) @item address@hidden
+../tar_texi/tar.texi(,8421) This keyword allows user control over the name
that is written into
+../tar_texi/tar.texi(,8422) the ustar header blocks for global extended header
records. The name
+../tar_texi/tar.texi(,8423) is obtained from the contents of @var{string},
after making
+../tar_texi/tar.texi(,8424) the following substitutions:
+../tar_texi/tar.texi(,8425)
+../tar_texi/tar.texi(,8426) @multitable @columnfractions .25 .55
+../tar_texi/tar.texi(,8427) @headitem Meta-character @tab Replaced By
+../tar_texi/tar.texi(,8428) @item %n @tab An integer that represents the
+../tar_texi/tar.texi(,8429) sequence number of the global extended header
record in the archive,
+../tar_texi/tar.texi(,8430) starting at 1.
+../tar_texi/tar.texi(,8431) @item %p @tab The process ID of the @command{tar}
process.
+../tar_texi/tar.texi(,8432) @item %% @tab A @samp{%} character.
+../tar_texi/tar.texi(,8433) @end multitable
+../tar_texi/tar.texi(,8434)
+../tar_texi/tar.texi(,8435) Any other @samp{%} characters in @var{string}
produce undefined results.
+../tar_texi/tar.texi(,8436)
+../tar_texi/tar.texi(,8437) If no option @samp{globexthdr.name=string} is
specified, @command{tar}
+../tar_texi/tar.texi(,8438) will use the following default value:
+../tar_texi/tar.texi(,8439)
+../tar_texi/tar.texi(,8440) @smallexample
+../tar_texi/tar.texi(,8441) $TMPDIR/GlobalHead.%p.%n
+../tar_texi/tar.texi(,8442) @end smallexample
+../tar_texi/tar.texi(,8443)
+../tar_texi/tar.texi(,8444) @noindent
+../tar_texi/tar.texi(,8445) where @samp{$TMPDIR} represents the value of the
@var{TMPDIR}
+../tar_texi/tar.texi(,8446) environment variable. If @var{TMPDIR} is not set,
@command{tar}
+../tar_texi/tar.texi(,8447) uses @samp{/tmp}.
+../tar_texi/tar.texi(,8448)
+../tar_texi/tar.texi(,8449) @item @address@hidden
+../tar_texi/tar.texi(,8450) When used with one of archive-creation commands,
these keyword/value pairs
+../tar_texi/tar.texi(,8451) will be included at the beginning of the archive
in a global extended
+../tar_texi/tar.texi(,8452) header record. When used with one of
archive-reading commands,
+../tar_texi/tar.texi(,8453) @command{tar} will behave as if it has encountered
these keyword/value
+../tar_texi/tar.texi(,8454) pairs at the beginning of the archive in a global
extended header
+../tar_texi/tar.texi(,8455) record.
+../tar_texi/tar.texi(,8456)
+../tar_texi/tar.texi(,8457) @item @var{keyword}:address@hidden
+../tar_texi/tar.texi(,8458) When used with one of archive-creation commands,
these keyword/value pairs
+../tar_texi/tar.texi(,8459) will be included as records at the beginning of an
extended header for
+../tar_texi/tar.texi(,8460) each file. This is effectively equivalent to
@address@hidden
+../tar_texi/tar.texi(,8461) form except that it creates no global extended
header records.
+../tar_texi/tar.texi(,8462)
+../tar_texi/tar.texi(,8463) When used with one of archive-reading commands,
@command{tar} will
+../tar_texi/tar.texi(,8464) behave as if these keyword/value pairs were
included as records at the
+../tar_texi/tar.texi(,8465) end of each extended header; thus, they will
override any global or
+../tar_texi/tar.texi(,8466) file-specific extended header record keywords of
the same names.
+../tar_texi/tar.texi(,8467) For example, in the command:
+../tar_texi/tar.texi(,8468)
+../tar_texi/tar.texi(,8469) @smallexample
+../tar_texi/tar.texi(,8470) tar --format=posix --create \
+../tar_texi/tar.texi(,8471) --file archive --pax-option gname:=user .
+../tar_texi/tar.texi(,8472) @end smallexample
+../tar_texi/tar.texi(,8473)
+../tar_texi/tar.texi(,8474) the group name will be forced to a new value for
all files
+../tar_texi/tar.texi(,8475) stored in the archive.
+../tar_texi/tar.texi(,8476) @end table
+../tar_texi/tar.texi(,8477)
+../tar_texi/tar.texi(,8478) @node Checksumming
+../tar_texi/tar.texi(,8479) @subsection Checksumming Problems
+../tar_texi/tar.texi(,8480)
+../tar_texi/tar.texi(,8481) SunOS and HP-UX @command{tar} fail to accept
archives created using
+../tar_texi/tar.texi(GNUTAR,8482) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8482) and containing non-ASCII file
names, that
+../tar_texi/tar.texi(,8483) is, file names having characters with the eight
bit set, because they
+../tar_texi/tar.texi(GNUTAR,8484) use signed checksums, while
../tar_texi/tar.texi(GNUTAR,8484) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8484) uses unsigned
+../tar_texi/tar.texi(,8485) checksums while creating archives, as per
@acronym{POSIX} standards. On
+../tar_texi/tar.texi(GNUTAR,8486) reading, ../tar_texi/tar.texi(GNUTAR,8486)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,8486) computes both
checksums and
+../tar_texi/tar.texi(,8487) accept any. It is somewhat worrying that a lot of
people may go
+../tar_texi/tar.texi(,8488) around doing backup of their files using faulty
(or at least
+../tar_texi/tar.texi(,8489) non-standard) software, not learning about it
until it's time to
+../tar_texi/tar.texi(,8490) restore their missing files with an incompatible
file extractor, or
+../tar_texi/tar.texi(,8491) vice versa.
+../tar_texi/tar.texi(,8492)
+../tar_texi/tar.texi(GNUTAR,8493) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8493) compute checksums both ways,
and accept
+../tar_texi/tar.texi(,8494) any on read, so @acronym{GNU} tar can read Sun
tapes even with their
+../tar_texi/tar.texi(GNUTAR,8495) wrong checksums.
../tar_texi/tar.texi(GNUTAR,8495) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8495) produces the standard
+../tar_texi/tar.texi(,8496) checksum, however, raising incompatibilities with
Sun. That is to
+../tar_texi/tar.texi(GNUTAR,8497) say, ../tar_texi/tar.texi(GNUTAR,8497)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,8497) has not been
modified to
+../tar_texi/tar.texi(,8498) @emph{produce} incorrect archives to be read by
buggy @command{tar}'s.
+../tar_texi/tar.texi(,8499) I've been told that more recent Sun @command{tar}
now read standard
+../tar_texi/tar.texi(,8500) archives, so maybe Sun did a similar patch, after
all?
+../tar_texi/tar.texi(,8501)
+../tar_texi/tar.texi(,8502) The story seems to be that when Sun first imported
@command{tar}
+../tar_texi/tar.texi(,8503) sources on their system, they recompiled it
without realizing that
+../tar_texi/tar.texi(,8504) the checksums were computed differently, because
of a change in
+../tar_texi/tar.texi(,8505) the default signing of @code{char}'s in their
compiler. So they
+../tar_texi/tar.texi(,8506) started computing checksums wrongly. When they
later realized their
+../tar_texi/tar.texi(,8507) mistake, they merely decided to stay compatible
with it, and with
+../tar_texi/tar.texi(,8508) themselves afterwards. Presumably, but I do not
really know, HP-UX
+../tar_texi/tar.texi(,8509) has chosen that their @command{tar} archives to be
compatible with Sun's.
+../tar_texi/tar.texi(,8510) The current standards do not favor Sun
@command{tar} format. In any
+../tar_texi/tar.texi(,8511) case, it now falls on the shoulders of SunOS and
HP-UX users to get
+../tar_texi/tar.texi(,8512) a @command{tar} able to read the good archives
they receive.
+../tar_texi/tar.texi(,8513)
+../tar_texi/tar.texi(,8514) @node Large or Negative Values
+../tar_texi/tar.texi(,8515) @subsection Large or Negative Values
+../tar_texi/tar.texi(,8516) @cindex large values
+../tar_texi/tar.texi(,8517) @cindex future time stamps
+../tar_texi/tar.texi(,8518) @cindex negative time stamps
+../tar_texi/tar.texi(UNREVISED,8519) @quotation
+../tar_texi/tar.texi(UNREVISED,8519) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,8519) @end quotation
+../tar_texi/tar.texi(UNREVISED,8519)
+../tar_texi/tar.texi(,8520)
+../tar_texi/tar.texi(,8521) The above sections suggest to use @samp{oldest
possible} archive
+../tar_texi/tar.texi(,8522) format if in doubt. However, sometimes it is not
possible. If you
+../tar_texi/tar.texi(,8523) attempt to archive a file whose metadata cannot be
represented using
+../tar_texi/tar.texi(GNUTAR,8524) required format,
../tar_texi/tar.texi(GNUTAR,8524) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8524) will print error message and
ignore such a
+../tar_texi/tar.texi(,8525) file. You will than have to switch to a format
that is able to
+../tar_texi/tar.texi(,8526) handle such values. The format summary table
(@pxref{Formats}) will
+../tar_texi/tar.texi(,8527) help you to do so.
+../tar_texi/tar.texi(,8528)
+../tar_texi/tar.texi(,8529) In particular, when trying to archive files larger
than 8GB or with
+../tar_texi/tar.texi(,8530) timestamps not in the range 1970-01-01 00:00:00
through 2242-03-16
+../tar_texi/tar.texi(,8531) 12:56:31 @sc{utc}, you will have to chose between
@acronym{GNU} and
+../tar_texi/tar.texi(,8532) @acronym{POSIX} archive formats. When considering
which format to
+../tar_texi/tar.texi(,8533) choose, bear in mind that the @acronym{GNU} format
uses
+../tar_texi/tar.texi(,8534) two's-complement base-256 notation to store values
that do not fit
+../tar_texi/tar.texi(,8535) into standard @acronym{ustar} range. Such
archives can generally be
+../tar_texi/tar.texi(GNUTAR,8536) read only by a
../tar_texi/tar.texi(GNUTAR,8536) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8536) implementation. Moreover, they
sometimes
+../tar_texi/tar.texi(GNUTAR,8537) cannot be correctly restored on another
hosts even by ../tar_texi/tar.texi(GNUTAR,8537) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8537) . For
+../tar_texi/tar.texi(,8538) example, using two's complement representation for
negative time
+../tar_texi/tar.texi(,8539) stamps that assumes a signed 32-bit @code{time_t}
generates archives
+../tar_texi/tar.texi(,8540) that are not portable to hosts with differing
@code{time_t}
+../tar_texi/tar.texi(,8541) representations.
+../tar_texi/tar.texi(,8542)
+../tar_texi/tar.texi(,8543) On the other hand, @acronym{POSIX} archives,
generally speaking, can
+../tar_texi/tar.texi(,8544) be extracted by any tar implementation that
understands older
+../tar_texi/tar.texi(,8545) @acronym{ustar} format. The only exception are
files larger than 8GB.
+../tar_texi/tar.texi(,8546)
+../tar_texi/tar.texi(FIXME,8548) @allow-recursion
+../tar_texi/tar.texi(FIXME,8548) @quote-arg
+../tar_texi/tar.texi(FIXME,8548)
+../tar_texi/tar.texi(,8549)
+../tar_texi/tar.texi(,8550) @node Other Tars
+../tar_texi/tar.texi(,8551) @subsection How to Extract GNU-Specific Data Using
Other @command{tar} Implementations
+../tar_texi/tar.texi(,8552)
+../tar_texi/tar.texi(,8553) In previous sections you became acquainted with
various quircks
+../tar_texi/tar.texi(,8554) necessary to make your archives portable.
Sometimes you may need to
+../tar_texi/tar.texi(,8555) extract archives containing GNU-specific members
using some
+../tar_texi/tar.texi(,8556) third-party @command{tar} implementation or an
older version of
+../tar_texi/tar.texi(GNUTAR,8557) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8557) . Of course your best bet is to
have ../tar_texi/tar.texi(GNUTAR,8557) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8557) installed,
+../tar_texi/tar.texi(,8558) but if it is for some reason impossible, this
section will explain
+../tar_texi/tar.texi(,8559) how to cope without it.
+../tar_texi/tar.texi(,8560)
+../tar_texi/tar.texi(,8561) When we speak about @dfn{GNU-specific} members we
mean two classes of
+../tar_texi/tar.texi(,8562) them: members split between the volumes of a
multi-volume archive and
+../tar_texi/tar.texi(,8563) sparse members. You will be able to always
recover such members if
+../tar_texi/tar.texi(,8564) the archive is in PAX format. In addition split
members can be
+../tar_texi/tar.texi(,8565) recovered from archives in old GNU format. The
following subsections
+../tar_texi/tar.texi(,8566) describe the required procedures in detail.
+../tar_texi/tar.texi(,8567)
+../tar_texi/tar.texi(,8568) @menu
+../tar_texi/tar.texi(,8569) * Split Recovery:: Members Split Between
Volumes
+../tar_texi/tar.texi(,8570) * Sparse Recovery:: Sparse Members
+../tar_texi/tar.texi(,8571) @end menu
+../tar_texi/tar.texi(,8572)
+../tar_texi/tar.texi(,8573) @node Split Recovery
+../tar_texi/tar.texi(,8574) @subsubsection Extracting Members Split Between
Volumes
+../tar_texi/tar.texi(,8575)
+../tar_texi/tar.texi(,8576) @cindex Mutli-volume archives, extracting using
non-GNU tars
+../tar_texi/tar.texi(,8577) If a member is split between several volumes of an
old GNU format archive
+../tar_texi/tar.texi(,8578) most third party @command{tar} implementation will
fail to extract
+../tar_texi/tar.texi(,8579) it. To extract it, use @command{tarcat} program
(@pxref{Tarcat}).
+../tar_texi/tar.texi(,8580) This program is available from
+../tar_texi/tar.texi(GNUTAR,8581)
@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @acronym{GNU}
@command{tar}
+../tar_texi/tar.texi(,8582) home page}. It concatenates several archive
volumes into a single
+../tar_texi/tar.texi(,8583) valid archive. For example, if you have three
volumes named from
+../tar_texi/tar.texi(,8584) @file{vol-1.tar} to @file{vol-2.tar}, you can do
the following to
+../tar_texi/tar.texi(,8585) extract them using a third-party @command{tar}:
+../tar_texi/tar.texi(,8586)
+../tar_texi/tar.texi(,8587) @smallexample
+../tar_texi/tar.texi(,8588) $ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar
xf -}
+../tar_texi/tar.texi(,8589) @end smallexample
+../tar_texi/tar.texi(,8590)
+../tar_texi/tar.texi(,8591) @cindex Mutli-volume archives in PAX format,
extracting using non-GNU tars
+../tar_texi/tar.texi(,8592) You could use this approach for many (although not
all) PAX
+../tar_texi/tar.texi(,8593) format archives as well. However, extracting
split members from a PAX
+../tar_texi/tar.texi(,8594) archive is a much easier task, because PAX volumes
are constructed in
+../tar_texi/tar.texi(,8595) such a way that each part of a split member is
extracted as a
+../tar_texi/tar.texi(,8596) different file by @command{tar} implementations
that are not aware of
+../tar_texi/tar.texi(,8597) GNU extensions. More specifically, the very first
part retains its
+../tar_texi/tar.texi(,8598) original name, and all subsequent parts are named
using the pattern:
+../tar_texi/tar.texi(,8599)
+../tar_texi/tar.texi(,8600) @smallexample
+../tar_texi/tar.texi(,8601) %d/GNUFileParts.%p/%f.%n
+../tar_texi/tar.texi(,8602) @end smallexample
+../tar_texi/tar.texi(,8603)
+../tar_texi/tar.texi(,8604) @noindent
+../tar_texi/tar.texi(,8605) where symbols preceeded by @samp{%} are @dfn{macro
characters} that
+../tar_texi/tar.texi(,8606) have the following meaning:
+../tar_texi/tar.texi(,8607)
+../tar_texi/tar.texi(,8608) @multitable @columnfractions .25 .55
+../tar_texi/tar.texi(,8609) @headitem Meta-character @tab Replaced By
+../tar_texi/tar.texi(,8610) @item %d @tab The directory name of the file,
equivalent to the
+../tar_texi/tar.texi(,8611) result of the @command{dirname} utility on its
full name.
+../tar_texi/tar.texi(,8612) @item %f @tab The file name of the file,
equivalent to the result
+../tar_texi/tar.texi(,8613) of the @command{basename} utility on its full name.
+../tar_texi/tar.texi(,8614) @item %p @tab The process ID of the @command{tar}
process that
+../tar_texi/tar.texi(,8615) created the archive.
+../tar_texi/tar.texi(,8616) @item %n @tab Ordinal number of this particular
part.
+../tar_texi/tar.texi(,8617) @end multitable
+../tar_texi/tar.texi(,8618)
+../tar_texi/tar.texi(,8619) For example, if, a file @file{var/longfile} was
split during archive
+../tar_texi/tar.texi(,8620) creation between three volumes, and the creator
@command{tar} process
+../tar_texi/tar.texi(,8621) had process ID @samp{27962}, then the member names
will be:
+../tar_texi/tar.texi(,8622)
+../tar_texi/tar.texi(,8623) @smallexample
+../tar_texi/tar.texi(,8624) var/longfile
+../tar_texi/tar.texi(,8625) var/GNUFileParts.27962/longfile.1
+../tar_texi/tar.texi(,8626) var/GNUFileParts.27962/longfile.2
+../tar_texi/tar.texi(,8627) @end smallexample
+../tar_texi/tar.texi(,8628)
+../tar_texi/tar.texi(,8629) When you extract your archive using a third-party
@command{tar}, these
+../tar_texi/tar.texi(,8630) files will be created on your disk, and the only
thing you will need
+../tar_texi/tar.texi(,8631) to do to restore your file in its original form is
concatenate them in
+../tar_texi/tar.texi(,8632) the proper order, for example:
+../tar_texi/tar.texi(,8633)
+../tar_texi/tar.texi(,8634) @smallexample
+../tar_texi/tar.texi(,8635) @group
+../tar_texi/tar.texi(,8636) $ @kbd{cd var}
+../tar_texi/tar.texi(,8637) $ @kbd{cat GNUFileParts.27962/longfile.1 \
+../tar_texi/tar.texi(,8638) GNUFileParts.27962/longfile.2 >> longfile}
+../tar_texi/tar.texi(,8639) $ rm -f GNUFileParts.27962
+../tar_texi/tar.texi(,8640) @end group
+../tar_texi/tar.texi(,8641) @end smallexample
+../tar_texi/tar.texi(,8642)
+../tar_texi/tar.texi(,8643) Notice, that if the @command{tar} implementation
you use supports PAX
+../tar_texi/tar.texi(,8644) format archives, it will probably emit warnings
about unknown keywords
+../tar_texi/tar.texi(,8645) during extraction. They will lool like this:
+../tar_texi/tar.texi(,8646)
+../tar_texi/tar.texi(,8647) @smallexample
+../tar_texi/tar.texi(,8648) @group
+../tar_texi/tar.texi(,8649) Tar file too small
+../tar_texi/tar.texi(,8650) Unknown extended header keyword
'GNU.volume.filename' ignored.
+../tar_texi/tar.texi(,8651) Unknown extended header keyword 'GNU.volume.size'
ignored.
+../tar_texi/tar.texi(,8652) Unknown extended header keyword
'GNU.volume.offset' ignored.
+../tar_texi/tar.texi(,8653) @end group
+../tar_texi/tar.texi(,8654) @end smallexample
+../tar_texi/tar.texi(,8655)
+../tar_texi/tar.texi(,8656) @noindent
+../tar_texi/tar.texi(,8657) You can safely ignore these warnings.
+../tar_texi/tar.texi(,8658)
+../tar_texi/tar.texi(,8659) If your @command{tar} implementation is not
PAX-aware, you will get
+../tar_texi/tar.texi(,8660) more warnigns and more files generated on your
disk, e.g.:
+../tar_texi/tar.texi(,8661)
+../tar_texi/tar.texi(,8662) @smallexample
+../tar_texi/tar.texi(,8663) @group
+../tar_texi/tar.texi(,8664) $ @kbd{tar xf vol-1.tar}
+../tar_texi/tar.texi(,8665) var/PaxHeaders.27962/longfile: Unknown file type
'x', extracted as
+../tar_texi/tar.texi(,8666) normal file
+../tar_texi/tar.texi(,8667) Unexpected EOF in archive
+../tar_texi/tar.texi(,8668) $ @kbd{tar xf vol-2.tar}
+../tar_texi/tar.texi(,8669) tmp/GlobalHead.27962.1: Unknown file type 'g',
extracted as normal file
+../tar_texi/tar.texi(,8670) GNUFileParts.27962/PaxHeaders.27962/sparsefile.1:
Unknown file type
+../tar_texi/tar.texi(,8671) 'x', extracted as normal file
+../tar_texi/tar.texi(,8672) @end group
+../tar_texi/tar.texi(,8673) @end smallexample
+../tar_texi/tar.texi(,8674)
+../tar_texi/tar.texi(,8675) Ignore these warnings. The @file{PaxHeaders.*}
directories created
+../tar_texi/tar.texi(,8676) will contain files with @dfn{extended header
keywords} describing the
+../tar_texi/tar.texi(,8677) extracted files. You can delete them, unless they
describe sparse
+../tar_texi/tar.texi(,8678) members. Read further to learn more about them.
+../tar_texi/tar.texi(,8679)
+../tar_texi/tar.texi(,8680) @node Sparse Recovery
+../tar_texi/tar.texi(,8681) @subsubsection Extracting Sparse Members
+../tar_texi/tar.texi(,8682)
+../tar_texi/tar.texi(,8683) @cindex sparse files, extracting with non-GNU tars
+../tar_texi/tar.texi(,8684) Any @command{tar} implementation will be able to
extract sparse members from a
+../tar_texi/tar.texi(,8685) PAX archive. However, the extracted files will be
@dfn{condensed},
+../tar_texi/tar.texi(,8686) i.e. any zero blocks will be removed from them.
When we restore such
+../tar_texi/tar.texi(,8687) a condensed file to its original form, by adding
zero bloks (or
+../tar_texi/tar.texi(,8688) @dfn{holes}) back to their original locations, we
call this process
+../tar_texi/tar.texi(,8689) @dfn{expanding} a compressed sparse file.
+../tar_texi/tar.texi(,8690)
+../tar_texi/tar.texi(,8691) @pindex xsparse
+../tar_texi/tar.texi(,8692) To expand a file, you will need a simple auxiliary
program called
+../tar_texi/tar.texi(,8693) @command{xsparse}. It is available in source form
from
+../tar_texi/tar.texi(GNUTAR,8694)
@uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @acronym{GNU}
@command{tar}
+../tar_texi/tar.texi(,8695) home page}.
+../tar_texi/tar.texi(,8696)
+../tar_texi/tar.texi(,8697) @cindex sparse files v.1.0, extracting with
non-GNU tars
+../tar_texi/tar.texi(,8698) Let's begin with archive members in @dfn{sparse
format
+../tar_texi/tar.texi(,8699) version address@hidden@xref{PAX 1}.}, which are
the easiest to expand.
+../tar_texi/tar.texi(,8700) The condensed file will contain both file map and
file data, so no
+../tar_texi/tar.texi(,8701) additional data will be needed to restore it. If
the original file
+../tar_texi/tar.texi(,8702) name was @address@hidden/@var{name}}, then the
condensed file will be
+../tar_texi/tar.texi(,8703) named
@address@hidden/@/address@hidden/@/@var{name}}, where
+../tar_texi/tar.texi(,8704) @var{n} is a decimal address@hidden speaking,
@var{n} is a
+../tar_texi/tar.texi(,8705) @dfn{process ID} of the @command{tar} process
which created the
+../tar_texi/tar.texi(,8706) archive (@pxref{PAX keywords}).}.
+../tar_texi/tar.texi(,8707)
+../tar_texi/tar.texi(,8708) To expand a version 1.0 file, run
@command{xsparse} as follows:
+../tar_texi/tar.texi(,8709)
+../tar_texi/tar.texi(,8710) @smallexample
+../tar_texi/tar.texi(,8711) $ @kbd{xsparse @file{cond-file}}
+../tar_texi/tar.texi(,8712) @end smallexample
+../tar_texi/tar.texi(,8713)
+../tar_texi/tar.texi(,8714) @noindent
+../tar_texi/tar.texi(,8715) where @file{cond-file} is the name of the
condensed file. The utility
+../tar_texi/tar.texi(,8716) will deduce the name for the resulting expanded
file using the
+../tar_texi/tar.texi(,8717) following algorithm:
+../tar_texi/tar.texi(,8718)
+../tar_texi/tar.texi(,8719) @enumerate 1
+../tar_texi/tar.texi(,8720) @item If @file{cond-file} does not contain any
directories,
+../tar_texi/tar.texi(,8721) @file{../cond-file} will be used;
+../tar_texi/tar.texi(,8722)
+../tar_texi/tar.texi(,8723) @item If @file{cond-file} has the form
+../tar_texi/tar.texi(,8724) @address@hidden/@var{t}/@var{name}}, where both
@var{t} and @var{name}
+../tar_texi/tar.texi(,8725) are simple names, with no @samp{/} characters in
them, the output file
+../tar_texi/tar.texi(,8726) name will be @address@hidden/@var{name}}.
+../tar_texi/tar.texi(,8727)
+../tar_texi/tar.texi(,8728) @item Otherwise, if @file{cond-file} has the form
+../tar_texi/tar.texi(,8729) @address@hidden/@var{name}}, the output file name
will be
+../tar_texi/tar.texi(,8730) @address@hidden
+../tar_texi/tar.texi(,8731) @end enumerate
+../tar_texi/tar.texi(,8732)
+../tar_texi/tar.texi(,8733) In the unlikely case when this algorithm does not
suite your needs,
+../tar_texi/tar.texi(,8734) you can explicitely specify output file name as a
second argument to
+../tar_texi/tar.texi(,8735) the command:
+../tar_texi/tar.texi(,8736)
+../tar_texi/tar.texi(,8737) @smallexample
+../tar_texi/tar.texi(,8738) $ @kbd{xsparse @file{cond-file}}
+../tar_texi/tar.texi(,8739) @end smallexample
+../tar_texi/tar.texi(,8740)
+../tar_texi/tar.texi(,8741) It is often a good idea to run @command{xsparse}
in @dfn{dry run} mode
+../tar_texi/tar.texi(,8742) first. In this mode, the command does not
actually expand the file,
+../tar_texi/tar.texi(,8743) but verbosely lists all actions it would be taking
to do so. The dry
+../tar_texi/tar.texi(,8744) run mode is enabled by @option{-n} command line
argument:
+../tar_texi/tar.texi(,8745)
+../tar_texi/tar.texi(,8746) @smallexample
+../tar_texi/tar.texi(,8747) @group
+../tar_texi/tar.texi(,8748) $ @kbd{xsparse -n
/home/gray/GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8749) Reading v.1.0 sparse map
+../tar_texi/tar.texi(,8750) Expanding file
`/home/gray/GNUSparseFile.6058/sparsefile' to
+../tar_texi/tar.texi(,8751) `/home/gray/sparsefile'
+../tar_texi/tar.texi(,8752) Finished dry run
+../tar_texi/tar.texi(,8753) @end group
+../tar_texi/tar.texi(,8754) @end smallexample
+../tar_texi/tar.texi(,8755)
+../tar_texi/tar.texi(,8756) To actually expand the file, you would run:
+../tar_texi/tar.texi(,8757)
+../tar_texi/tar.texi(,8758) @smallexample
+../tar_texi/tar.texi(,8759) $ @kbd{xsparse
/home/gray/GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8760) @end smallexample
+../tar_texi/tar.texi(,8761)
+../tar_texi/tar.texi(,8762) @noindent
+../tar_texi/tar.texi(,8763) The program behaves the same way all UNIX
utilities do: it will keep
+../tar_texi/tar.texi(,8764) quiet unless it has simething important to tell
you (e.g. an error
+../tar_texi/tar.texi(,8765) condition or something). If you wish it to
produce verbose output,
+../tar_texi/tar.texi(,8766) similar to that from the dry run mode, give it
@option{-v} option:
+../tar_texi/tar.texi(,8767)
+../tar_texi/tar.texi(,8768) @smallexample
+../tar_texi/tar.texi(,8769) @group
+../tar_texi/tar.texi(,8770) $ @kbd{xsparse -v
/home/gray/GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8771) Reading v.1.0 sparse map
+../tar_texi/tar.texi(,8772) Expanding file
`/home/gray/GNUSparseFile.6058/sparsefile' to
+../tar_texi/tar.texi(,8773) `/home/gray/sparsefile'
+../tar_texi/tar.texi(,8774) Done
+../tar_texi/tar.texi(,8775) @end group
+../tar_texi/tar.texi(,8776) @end smallexample
+../tar_texi/tar.texi(,8777)
+../tar_texi/tar.texi(,8778) Additionally, if your @command{tar} implementation
has extracted the
+../tar_texi/tar.texi(,8779) @dfn{extended headers} for this file, you can
instruct @command{xstar}
+../tar_texi/tar.texi(,8780) to use them in order to verify the integrity of
the expanded file.
+../tar_texi/tar.texi(,8781) The option @option{-x} sets the name of the
extended header file to
+../tar_texi/tar.texi(,8782) use. Continuing our example:
+../tar_texi/tar.texi(,8783)
+../tar_texi/tar.texi(,8784) @smallexample
+../tar_texi/tar.texi(,8785) @group
+../tar_texi/tar.texi(,8786) $ @kbd{xsparse -v -x
/home/gray/PaxHeaders.6058/sparsefile \
+../tar_texi/tar.texi(,8787) /home/gray/GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8788) Reading extended header file
+../tar_texi/tar.texi(,8789) Found variable GNU.sparse.major = 1
+../tar_texi/tar.texi(,8790) Found variable GNU.sparse.minor = 0
+../tar_texi/tar.texi(,8791) Found variable GNU.sparse.name = sparsefile
+../tar_texi/tar.texi(,8792) Found variable GNU.sparse.realsize = 217481216
+../tar_texi/tar.texi(,8793) Reading v.1.0 sparse map
+../tar_texi/tar.texi(,8794) Expanding file
`/home/gray/GNUSparseFile.6058/sparsefile' to
+../tar_texi/tar.texi(,8795) `/home/gray/sparsefile'
+../tar_texi/tar.texi(,8796) Done
+../tar_texi/tar.texi(,8797) @end group
+../tar_texi/tar.texi(,8798) @end smallexample
+../tar_texi/tar.texi(,8799)
+../tar_texi/tar.texi(,8800) @anchor{extracting sparse v.0.x}
+../tar_texi/tar.texi(,8801) @cindex sparse files v.0.1, extracting with
non-GNU tars
+../tar_texi/tar.texi(,8802) @cindex sparse files v.0.0, extracting with
non-GNU tars
+../tar_texi/tar.texi(,8803) An @dfn{extended header} is a special
@command{tar} archive header
+../tar_texi/tar.texi(,8804) that precedes an archive member and contains a set
of
+../tar_texi/tar.texi(,8805) @dfn{variables}, describing the member properties
that cannot be
+../tar_texi/tar.texi(,8806) stored in the standard @code{ustar} header. While
optional for
+../tar_texi/tar.texi(,8807) expanding sparse version 1.0 members, use of
extended headers is
+../tar_texi/tar.texi(,8808) mandatory when expanding sparse members in older
sparse formats: v.0.0
+../tar_texi/tar.texi(,8809) and v.0.1 (The sparse formats are described in
detail in @pxref{Sparse
+../tar_texi/tar.texi(,8810) Formats}). So, for this format, the question is:
how to obtain
+../tar_texi/tar.texi(,8811) extended headers from the archive?
+../tar_texi/tar.texi(,8812)
+../tar_texi/tar.texi(,8813) If you use a @command{tar} implementation that
does not support PAX
+../tar_texi/tar.texi(,8814) format, extended headers for each member will be
extracted as a
+../tar_texi/tar.texi(,8815) separate file. If we represent the member name as
+../tar_texi/tar.texi(,8816) @address@hidden/@var{name}}, then the extended
header file will be
+../tar_texi/tar.texi(,8817) named
@address@hidden/@/address@hidden/@/@var{name}}, where
+../tar_texi/tar.texi(,8818) @var{n} is an integer number.
+../tar_texi/tar.texi(,8819)
+../tar_texi/tar.texi(,8820) Things become more difficult if your @command{tar}
implementation
+../tar_texi/tar.texi(,8821) does support PAX headers, because in this case you
will have to
+../tar_texi/tar.texi(,8822) manually extract the headers. We recommend the
following algorithm:
+../tar_texi/tar.texi(,8823)
+../tar_texi/tar.texi(,8824) @enumerate 1
+../tar_texi/tar.texi(,8825) @item
+../tar_texi/tar.texi(,8826) Consult the documentation for your @command{tar}
implementation for an
+../tar_texi/tar.texi(,8827) option that will print @dfn{block numbers} along
with the archive
+../tar_texi/tar.texi(GNUTAR,8828) listing (analogous to
../tar_texi/tar.texi(GNUTAR,8828) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,8828) 's @option{-R} option). For
example,
+../tar_texi/tar.texi(,8829) @command{star} has @option{-block-number}.
+../tar_texi/tar.texi(,8830)
+../tar_texi/tar.texi(,8831) @item
+../tar_texi/tar.texi(,8832) Obtain the verbose listing using the @samp{block
number} option, and
+../tar_texi/tar.texi(,8833) find the position of the sparse member in question
and the member
+../tar_texi/tar.texi(,8834) immediately following it. For example, running
@command{star} on our
+../tar_texi/tar.texi(,8835) archive we obtain:
+../tar_texi/tar.texi(,8836)
+../tar_texi/tar.texi(,8837) @smallexample
+../tar_texi/tar.texi(,8838) @group
+../tar_texi/tar.texi(,8839) $ @kbd{star -t -v -block-number -f arc.tar}
+../tar_texi/tar.texi(,8840) @dots{}
+../tar_texi/tar.texi(,8841) star: Unknown extended header keyword
'GNU.sparse.size' ignored.
+../tar_texi/tar.texi(,8842) star: Unknown extended header keyword
'GNU.sparse.numblocks' ignored.
+../tar_texi/tar.texi(,8843) star: Unknown extended header keyword
'GNU.sparse.name' ignored.
+../tar_texi/tar.texi(,8844) star: Unknown extended header keyword
'GNU.sparse.map' ignored.
+../tar_texi/tar.texi(,8845) block 56: 425984 -rw-r--r-- gray/users
Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
+../tar_texi/tar.texi(,8846) block 897: 65391 -rw-r--r-- gray/users
Jun 24 20:06 2006 README
+../tar_texi/tar.texi(,8847) @dots{}
+../tar_texi/tar.texi(,8848) @end group
+../tar_texi/tar.texi(,8849) @end smallexample
+../tar_texi/tar.texi(,8850)
+../tar_texi/tar.texi(,8851) @noindent
+../tar_texi/tar.texi(,8852) (as usual, ignore the warnings about unknown
keywords.)
+../tar_texi/tar.texi(,8853)
+../tar_texi/tar.texi(,8854) @item
+../tar_texi/tar.texi(,8855) Let @var{size} be the size of the sparse member,
@var{Bs} be its block number
+../tar_texi/tar.texi(,8856) and @var{Bn} be the block number of the next
member.
+../tar_texi/tar.texi(,8857) Compute:
+../tar_texi/tar.texi(,8858)
+../tar_texi/tar.texi(,8859) @smallexample
+../tar_texi/tar.texi(,8860) @var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2
+../tar_texi/tar.texi(,8861) @end smallexample
+../tar_texi/tar.texi(,8862)
+../tar_texi/tar.texi(,8863) @noindent
+../tar_texi/tar.texi(,8864) This number gives the size of the extended header
part in tar @dfn{blocks}.
+../tar_texi/tar.texi(,8865) In our example, this formula gives: @code{897 - 56
- 425984 / 512 - 2
+../tar_texi/tar.texi(,8866) = 7}.
+../tar_texi/tar.texi(,8867)
+../tar_texi/tar.texi(,8868) @item
+../tar_texi/tar.texi(,8869) Use @command{dd} to extract the headers:
+../tar_texi/tar.texi(,8870)
+../tar_texi/tar.texi(,8871) @smallexample
+../tar_texi/tar.texi(,8872) @kbd{dd address@hidden address@hidden bs=512
address@hidden address@hidden
+../tar_texi/tar.texi(,8873) @end smallexample
+../tar_texi/tar.texi(,8874)
+../tar_texi/tar.texi(,8875) @noindent
+../tar_texi/tar.texi(,8876) where @var{archive} is the archive name,
@var{hname} is a name of the
+../tar_texi/tar.texi(,8877) file to store the extended header in, @var{Bs} and
@var{N} are
+../tar_texi/tar.texi(,8878) computed in previous steps.
+../tar_texi/tar.texi(,8879)
+../tar_texi/tar.texi(,8880) In our example, this command will be
+../tar_texi/tar.texi(,8881)
+../tar_texi/tar.texi(,8882) @smallexample
+../tar_texi/tar.texi(,8883) $ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56
count=7}
+../tar_texi/tar.texi(,8884) @end smallexample
+../tar_texi/tar.texi(,8885) @end enumerate
+../tar_texi/tar.texi(,8886)
+../tar_texi/tar.texi(,8887) Finally, you can expand the condensed file, using
the obtained header:
+../tar_texi/tar.texi(,8888)
+../tar_texi/tar.texi(,8889) @smallexample
+../tar_texi/tar.texi(,8890) @group
+../tar_texi/tar.texi(,8891) $ @kbd{xsparse -v -x xhdr
GNUSparseFile.6058/sparsefile}
+../tar_texi/tar.texi(,8892) Reading extended header file
+../tar_texi/tar.texi(,8893) Found variable GNU.sparse.size = 217481216
+../tar_texi/tar.texi(,8894) Found variable GNU.sparse.numblocks = 208
+../tar_texi/tar.texi(,8895) Found variable GNU.sparse.name = sparsefile
+../tar_texi/tar.texi(,8896) Found variable GNU.sparse.map =
0,2048,1050624,2048,@dots{}
+../tar_texi/tar.texi(,8897) Expanding file `GNUSparseFile.28124/sparsefile' to
`sparsefile'
+../tar_texi/tar.texi(,8898) Done
+../tar_texi/tar.texi(,8899) @end group
+../tar_texi/tar.texi(,8900) @end smallexample
+../tar_texi/tar.texi(,8901)
+../tar_texi/tar.texi(,8902) @node cpio
+../tar_texi/tar.texi(,8903) @section Comparison of @command{tar} and
@command{cpio}
+../tar_texi/tar.texi(UNREVISED,8904) @quotation
+../tar_texi/tar.texi(UNREVISED,8904) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,8904) @end quotation
+../tar_texi/tar.texi(UNREVISED,8904)
+../tar_texi/tar.texi(,8905)
+../tar_texi/tar.texi(FIXME,8906) @allow-recursion
+../tar_texi/tar.texi(FIXME,8906) @quote-arg
+../tar_texi/tar.texi(FIXME,8906)
+../tar_texi/tar.texi(,8907)
+../tar_texi/tar.texi(,8908) The @command{cpio} archive formats, like
@command{tar}, do have maximum
+../tar_texi/tar.texi(,8909) pathname lengths. The binary and old ASCII
formats have a max path
+../tar_texi/tar.texi(,8910) length of 256, and the new ASCII and CRC ASCII
formats have a max
+../tar_texi/tar.texi(,8911) path length of 1024. @acronym{GNU} @command{cpio}
can read and write archives
+../tar_texi/tar.texi(,8912) with arbitrary pathname lengths, but other
@command{cpio} implementations
+../tar_texi/tar.texi(,8913) may crash unexplainedly trying to read them.
+../tar_texi/tar.texi(,8914)
+../tar_texi/tar.texi(,8915) @command{tar} handles symbolic links in the form
in which it comes in BSD;
+../tar_texi/tar.texi(,8916) @command{cpio} doesn't handle symbolic links in
the form in which it comes
+../tar_texi/tar.texi(,8917) in System V prior to SVR4, and some vendors may
have added symlinks
+../tar_texi/tar.texi(,8918) to their system without enhancing @command{cpio}
to know about them.
+../tar_texi/tar.texi(,8919) Others may have enhanced it in a way other than
the way I did it
+../tar_texi/tar.texi(,8920) at Sun, and which was adopted by AT&T (and which
is, I think, also
+../tar_texi/tar.texi(,8921) present in the @command{cpio} that Berkeley picked
up from AT&T and put
+../tar_texi/tar.texi(,8922) into a later BSD release---I think I gave them my
changes).
+../tar_texi/tar.texi(,8923)
+../tar_texi/tar.texi(,8924) (SVR4 does some funny stuff with @command{tar};
basically, its @command{cpio}
+../tar_texi/tar.texi(,8925) can handle @command{tar} format input, and write
it on output, and it
+../tar_texi/tar.texi(,8926) probably handles symbolic links. They may not
have bothered doing
+../tar_texi/tar.texi(,8927) anything to enhance @command{tar} as a result.)
+../tar_texi/tar.texi(,8928)
+../tar_texi/tar.texi(,8929) @command{cpio} handles special files; traditional
@command{tar} doesn't.
+../tar_texi/tar.texi(,8930)
+../tar_texi/tar.texi(,8931) @command{tar} comes with V7, System III, System V,
and BSD source;
+../tar_texi/tar.texi(,8932) @command{cpio} comes only with System III, System
V, and later BSD
+../tar_texi/tar.texi(,8933) (4.3-tahoe and later).
+../tar_texi/tar.texi(,8934)
+../tar_texi/tar.texi(,8935) @command{tar}'s way of handling multiple hard
links to a file can handle
+../tar_texi/tar.texi(,8936) file systems that support 32-bit inumbers (e.g.,
the BSD file system);
+../tar_texi/tar.texi(,8937) @command{cpio}s way requires you to play some
games (in its "binary"
+../tar_texi/tar.texi(,8938) format, i-numbers are only 16 bits, and in its
"portable ASCII" format,
+../tar_texi/tar.texi(,8939) they're 18 bits---it would have to play games with
the "file system ID"
+../tar_texi/tar.texi(,8940) field of the header to make sure that the file
system ID/i-number pairs
+../tar_texi/tar.texi(,8941) of different files were always different), and I
don't know which
+../tar_texi/tar.texi(,8942) @command{cpio}s, if any, play those games. Those
that don't might get
+../tar_texi/tar.texi(,8943) confused and think two files are the same file
when they're not, and
+../tar_texi/tar.texi(,8944) make hard links between them.
+../tar_texi/tar.texi(,8945)
+../tar_texi/tar.texi(,8946) @command{tar}s way of handling multiple hard links
to a file places only
+../tar_texi/tar.texi(,8947) one copy of the link on the tape, but the name
attached to that copy
+../tar_texi/tar.texi(,8948) is the @emph{only} one you can use to retrieve the
file; @command{cpio}s
+../tar_texi/tar.texi(,8949) way puts one copy for every link, but you can
retrieve it using any
+../tar_texi/tar.texi(,8950) of the names.
+../tar_texi/tar.texi(,8951)
+../tar_texi/tar.texi(,8952) @quotation
+../tar_texi/tar.texi(,8953) What type of check sum (if any) is used, and how
is this calculated.
+../tar_texi/tar.texi(,8954) @end quotation
+../tar_texi/tar.texi(,8955)
+../tar_texi/tar.texi(,8956) See the attached manual pages for @command{tar}
and @command{cpio} format.
+../tar_texi/tar.texi(,8957) @command{tar} uses a checksum which is the sum of
all the bytes in the
+../tar_texi/tar.texi(,8958) @command{tar} header for a file; @command{cpio}
uses no checksum.
+../tar_texi/tar.texi(,8959)
+../tar_texi/tar.texi(,8960) @quotation
+../tar_texi/tar.texi(,8961) If anyone knows why @command{cpio} was made when
@command{tar} was present
+../tar_texi/tar.texi(,8962) at the unix scene,
+../tar_texi/tar.texi(,8963) @end quotation
+../tar_texi/tar.texi(,8964)
+../tar_texi/tar.texi(,8965) It wasn't. @command{cpio} first showed up in
PWB/UNIX 1.0; no
+../tar_texi/tar.texi(,8966) generally-available version of UNIX had
@command{tar} at the time. I don't
+../tar_texi/tar.texi(,8967) know whether any version that was generally
available @emph{within AT&T}
+../tar_texi/tar.texi(,8968) had @command{tar}, or, if so, whether the people
within AT&T who did
+../tar_texi/tar.texi(,8969) @command{cpio} knew about it.
+../tar_texi/tar.texi(,8970)
+../tar_texi/tar.texi(,8971) On restore, if there is a corruption on a tape
@command{tar} will stop at
+../tar_texi/tar.texi(,8972) that point, while @command{cpio} will skip over it
and try to restore the
+../tar_texi/tar.texi(,8973) rest of the files.
+../tar_texi/tar.texi(,8974)
+../tar_texi/tar.texi(,8975) The main difference is just in the command syntax
and header format.
+../tar_texi/tar.texi(,8976)
+../tar_texi/tar.texi(,8977) @command{tar} is a little more tape-oriented in
that everything is blocked
+../tar_texi/tar.texi(,8978) to start on a record boundary.
+../tar_texi/tar.texi(,8979)
+../tar_texi/tar.texi(,8980) @quotation
+../tar_texi/tar.texi(,8981) Is there any differences between the ability to
recover crashed
+../tar_texi/tar.texi(,8982) archives between the two of them. (Is there any
chance of recovering
+../tar_texi/tar.texi(,8983) crashed archives at all.)
+../tar_texi/tar.texi(,8984) @end quotation
+../tar_texi/tar.texi(,8985)
+../tar_texi/tar.texi(,8986) Theoretically it should be easier under
@command{tar} since the blocking
+../tar_texi/tar.texi(,8987) lets you find a header with some variation of
@samp{dd address@hidden
+../tar_texi/tar.texi(,8988) However, modern @command{cpio}'s and variations
have an option to just
+../tar_texi/tar.texi(,8989) search for the next file header after an error
with a reasonable chance
+../tar_texi/tar.texi(,8990) of resyncing. However, lots of tape driver
software won't allow you to
+../tar_texi/tar.texi(,8991) continue past a media error which should be the
only reason for getting
+../tar_texi/tar.texi(,8992) out of sync unless a file changed sizes while you
were writing the
+../tar_texi/tar.texi(,8993) archive.
+../tar_texi/tar.texi(,8994)
+../tar_texi/tar.texi(,8995) @quotation
+../tar_texi/tar.texi(,8996) If anyone knows why @command{cpio} was made when
@command{tar} was present
+../tar_texi/tar.texi(,8997) at the unix scene, please tell me about this too.
+../tar_texi/tar.texi(,8998) @end quotation
+../tar_texi/tar.texi(,8999)
+../tar_texi/tar.texi(,9000) Probably because it is more media efficient (by
not blocking everything
+../tar_texi/tar.texi(,9001) and using only the space needed for the headers
where @command{tar}
+../tar_texi/tar.texi(,9002) always uses 512 bytes per file header) and it
knows how to archive
+../tar_texi/tar.texi(,9003) special files.
+../tar_texi/tar.texi(,9004)
+../tar_texi/tar.texi(,9005) You might want to look at the freely available
alternatives. The
+../tar_texi/tar.texi(GNUTAR,9006) major ones are @command{afio},
../tar_texi/tar.texi(GNUTAR,9006) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9006) , and
+../tar_texi/tar.texi(,9007) @command{pax}, each of which have their own
extensions with some
+../tar_texi/tar.texi(,9008) backwards compatibility.
+../tar_texi/tar.texi(,9009)
+../tar_texi/tar.texi(,9010) Sparse files were @command{tar}red as sparse files
(which you can
+../tar_texi/tar.texi(,9011) easily test, because the resulting archive gets
smaller, and
+../tar_texi/tar.texi(,9012) @acronym{GNU} @command{cpio} can no longer read
it).
+../tar_texi/tar.texi(,9013)
+../tar_texi/tar.texi(,9014) @node Media
+../tar_texi/tar.texi(,9015) @chapter Tapes and Other Archive Media
+../tar_texi/tar.texi(UNREVISED,9016) @quotation
+../tar_texi/tar.texi(UNREVISED,9016) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9016) @end quotation
+../tar_texi/tar.texi(UNREVISED,9016)
+../tar_texi/tar.texi(,9017)
+../tar_texi/tar.texi(,9018) A few special cases about tape handling warrant
more detailed
+../tar_texi/tar.texi(,9019) description. These special cases are discussed
below.
+../tar_texi/tar.texi(,9020)
+../tar_texi/tar.texi(,9021) Many complexities surround the use of
@command{tar} on tape drives. Since
+../tar_texi/tar.texi(,9022) the creation and manipulation of archives located
on magnetic tape was
+../tar_texi/tar.texi(,9023) the original purpose of @command{tar}, it contains
many features making
+../tar_texi/tar.texi(,9024) such manipulation easier.
+../tar_texi/tar.texi(,9025)
+../tar_texi/tar.texi(,9026) Archives are usually written on dismountable
media---tape cartridges,
+../tar_texi/tar.texi(,9027) mag tapes, or floppy disks.
+../tar_texi/tar.texi(,9028)
+../tar_texi/tar.texi(,9029) The amount of data a tape or disk holds depends
not only on its size,
+../tar_texi/tar.texi(,9030) but also on how it is formatted. A 2400 foot long
reel of mag tape
+../tar_texi/tar.texi(,9031) holds 40 megabytes of data when formatted at 1600
bits per inch. The
+../tar_texi/tar.texi(,9032) physically smaller EXABYTE tape cartridge holds
2.3 gigabytes.
+../tar_texi/tar.texi(,9033)
+../tar_texi/tar.texi(,9034) Magnetic media are re-usable---once the archive on
a tape is no longer
+../tar_texi/tar.texi(,9035) needed, the archive can be erased and the tape or
disk used over.
+../tar_texi/tar.texi(,9036) Media quality does deteriorate with use, however.
Most tapes or disks
+../tar_texi/tar.texi(,9037) should be discarded when they begin to produce
data errors. EXABYTE
+../tar_texi/tar.texi(,9038) tape cartridges should be discarded when they
generate an @dfn{error
+../tar_texi/tar.texi(,9039) count} (number of non-usable bits) of more than
10k.
+../tar_texi/tar.texi(,9040)
+../tar_texi/tar.texi(,9041) Magnetic media are written and erased using
magnetic fields, and
+../tar_texi/tar.texi(,9042) should be protected from such fields to avoid
damage to stored data.
+../tar_texi/tar.texi(,9043) Sticking a floppy disk to a filing cabinet using a
magnet is probably
+../tar_texi/tar.texi(,9044) not a good idea.
+../tar_texi/tar.texi(,9045)
+../tar_texi/tar.texi(,9046) @menu
+../tar_texi/tar.texi(,9047) * Device:: Device selection
and switching
+../tar_texi/tar.texi(,9048) * Remote Tape Server::
+../tar_texi/tar.texi(,9049) * Common Problems and Solutions::
+../tar_texi/tar.texi(,9050) * Blocking:: Blocking
+../tar_texi/tar.texi(,9051) * Many:: Many archives on
one tape
+../tar_texi/tar.texi(,9052) * Using Multiple Tapes:: Using Multiple
Tapes
+../tar_texi/tar.texi(,9053) * label:: Including a Label
in the Archive
+../tar_texi/tar.texi(,9054) * verify::
+../tar_texi/tar.texi(,9055) * Write Protection::
+../tar_texi/tar.texi(,9056) @end menu
+../tar_texi/tar.texi(,9057)
+../tar_texi/tar.texi(,9058) @node Device
+../tar_texi/tar.texi(,9059) @section Device Selection and Switching
+../tar_texi/tar.texi(UNREVISED,9060) @quotation
+../tar_texi/tar.texi(UNREVISED,9060) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9060) @end quotation
+../tar_texi/tar.texi(UNREVISED,9060)
+../tar_texi/tar.texi(,9061)
+../tar_texi/tar.texi(,9062) @table @option
+../tar_texi/tar.texi(,9063) @item -f address@hidden:address@hidden
+../tar_texi/tar.texi(,9064) @itemx address@hidden:address@hidden
+../tar_texi/tar.texi(,9065) Use archive file or device @var{file} on
@var{hostname}.
+../tar_texi/tar.texi(,9066) @end table
+../tar_texi/tar.texi(,9067)
+../tar_texi/tar.texi(,9068) This option is used to specify the file name of
the archive @command{tar}
+../tar_texi/tar.texi(,9069) works on.
+../tar_texi/tar.texi(,9070)
+../tar_texi/tar.texi(,9071) If the file name is @samp{-}, @command{tar} reads
the archive from standard
+../tar_texi/tar.texi(,9072) input (when listing or extracting), or writes it
to standard output
+../tar_texi/tar.texi(,9073) (when creating). If the @samp{-} file name is
given when updating an
+../tar_texi/tar.texi(,9074) archive, @command{tar} will read the original
archive from its standard
+../tar_texi/tar.texi(,9075) input, and will write the entire new archive to
its standard output.
+../tar_texi/tar.texi(,9076)
+../tar_texi/tar.texi(,9077) If the file name contains a @samp{:}, it is
interpreted as
+../tar_texi/tar.texi(,9078) @samp{hostname:file name}. If the @var{hostname}
contains an @dfn{at}
+../tar_texi/tar.texi(,9079) sign (@samp{@@}), it is treated as
@samp{user@@hostname:file name}. In
+../tar_texi/tar.texi(,9080) either case, @command{tar} will invoke the command
@command{rsh} (or
+../tar_texi/tar.texi(,9081) @command{remsh}) to start up an
@command{/usr/libexec/rmt} on the remote
+../tar_texi/tar.texi(,9082) machine. If you give an alternate login name, it
will be given to the
+../tar_texi/tar.texi(,9083) @command{rsh}.
+../tar_texi/tar.texi(,9084) Naturally, the remote machine must have an
executable
+../tar_texi/tar.texi(,9085) @command{/usr/libexec/rmt}. This program is free
software from the
+../tar_texi/tar.texi(,9086) University of California, and a copy of the source
code can be found
+../tar_texi/tar.texi(,9087) with the sources for @command{tar}; it's compiled
and installed by default.
+../tar_texi/tar.texi(,9088) The exact path to this utility is determined when
configuring the package.
+../tar_texi/tar.texi(,9089) It is @address@hidden/libexec/rmt}, where
@var{prefix} stands for
+../tar_texi/tar.texi(,9090) your installation prefix. This location may also
be overridden at
+../tar_texi/tar.texi(,9091) runtime by using @address@hidden option
(@xref{Option Summary,
+../tar_texi/tar.texi(,9092) ---rmt-command}, for detailed description of this
option. @xref{Remote
+../tar_texi/tar.texi(,9093) Tape Server}, for the description of @command{rmt}
command).
+../tar_texi/tar.texi(,9094)
+../tar_texi/tar.texi(,9095) If this option is not given, but the environment
variable @env{TAPE}
+../tar_texi/tar.texi(,9096) is set, its value is used; otherwise, old versions
of @command{tar}
+../tar_texi/tar.texi(,9097) used a default archive name (which was picked when
@command{tar} was
+../tar_texi/tar.texi(,9098) compiled). The default is normally set up to be
the @dfn{first} tape
+../tar_texi/tar.texi(,9099) drive or other transportable I/O medium on the
system.
+../tar_texi/tar.texi(,9100)
+../tar_texi/tar.texi(GNUTAR,9101) Starting with version 1.11.5,
../tar_texi/tar.texi(GNUTAR,9101) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9101) uses
+../tar_texi/tar.texi(,9102) standard input and standard output as the default
device, and I will
+../tar_texi/tar.texi(,9103) not try anymore supporting automatic device
detection at installation
+../tar_texi/tar.texi(,9104) time. This was failing really in too many cases,
it was hopeless.
+../tar_texi/tar.texi(,9105) This is now completely left to the installer to
override standard
+../tar_texi/tar.texi(,9106) input and standard output for default device, if
this seems
+../tar_texi/tar.texi(,9107) preferable. Further, I think @emph{most} actual
usages of
+../tar_texi/tar.texi(,9108) @command{tar} are done with pipes or disks, not
really tapes,
+../tar_texi/tar.texi(,9109) cartridges or diskettes.
+../tar_texi/tar.texi(,9110)
+../tar_texi/tar.texi(,9111) Some users think that using standard input and
output is running
+../tar_texi/tar.texi(,9112) after trouble. This could lead to a nasty
surprise on your screen if
+../tar_texi/tar.texi(,9113) you forget to specify an output file
name---especially if you are going
+../tar_texi/tar.texi(,9114) through a network or terminal server capable of
buffering large amounts
+../tar_texi/tar.texi(,9115) of output. We had so many bug reports in that
area of configuring
+../tar_texi/tar.texi(,9116) default tapes automatically, and so many
contradicting requests, that
+../tar_texi/tar.texi(,9117) we finally consider the problem to be portably
intractable. We could
+../tar_texi/tar.texi(,9118) of course use something like @samp{/dev/tape} as a
default, but this
+../tar_texi/tar.texi(,9119) is @emph{also} running after various kind of
trouble, going from hung
+../tar_texi/tar.texi(,9120) processes to accidental destruction of real tapes.
After having seen
+../tar_texi/tar.texi(,9121) all this mess, using standard input and output as
a default really
+../tar_texi/tar.texi(,9122) sounds like the only clean choice left, and a very
useful one too.
+../tar_texi/tar.texi(,9123)
+../tar_texi/tar.texi(GNUTAR,9124) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9124) reads and writes archive in
records, I
+../tar_texi/tar.texi(,9125) suspect this is the main reason why block devices
are preferred over
+../tar_texi/tar.texi(,9126) character devices. Most probably, block devices
are more efficient
+../tar_texi/tar.texi(,9127) too. The installer could also check for
@samp{DEFTAPE} in
+../tar_texi/tar.texi(,9128) @file{<sys/mtio.h>}.
+../tar_texi/tar.texi(,9129)
+../tar_texi/tar.texi(,9130) @table @option
+../tar_texi/tar.texi(xopindex,9131) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,9131)
+../tar_texi/tar.texi(,9132) @item --force-local
+../tar_texi/tar.texi(,9133) Archive file is local even if it contains a colon.
+../tar_texi/tar.texi(,9134)
+../tar_texi/tar.texi(,9135) @opindex rsh-command
+../tar_texi/tar.texi(,9136) @item address@hidden
+../tar_texi/tar.texi(,9137) Use remote @var{command} instead of @command{rsh}.
This option exists
+../tar_texi/tar.texi(,9138) so that people who use something other than the
standard @command{rsh}
+../tar_texi/tar.texi(,9139) (e.g., a Kerberized @command{rsh}) can access a
remote device.
+../tar_texi/tar.texi(,9140)
+../tar_texi/tar.texi(,9141) When this command is not used, the shell command
found when
+../tar_texi/tar.texi(,9142) the @command{tar} program was installed is used
instead. This is
+../tar_texi/tar.texi(,9143) the first found of @file{/usr/ucb/rsh},
@file{/usr/bin/remsh},
+../tar_texi/tar.texi(,9144) @file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or
@file{/usr/bin/nsh}.
+../tar_texi/tar.texi(,9145) The installer may have overridden this by defining
the environment
+../tar_texi/tar.texi(,9146) variable @env{RSH} @emph{at installation time}.
+../tar_texi/tar.texi(,9147)
+../tar_texi/tar.texi(,9148) @item -[0-7][lmh]
+../tar_texi/tar.texi(,9149) Specify drive and density.
+../tar_texi/tar.texi(,9150)
+../tar_texi/tar.texi(xopindex,9151) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,9151)
+../tar_texi/tar.texi(,9152) @item -M
+../tar_texi/tar.texi(,9153) @itemx --multi-volume
+../tar_texi/tar.texi(,9154) Create/list/extract multi-volume archive.
+../tar_texi/tar.texi(,9155)
+../tar_texi/tar.texi(,9156) This option causes @command{tar} to write a
@dfn{multi-volume} archive---one
+../tar_texi/tar.texi(,9157) that may be larger than will fit on the medium
used to hold it.
+../tar_texi/tar.texi(,9158) @xref{Multi-Volume Archives}.
+../tar_texi/tar.texi(,9159)
+../tar_texi/tar.texi(xopindex,9160) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,9160)
+../tar_texi/tar.texi(,9161) @item -L @var{num}
+../tar_texi/tar.texi(,9162) @itemx address@hidden
+../tar_texi/tar.texi(,9163) Change tape after writing @var{num} x 1024 bytes.
+../tar_texi/tar.texi(,9164)
+../tar_texi/tar.texi(,9165) This option might be useful when your tape drivers
do not properly
+../tar_texi/tar.texi(,9166) detect end of physical tapes. By being slightly
conservative on the
+../tar_texi/tar.texi(,9167) maximum tape length, you might avoid the problem
entirely.
+../tar_texi/tar.texi(,9168)
+../tar_texi/tar.texi(xopindex,9169) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,9169)
+../tar_texi/tar.texi(xopindex,9170) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,9170)
+../tar_texi/tar.texi(,9171) @item -F @var{file}
+../tar_texi/tar.texi(,9172) @itemx address@hidden
+../tar_texi/tar.texi(,9173) @itemx address@hidden
+../tar_texi/tar.texi(,9174) Execute @file{file} at end of each tape. This
implies
+../tar_texi/tar.texi(,9175) @option{--multi-volume} (@option{-M}).
@xref{info-script}, for a detailed
+../tar_texi/tar.texi(,9176) description of this option.
+../tar_texi/tar.texi(,9177) @end table
+../tar_texi/tar.texi(,9178)
+../tar_texi/tar.texi(,9179) @node Remote Tape Server
+../tar_texi/tar.texi(,9180) @section The Remote Tape Server
+../tar_texi/tar.texi(,9181)
+../tar_texi/tar.texi(,9182) @cindex remote tape drive
+../tar_texi/tar.texi(,9183) @pindex rmt
+../tar_texi/tar.texi(,9184) In order to access the tape drive on a remote
machine, @command{tar}
+../tar_texi/tar.texi(,9185) uses the remote tape server written at the
University of California at
+../tar_texi/tar.texi(,9186) Berkeley. The remote tape server must be
installed as
+../tar_texi/tar.texi(,9187) @address@hidden/libexec/rmt} on any machine whose
tape drive you
+../tar_texi/tar.texi(,9188) want to use. @command{tar} calls @command{rmt} by
running an
+../tar_texi/tar.texi(,9189) @command{rsh} or @command{remsh} to the remote
machine, optionally
+../tar_texi/tar.texi(,9190) using a different login name if one is supplied.
+../tar_texi/tar.texi(,9191)
+../tar_texi/tar.texi(,9192) A copy of the source for the remote tape server is
provided. It is
+../tar_texi/tar.texi(,9193) Copyright @copyright{} 1983 by the Regents of the
University of
+../tar_texi/tar.texi(,9194) California, but can be freely distributed. It is
compiled and
+../tar_texi/tar.texi(,9195) installed by default.
+../tar_texi/tar.texi(,9196)
+../tar_texi/tar.texi(,9197) @cindex absolute file names
+../tar_texi/tar.texi(,9198) Unless you use the @option{--absolute-names}
(@option{-P}) option,
+../tar_texi/tar.texi(GNUTAR,9199) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9199) will not allow you to create an
archive that contains
+../tar_texi/tar.texi(,9200) absolute file names (a file name beginning with
@samp{/}.) If you try,
+../tar_texi/tar.texi(,9201) @command{tar} will automatically remove the
leading @samp{/} from the
+../tar_texi/tar.texi(,9202) file names it stores in the archive. It will also
type a warning
+../tar_texi/tar.texi(,9203) message telling you what it is doing.
+../tar_texi/tar.texi(,9204)
+../tar_texi/tar.texi(,9205) When reading an archive that was created with a
different
+../tar_texi/tar.texi(GNUTAR,9206) @command{tar} program,
../tar_texi/tar.texi(GNUTAR,9206) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9206) automatically
+../tar_texi/tar.texi(,9207) extracts entries in the archive which have
absolute file names as if
+../tar_texi/tar.texi(,9208) the file names were not absolute. This is an
important feature. A
+../tar_texi/tar.texi(,9209) visitor here once gave a @command{tar} tape to an
operator to restore;
+../tar_texi/tar.texi(GNUTAR,9210) the operator used Sun @command{tar} instead
of ../tar_texi/tar.texi(GNUTAR,9210) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9210) ,
+../tar_texi/tar.texi(,9211) and the result was that it replaced large portions
of
+../tar_texi/tar.texi(,9212) our @file{/bin} and friends with versions from the
tape; needless to
+../tar_texi/tar.texi(,9213) say, we were unhappy about having to recover the
file system from
+../tar_texi/tar.texi(,9214) backup tapes.
+../tar_texi/tar.texi(,9215)
+../tar_texi/tar.texi(,9216) For example, if the archive contained a file
@file{/usr/bin/computoy},
+../tar_texi/tar.texi(GNUTAR,9217) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9217) would extract the file to
@file{usr/bin/computoy},
+../tar_texi/tar.texi(,9218) relative to the current directory. If you want to
extract the files in
+../tar_texi/tar.texi(,9219) an archive to the same absolute names that they
had when the archive
+../tar_texi/tar.texi(,9220) was created, you should do a @samp{cd /} before
extracting the files
+../tar_texi/tar.texi(,9221) from the archive, or you should either use the
@option{--absolute-names}
+../tar_texi/tar.texi(,9222) option, or use the command @samp{tar -C / @dots{}}.
+../tar_texi/tar.texi(,9223)
+../tar_texi/tar.texi(,9224) @cindex Ultrix 3.1 and write failure
+../tar_texi/tar.texi(,9225) Some versions of Unix (Ultrix 3.1 is known to have
this problem),
+../tar_texi/tar.texi(,9226) can claim that a short write near the end of a
tape succeeded,
+../tar_texi/tar.texi(,9227) when it actually failed. This will result in the
-M option not
+../tar_texi/tar.texi(,9228) working correctly. The best workaround at the
moment is to use a
+../tar_texi/tar.texi(,9229) significantly larger blocking factor than the
default 20.
+../tar_texi/tar.texi(,9230)
+../tar_texi/tar.texi(,9231) In order to update an archive, @command{tar} must
be able to backspace the
+../tar_texi/tar.texi(,9232) archive in order to reread or rewrite a record
that was just read (or
+../tar_texi/tar.texi(,9233) written). This is currently possible only on two
kinds of files: normal
+../tar_texi/tar.texi(,9234) disk files (or any other file that can be
backspaced with @samp{lseek}),
+../tar_texi/tar.texi(,9235) and industry-standard 9-track magnetic tape (or
any other kind of tape
+../tar_texi/tar.texi(,9236) that can be backspaced with the @code{MTIOCTOP}
@code{ioctl}.
+../tar_texi/tar.texi(,9237)
+../tar_texi/tar.texi(,9238) This means that the @option{--append},
@option{--concatenate}, and
+../tar_texi/tar.texi(,9239) @option{--delete} commands will not work on any
other kind of file.
+../tar_texi/tar.texi(,9240) Some media simply cannot be backspaced, which
means these commands and
+../tar_texi/tar.texi(,9241) options will never be able to work on them. These
non-backspacing
+../tar_texi/tar.texi(,9242) media include pipes and cartridge tape drives.
+../tar_texi/tar.texi(,9243)
+../tar_texi/tar.texi(,9244) Some other media can be backspaced, and
@command{tar} will work on them
+../tar_texi/tar.texi(,9245) once @command{tar} is modified to do so.
+../tar_texi/tar.texi(,9246)
+../tar_texi/tar.texi(,9247) Archives created with the @option{--multi-volume},
@option{--label}, and
+../tar_texi/tar.texi(,9248) @option{--incremental} (@option{-G}) options may
not be readable by other version
+../tar_texi/tar.texi(,9249) of @command{tar}. In particular, restoring a file
that was split over
+../tar_texi/tar.texi(,9250) a volume boundary will require some careful work
with @command{dd}, if
+../tar_texi/tar.texi(,9251) it can be done at all. Other versions of
@command{tar} may also create
+../tar_texi/tar.texi(,9252) an empty file whose name is that of the volume
header. Some versions
+../tar_texi/tar.texi(,9253) of @command{tar} may create normal files instead
of directories archived
+../tar_texi/tar.texi(,9254) with the @option{--incremental} (@option{-G})
option.
+../tar_texi/tar.texi(,9255)
+../tar_texi/tar.texi(,9256) @node Common Problems and Solutions
+../tar_texi/tar.texi(,9257) @section Some Common Problems and their Solutions
+../tar_texi/tar.texi(,9258)
+../tar_texi/tar.texi(,9260)
+../tar_texi/tar.texi(,9261) @format
+../tar_texi/tar.texi(,9262) errors from system:
+../tar_texi/tar.texi(,9263) permission denied
+../tar_texi/tar.texi(,9264) no such file or directory
+../tar_texi/tar.texi(,9265) not owner
+../tar_texi/tar.texi(,9266)
+../tar_texi/tar.texi(,9267) errors from @command{tar}:
+../tar_texi/tar.texi(,9268) directory checksum error
+../tar_texi/tar.texi(,9269) header format error
+../tar_texi/tar.texi(,9270)
+../tar_texi/tar.texi(,9271) errors from media/system:
+../tar_texi/tar.texi(,9272) i/o error
+../tar_texi/tar.texi(,9273) device busy
+../tar_texi/tar.texi(,9274) @end format
+../tar_texi/tar.texi(,9275)
+../tar_texi/tar.texi(,9277)
+../tar_texi/tar.texi(,9278) @node Blocking
+../tar_texi/tar.texi(,9279) @section Blocking
+../tar_texi/tar.texi(UNREVISED,9280) @quotation
+../tar_texi/tar.texi(UNREVISED,9280) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9280) @end quotation
+../tar_texi/tar.texi(UNREVISED,9280)
+../tar_texi/tar.texi(,9281)
+../tar_texi/tar.texi(,9282) @dfn{Block} and @dfn{record} terminology is rather
confused, and it
+../tar_texi/tar.texi(,9283) is also confusing to the expert reader. On the
other hand, readers
+../tar_texi/tar.texi(,9284) who are new to the field have a fresh mind, and
they may safely skip
+../tar_texi/tar.texi(,9285) the next two paragraphs, as the remainder of this
manual uses those
+../tar_texi/tar.texi(,9286) two terms in a quite consistent way.
+../tar_texi/tar.texi(,9287)
+../tar_texi/tar.texi(,9288) John Gilmore, the writer of the public domain
@command{tar} from which
+../tar_texi/tar.texi(GNUTAR,9289) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9289) was originally derived, wrote
(June 1995):
+../tar_texi/tar.texi(,9290)
+../tar_texi/tar.texi(,9291) @quotation
+../tar_texi/tar.texi(,9292) The nomenclature of tape drives comes from IBM,
where I believe
+../tar_texi/tar.texi(,9293) they were invented for the IBM 650 or so. On IBM
mainframes, what
+../tar_texi/tar.texi(,9294) is recorded on tape are tape blocks. The logical
organization of
+../tar_texi/tar.texi(,9295) data is into records. There are various ways of
putting records into
+../tar_texi/tar.texi(,9296) blocks, including @code{F} (fixed sized records),
@code{V} (variable
+../tar_texi/tar.texi(,9297) sized records), @code{FB} (fixed blocked: fixed
size records, @var{n}
+../tar_texi/tar.texi(,9298) to a block), @code{VB} (variable size records,
@var{n} to a block),
+../tar_texi/tar.texi(,9299) @code{VSB} (variable spanned blocked: variable
sized records that can
+../tar_texi/tar.texi(,9300) occupy more than one block), etc. The @code{JCL}
@samp{DD RECFORM=}
+../tar_texi/tar.texi(,9301) parameter specified this to the operating system.
+../tar_texi/tar.texi(,9302)
+../tar_texi/tar.texi(,9303) The Unix man page on @command{tar} was totally
confused about this.
+../tar_texi/tar.texi(,9304) When I wrote @code{PD TAR}, I used the
historically correct terminology
+../tar_texi/tar.texi(,9305) (@command{tar} writes data records, which are
grouped into blocks).
+../tar_texi/tar.texi(,9306) It appears that the bogus terminology made it into
@acronym{POSIX} (no surprise
+../tar_texi/tar.texi(,9307) here), and now address@hidden has migrated that
terminology back
+../tar_texi/tar.texi(,9308) into the source code too.
+../tar_texi/tar.texi(,9309) @end quotation
+../tar_texi/tar.texi(,9310)
+../tar_texi/tar.texi(,9311) The term @dfn{physical block} means the basic
transfer chunk from or
+../tar_texi/tar.texi(,9312) to a device, after which reading or writing may
stop without anything
+../tar_texi/tar.texi(,9313) being lost. In this manual, the term @dfn{block}
usually refers to
+../tar_texi/tar.texi(,9314) a disk physical block, @emph{assuming} that each
disk block is 512
+../tar_texi/tar.texi(,9315) bytes in length. It is true that some disk
devices have different
+../tar_texi/tar.texi(,9316) physical blocks, but @command{tar} ignore these
differences in its own
+../tar_texi/tar.texi(,9317) format, which is meant to be portable, so a
@command{tar} block is always
+../tar_texi/tar.texi(,9318) 512 bytes in length, and @dfn{block} always mean a
@command{tar} block.
+../tar_texi/tar.texi(,9319) The term @dfn{logical block} often represents the
basic chunk of
+../tar_texi/tar.texi(,9320) allocation of many disk blocks as a single entity,
which the operating
+../tar_texi/tar.texi(,9321) system treats somewhat atomically; this concept is
only barely used
+../tar_texi/tar.texi(GNUTAR,9322) in ../tar_texi/tar.texi(GNUTAR,9322)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,9322) .
+../tar_texi/tar.texi(,9323)
+../tar_texi/tar.texi(,9324) The term @dfn{physical record} is another way to
speak of a physical
+../tar_texi/tar.texi(,9325) block, those two terms are somewhat
interchangeable. In this manual,
+../tar_texi/tar.texi(,9326) the term @dfn{record} usually refers to a tape
physical block,
+../tar_texi/tar.texi(,9327) @emph{assuming} that the @command{tar} archive is
kept on magnetic tape.
+../tar_texi/tar.texi(,9328) It is true that archives may be put on disk or
used with pipes,
+../tar_texi/tar.texi(,9329) but nevertheless, @command{tar} tries to read and
write the archive one
+../tar_texi/tar.texi(,9330) @dfn{record} at a time, whatever the medium in
use. One record is made
+../tar_texi/tar.texi(,9331) up of an integral number of blocks, and this
operation of putting many
+../tar_texi/tar.texi(,9332) disk blocks into a single tape block is called
@dfn{reblocking}, or
+../tar_texi/tar.texi(,9333) more simply, @dfn{blocking}. The term
@dfn{logical record} refers to
+../tar_texi/tar.texi(,9334) the logical organization of many characters into
something meaningful
+../tar_texi/tar.texi(,9335) to the application. The term @dfn{unit record}
describes a small set
+../tar_texi/tar.texi(,9336) of characters which are transmitted whole to or by
the application,
+../tar_texi/tar.texi(,9337) and often refers to a line of text. Those two
last terms are unrelated
+../tar_texi/tar.texi(GNUTAR,9338) to what we call a @dfn{record} in
../tar_texi/tar.texi(GNUTAR,9338) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9338) .
+../tar_texi/tar.texi(,9339)
+../tar_texi/tar.texi(,9340) When writing to tapes, @command{tar} writes the
contents of the archive
+../tar_texi/tar.texi(,9341) in chunks known as @dfn{records}. To change the
default blocking
+../tar_texi/tar.texi(,9342) factor, use the @address@hidden (@option{-b
+../tar_texi/tar.texi(,9343) @var{512-size}}) option. Each record will then be
composed of
+../tar_texi/tar.texi(,9344) @var{512-size} blocks. (Each @command{tar} block
is 512 bytes.
+../tar_texi/tar.texi(,9345) @xref{Standard}.) Each file written to the
archive uses at least one
+../tar_texi/tar.texi(,9346) full record. As a result, using a larger record
size can result in
+../tar_texi/tar.texi(,9347) more wasted space for small files. On the other
hand, a larger record
+../tar_texi/tar.texi(,9348) size can often be read and written much more
efficiently.
+../tar_texi/tar.texi(,9349)
+../tar_texi/tar.texi(,9350) Further complicating the problem is that some tape
drives ignore the
+../tar_texi/tar.texi(,9351) blocking entirely. For these, a larger record
size can still improve
+../tar_texi/tar.texi(,9352) performance (because the software layers above the
tape drive still
+../tar_texi/tar.texi(,9353) honor the blocking), but not as dramatically as on
tape drives that
+../tar_texi/tar.texi(,9354) honor blocking.
+../tar_texi/tar.texi(,9355)
+../tar_texi/tar.texi(,9356) When reading an archive, @command{tar} can usually
figure out the
+../tar_texi/tar.texi(,9357) record size on itself. When this is the case, and
a non-standard
+../tar_texi/tar.texi(,9358) record size was used when the archive was created,
@command{tar} will
+../tar_texi/tar.texi(,9359) print a message about a non-standard blocking
factor, and then operate
+../tar_texi/tar.texi(,9360) normally. On some tape devices, however,
@command{tar} cannot figure
+../tar_texi/tar.texi(,9361) out the record size itself. On most of those, you
can specify a
+../tar_texi/tar.texi(,9362) blocking factor (with @option{--blocking-factor})
larger than the
+../tar_texi/tar.texi(,9363) actual blocking factor, and then use the
@option{--read-full-records}
+../tar_texi/tar.texi(,9364) (@option{-B}) option. (If you specify a blocking
factor with
+../tar_texi/tar.texi(,9365) @option{--blocking-factor} and don't use the
+../tar_texi/tar.texi(,9366) @option{--read-full-records} option, then
@command{tar} will not
+../tar_texi/tar.texi(,9367) attempt to figure out the recording size itself.)
On some devices,
+../tar_texi/tar.texi(,9368) you must always specify the record size exactly
with
+../tar_texi/tar.texi(,9369) @option{--blocking-factor} when reading, because
@command{tar} cannot
+../tar_texi/tar.texi(,9370) figure it out. In any case, use @option{--list}
(@option{-t}) before
+../tar_texi/tar.texi(,9371) doing any extractions to see whether @command{tar}
is reading the archive
+../tar_texi/tar.texi(,9372) correctly.
+../tar_texi/tar.texi(,9373)
+../tar_texi/tar.texi(,9374) @command{tar} blocks are all fixed size (512
bytes), and its scheme for
+../tar_texi/tar.texi(,9375) putting them into records is to put a whole number
of them (one or
+../tar_texi/tar.texi(,9376) more) into each record. @command{tar} records are
all the same size;
+../tar_texi/tar.texi(,9377) at the end of the file there's a block containing
all zeros, which
+../tar_texi/tar.texi(,9378) is how you tell that the remainder of the last
record(s) are garbage.
+../tar_texi/tar.texi(,9379)
+../tar_texi/tar.texi(,9380) In a standard @command{tar} file (no options), the
block size is 512
+../tar_texi/tar.texi(,9381) and the record size is 10240, for a blocking
factor of 20. What the
+../tar_texi/tar.texi(,9382) @option{--blocking-factor} option does is sets the
blocking factor,
+../tar_texi/tar.texi(,9383) changing the record size while leaving the block
size at 512 bytes.
+../tar_texi/tar.texi(,9384) 20 was fine for ancient 800 or 1600 bpi
reel-to-reel tape drives;
+../tar_texi/tar.texi(,9385) most tape drives these days prefer much bigger
records in order to
+../tar_texi/tar.texi(,9386) stream and not waste tape. When writing tapes for
myself, some tend
+../tar_texi/tar.texi(,9387) to use a factor of the order of 2048, say, giving
a record size of
+../tar_texi/tar.texi(,9388) around one megabyte.
+../tar_texi/tar.texi(,9389)
+../tar_texi/tar.texi(,9390) If you use a blocking factor larger than 20, older
@command{tar}
+../tar_texi/tar.texi(,9391) programs might not be able to read the archive, so
we recommend this
+../tar_texi/tar.texi(GNUTAR,9392) as a limit to use in practice.
../tar_texi/tar.texi(GNUTAR,9392) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9392) , however,
+../tar_texi/tar.texi(,9393) will support arbitrarily large record sizes,
limited only by the
+../tar_texi/tar.texi(,9394) amount of virtual memory or the physical
characteristics of the tape
+../tar_texi/tar.texi(,9395) device.
+../tar_texi/tar.texi(,9396)
+../tar_texi/tar.texi(,9397) @menu
+../tar_texi/tar.texi(,9398) * Format Variations:: Format Variations
+../tar_texi/tar.texi(,9399) * Blocking Factor:: The Blocking
Factor of an Archive
+../tar_texi/tar.texi(,9400) @end menu
+../tar_texi/tar.texi(,9401)
+../tar_texi/tar.texi(,9402) @node Format Variations
+../tar_texi/tar.texi(,9403) @subsection Format Variations
+../tar_texi/tar.texi(,9404) @cindex Format Parameters
+../tar_texi/tar.texi(,9405) @cindex Format Options
+../tar_texi/tar.texi(,9406) @cindex Options, archive format specifying
+../tar_texi/tar.texi(,9407) @cindex Options, format specifying
+../tar_texi/tar.texi(UNREVISED,9408) @quotation
+../tar_texi/tar.texi(UNREVISED,9408) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9408) @end quotation
+../tar_texi/tar.texi(UNREVISED,9408)
+../tar_texi/tar.texi(,9409)
+../tar_texi/tar.texi(,9410) Format parameters specify how an archive is
written on the archive
+../tar_texi/tar.texi(,9411) media. The best choice of format parameters will
vary depending on
+../tar_texi/tar.texi(,9412) the type and number of files being archived, and
on the media used to
+../tar_texi/tar.texi(,9413) store the archive.
+../tar_texi/tar.texi(,9414)
+../tar_texi/tar.texi(,9415) To specify format parameters when accessing or
creating an archive,
+../tar_texi/tar.texi(,9416) you can use the options described in the following
sections.
+../tar_texi/tar.texi(,9417) If you do not specify any format parameters,
@command{tar} uses
+../tar_texi/tar.texi(,9418) default parameters. You cannot modify a
compressed archive.
+../tar_texi/tar.texi(,9419) If you create an archive with the
@option{--blocking-factor} option
+../tar_texi/tar.texi(,9420) specified (@pxref{Blocking Factor}), you must
specify that
+../tar_texi/tar.texi(,9421) blocking-factor when operating on the archive.
@xref{Formats}, for other
+../tar_texi/tar.texi(,9422) examples of format parameter considerations.
+../tar_texi/tar.texi(,9423)
+../tar_texi/tar.texi(,9424) @node Blocking Factor
+../tar_texi/tar.texi(,9425) @subsection The Blocking Factor of an Archive
+../tar_texi/tar.texi(,9426) @cindex Blocking Factor
+../tar_texi/tar.texi(,9427) @cindex Record Size
+../tar_texi/tar.texi(,9428) @cindex Number of blocks per record
+../tar_texi/tar.texi(,9429) @cindex Number of bytes per record
+../tar_texi/tar.texi(,9430) @cindex Bytes per record
+../tar_texi/tar.texi(,9431) @cindex Blocks per record
+../tar_texi/tar.texi(UNREVISED,9432) @quotation
+../tar_texi/tar.texi(UNREVISED,9432) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9432) @end quotation
+../tar_texi/tar.texi(UNREVISED,9432)
+../tar_texi/tar.texi(,9433)
+../tar_texi/tar.texi(,9434) @opindex blocking-factor
+../tar_texi/tar.texi(,9435) The data in an archive is grouped into blocks,
which are 512 bytes.
+../tar_texi/tar.texi(,9436) Blocks are read and written in whole number
multiples called
+../tar_texi/tar.texi(,9437) @dfn{records}. The number of blocks in a record
(i.e. the size of a
+../tar_texi/tar.texi(,9438) record in units of 512 bytes) is called the
@dfn{blocking factor}.
+../tar_texi/tar.texi(,9439) The @address@hidden (@option{-b
+../tar_texi/tar.texi(,9440) @var{512-size}}) option specifies the blocking
factor of an archive.
+../tar_texi/tar.texi(,9441) The default blocking factor is typically 20 (i.e.,
10240 bytes), but
+../tar_texi/tar.texi(,9442) can be specified at installation. To find out the
blocking factor of
+../tar_texi/tar.texi(,9443) an existing archive, use @samp{tar --list
address@hidden
+../tar_texi/tar.texi(,9444) This may not work on some devices.
+../tar_texi/tar.texi(,9445)
+../tar_texi/tar.texi(,9446) Records are separated by gaps, which waste space
on the archive media.
+../tar_texi/tar.texi(,9447) If you are archiving on magnetic tape, using a
larger blocking factor
+../tar_texi/tar.texi(,9448) (and therefore larger records) provides faster
throughput and allows you
+../tar_texi/tar.texi(,9449) to fit more data on a tape (because there are
fewer gaps). If you are
+../tar_texi/tar.texi(,9450) archiving on cartridge, a very large blocking
factor (say 126 or more)
+../tar_texi/tar.texi(,9451) greatly increases performance. A smaller blocking
factor, on the other
+../tar_texi/tar.texi(,9452) hand, may be useful when archiving small files, to
avoid archiving lots
+../tar_texi/tar.texi(,9453) of nulls as @command{tar} fills out the archive to
the end of the record.
+../tar_texi/tar.texi(,9454) In general, the ideal record size depends on the
size of the
+../tar_texi/tar.texi(,9455) inter-record gaps on the tape you are using, and
the average size of the
+../tar_texi/tar.texi(,9456) files you are archiving. @xref{create}, for
information on
+../tar_texi/tar.texi(,9457) writing archives.
+../tar_texi/tar.texi(,9458)
+../tar_texi/tar.texi(FIXME,9459) @allow-recursion
+../tar_texi/tar.texi(FIXME,9459) @quote-arg
+../tar_texi/tar.texi(FIXME,9459)
+../tar_texi/tar.texi(,9460)
+../tar_texi/tar.texi(,9461) Archives with blocking factors larger than 20
cannot be read
+../tar_texi/tar.texi(,9462) by very old versions of @command{tar}, or by some
newer versions
+../tar_texi/tar.texi(,9463) of @command{tar} running on old machines with
small address spaces.
+../tar_texi/tar.texi(GNUTAR,9464) With ../tar_texi/tar.texi(GNUTAR,9464)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,9464) , the blocking
factor of an archive is limited
+../tar_texi/tar.texi(,9465) only by the maximum record size of the device
containing the archive,
+../tar_texi/tar.texi(,9466) or by the amount of available virtual memory.
+../tar_texi/tar.texi(,9467)
+../tar_texi/tar.texi(,9468) Also, on some systems, not using adequate blocking
factors, as sometimes
+../tar_texi/tar.texi(,9469) imposed by the device drivers, may yield
unexpected diagnostics. For
+../tar_texi/tar.texi(,9470) example, this has been reported:
+../tar_texi/tar.texi(,9471)
+../tar_texi/tar.texi(,9472) @smallexample
+../tar_texi/tar.texi(,9473) Cannot write to /dev/dlt: Invalid argument
+../tar_texi/tar.texi(,9474) @end smallexample
+../tar_texi/tar.texi(,9475)
+../tar_texi/tar.texi(,9476) @noindent
+../tar_texi/tar.texi(,9477) In such cases, it sometimes happen that the
@command{tar} bundled by
+../tar_texi/tar.texi(GNUTAR,9478) the system is aware of block size
idiosyncrasies, while ../tar_texi/tar.texi(GNUTAR,9478) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9478)
+../tar_texi/tar.texi(,9479) requires an explicit specification for the block
size,
+../tar_texi/tar.texi(,9480) which it cannot guess. This yields some people to
consider
+../tar_texi/tar.texi(GNUTAR,9481) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9481) is misbehaving, because by
comparison,
+../tar_texi/tar.texi(,9482) @cite{the bundle @command{tar} works OK}. Adding
@address@hidden 256}},
+../tar_texi/tar.texi(,9483) for example, might resolve the problem.
+../tar_texi/tar.texi(,9484)
+../tar_texi/tar.texi(,9485) If you use a non-default blocking factor when you
create an archive, you
+../tar_texi/tar.texi(,9486) must specify the same blocking factor when you
modify that archive. Some
+../tar_texi/tar.texi(,9487) archive devices will also require you to specify
the blocking factor when
+../tar_texi/tar.texi(,9488) reading that archive, however this is not
typically the case. Usually, you
+../tar_texi/tar.texi(,9489) can use @option{--list} (@option{-t}) without
specifying a blocking address@hidden
+../tar_texi/tar.texi(,9490) reports a non-default record size and then lists
the archive members as
+../tar_texi/tar.texi(,9491) it would normally. To extract files from an
archive with a non-standard
+../tar_texi/tar.texi(,9492) blocking factor (particularly if you're not sure
what the blocking factor
+../tar_texi/tar.texi(,9493) is), you can usually use the
@option{--read-full-records} (@option{-B}) option while
+../tar_texi/tar.texi(,9494) specifying a blocking factor larger then the
blocking factor of the archive
+../tar_texi/tar.texi(,9495) (i.e. @samp{tar --extract --read-full-records
--blocking-factor=300}.
+../tar_texi/tar.texi(,9496) @xref{list}, for more information on the
@option{--list} (@option{-t})
+../tar_texi/tar.texi(,9497) operation. @xref{Reading}, for a more detailed
explanation of that option.
+../tar_texi/tar.texi(,9498)
+../tar_texi/tar.texi(,9499) @table @option
+../tar_texi/tar.texi(,9500) @item address@hidden
+../tar_texi/tar.texi(,9501) @itemx -b @var{number}
+../tar_texi/tar.texi(,9502) Specifies the blocking factor of an archive. Can
be used with any
+../tar_texi/tar.texi(,9503) operation, but is usually not necessary with
@option{--list} (@option{-t}).
+../tar_texi/tar.texi(,9504) @end table
+../tar_texi/tar.texi(,9505)
+../tar_texi/tar.texi(,9506) Device blocking
+../tar_texi/tar.texi(,9507)
+../tar_texi/tar.texi(,9508) @table @option
+../tar_texi/tar.texi(,9509) @item -b @var{blocks}
+../tar_texi/tar.texi(,9510) @itemx address@hidden
+../tar_texi/tar.texi(,9511) Set record size to @address@hidden * 512} bytes.
+../tar_texi/tar.texi(,9512)
+../tar_texi/tar.texi(,9513) This option is used to specify a @dfn{blocking
factor} for the archive.
+../tar_texi/tar.texi(,9514) When reading or writing the archive,
@command{tar}, will do reads and writes
+../tar_texi/tar.texi(,9515) of the archive in records of @address@hidden
bytes. This is true
+../tar_texi/tar.texi(,9516) even when the archive is compressed. Some devices
requires that all
+../tar_texi/tar.texi(,9517) write operations be a multiple of a certain size,
and so, @command{tar}
+../tar_texi/tar.texi(,9518) pads the archive out to the next record boundary.
+../tar_texi/tar.texi(,9519)
+../tar_texi/tar.texi(,9520) The default blocking factor is set when
@command{tar} is compiled, and is
+../tar_texi/tar.texi(,9521) typically 20. Blocking factors larger than 20
cannot be read by very
+../tar_texi/tar.texi(,9522) old versions of @command{tar}, or by some newer
versions of @command{tar}
+../tar_texi/tar.texi(,9523) running on old machines with small address spaces.
+../tar_texi/tar.texi(,9524)
+../tar_texi/tar.texi(,9525) With a magnetic tape, larger records give faster
throughput and fit
+../tar_texi/tar.texi(,9526) more data on a tape (because there are fewer
inter-record gaps).
+../tar_texi/tar.texi(,9527) If the archive is in a disk file or a pipe, you
may want to specify
+../tar_texi/tar.texi(,9528) a smaller blocking factor, since a large one will
result in a large
+../tar_texi/tar.texi(,9529) number of null bytes at the end of the archive.
+../tar_texi/tar.texi(,9530)
+../tar_texi/tar.texi(,9531) When writing cartridge or other streaming tapes, a
much larger
+../tar_texi/tar.texi(,9532) blocking factor (say 126 or more) will greatly
increase performance.
+../tar_texi/tar.texi(,9533) However, you must specify the same blocking factor
when reading or
+../tar_texi/tar.texi(,9534) updating the archive.
+../tar_texi/tar.texi(,9535)
+../tar_texi/tar.texi(,9536) Apparently, Exabyte drives have a physical block
size of 8K bytes.
+../tar_texi/tar.texi(,9537) If we choose our blocksize as a multiple of 8k
bytes, then the problem
+../tar_texi/tar.texi(,9538) seems to disappear. Id est, we are using block
size of 112 right
+../tar_texi/tar.texi(,9539) now, and we haven't had the problem since we
address@hidden
+../tar_texi/tar.texi(,9540)
+../tar_texi/tar.texi(GNUTAR,9541) With ../tar_texi/tar.texi(GNUTAR,9541)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,9541) the blocking
factor is limited only
+../tar_texi/tar.texi(,9542) by the maximum record size of the device
containing the archive, or by
+../tar_texi/tar.texi(,9543) the amount of available virtual memory.
+../tar_texi/tar.texi(,9544)
+../tar_texi/tar.texi(,9545) However, deblocking or reblocking is virtually
avoided in a special
+../tar_texi/tar.texi(,9546) case which often occurs in practice, but which
requires all the
+../tar_texi/tar.texi(,9547) following conditions to be simultaneously true:
+../tar_texi/tar.texi(,9548) @itemize @bullet
+../tar_texi/tar.texi(,9549) @item
+../tar_texi/tar.texi(,9550) the archive is subject to a compression option,
+../tar_texi/tar.texi(,9551) @item
+../tar_texi/tar.texi(,9552) the archive is not handled through standard input
or output, nor
+../tar_texi/tar.texi(,9553) redirected nor piped,
+../tar_texi/tar.texi(,9554) @item
+../tar_texi/tar.texi(,9555) the archive is directly handled to a local disk,
instead of any special
+../tar_texi/tar.texi(,9556) device,
+../tar_texi/tar.texi(,9557) @item
+../tar_texi/tar.texi(,9558) @option{--blocking-factor} is not explicitly
specified on the @command{tar}
+../tar_texi/tar.texi(,9559) invocation.
+../tar_texi/tar.texi(,9560) @end itemize
+../tar_texi/tar.texi(,9561)
+../tar_texi/tar.texi(,9562) If the output goes directly to a local disk, and
not through
+../tar_texi/tar.texi(,9563) stdout, then the last write is not extended to a
full record size.
+../tar_texi/tar.texi(,9564) Otherwise, reblocking occurs. Here are a few
other remarks on this
+../tar_texi/tar.texi(,9565) topic:
+../tar_texi/tar.texi(,9566)
+../tar_texi/tar.texi(,9567) @itemize @bullet
+../tar_texi/tar.texi(,9568)
+../tar_texi/tar.texi(,9569) @item
+../tar_texi/tar.texi(,9570) @command{gzip} will complain about trailing
garbage if asked to
+../tar_texi/tar.texi(,9571) uncompress a compressed archive on tape, there is
an option to turn
+../tar_texi/tar.texi(,9572) the message off, but it breaks the regularity of
simply having to use
+../tar_texi/tar.texi(,9573) @address@hidden -d} for decompression. It would
be nice if gzip was
+../tar_texi/tar.texi(,9574) silently ignoring any number of trailing zeros.
I'll ask Jean-loup
+../tar_texi/tar.texi(,9575) Gailly, by sending a copy of this message to him.
+../tar_texi/tar.texi(,9576)
+../tar_texi/tar.texi(,9577) @item
+../tar_texi/tar.texi(,9578) @command{compress} does not show this problem, but
as Jean-loup pointed
+../tar_texi/tar.texi(,9579) out to Michael, @samp{compress -d} silently adds
garbage after
+../tar_texi/tar.texi(,9580) the result of decompression, which tar ignores
because it already
+../tar_texi/tar.texi(,9581) recognized its end-of-file indicator. So this bug
may be safely
+../tar_texi/tar.texi(,9582) ignored.
+../tar_texi/tar.texi(,9583)
+../tar_texi/tar.texi(,9584) @item
+../tar_texi/tar.texi(,9585) @samp{gzip -d -q} will be silent about the
trailing zeros indeed,
+../tar_texi/tar.texi(,9586) but will still return an exit status of 2 which
tar reports in turn.
+../tar_texi/tar.texi(,9587) @command{tar} might ignore the exit status
returned, but I hate doing
+../tar_texi/tar.texi(,9588) that, as it weakens the protection @command{tar}
offers users against
+../tar_texi/tar.texi(,9589) other possible problems at decompression time. If
@command{gzip} was
+../tar_texi/tar.texi(,9590) silently skipping trailing zeros @emph{and} also
avoiding setting the
+../tar_texi/tar.texi(,9591) exit status in this innocuous case, that would
solve this situation.
+../tar_texi/tar.texi(,9592)
+../tar_texi/tar.texi(,9593) @item
+../tar_texi/tar.texi(,9594) @command{tar} should become more solid at not
stopping to read a pipe at
+../tar_texi/tar.texi(,9595) the first null block encountered. This
inelegantly breaks the pipe.
+../tar_texi/tar.texi(,9596) @command{tar} should rather drain the pipe out
before exiting itself.
+../tar_texi/tar.texi(,9597) @end itemize
+../tar_texi/tar.texi(,9598)
+../tar_texi/tar.texi(xopindex,9599) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,9599)
+../tar_texi/tar.texi(,9600) @item -i
+../tar_texi/tar.texi(,9601) @itemx --ignore-zeros
+../tar_texi/tar.texi(,9602) Ignore blocks of zeros in archive (means EOF).
+../tar_texi/tar.texi(,9603)
+../tar_texi/tar.texi(,9604) The @option{--ignore-zeros} (@option{-i}) option
causes @command{tar} to ignore blocks
+../tar_texi/tar.texi(,9605) of zeros in the archive. Normally a block of
zeros indicates the
+../tar_texi/tar.texi(,9606) end of the archive, but when reading a damaged
archive, or one which
+../tar_texi/tar.texi(,9607) was created by concatenating several archives
together, this option
+../tar_texi/tar.texi(,9608) allows @command{tar} to read the entire archive.
This option is not on
+../tar_texi/tar.texi(,9609) by default because many versions of @command{tar}
write garbage after
+../tar_texi/tar.texi(,9610) the zeroed blocks.
+../tar_texi/tar.texi(,9611)
+../tar_texi/tar.texi(,9612) Note that this option causes @command{tar} to read
to the end of the
+../tar_texi/tar.texi(,9613) archive file, which may sometimes avoid problems
when multiple files
+../tar_texi/tar.texi(,9614) are stored on a single physical tape.
+../tar_texi/tar.texi(,9615)
+../tar_texi/tar.texi(xopindex,9616) @opindex address@hidden, short
description}../tar_texi/tar.texi(xopindex,9616)
+../tar_texi/tar.texi(,9617) @item -B
+../tar_texi/tar.texi(,9618) @itemx --read-full-records
+../tar_texi/tar.texi(,9619) Reblock as we read (for reading 4.2BSD pipes).
+../tar_texi/tar.texi(,9620)
+../tar_texi/tar.texi(,9621) If @option{--read-full-records} is used,
@command{tar}
+../tar_texi/tar.texi(,9622) will not panic if an attempt to read a record from
the archive does
+../tar_texi/tar.texi(,9623) not return a full record. Instead, @command{tar}
will keep reading
+../tar_texi/tar.texi(,9624) until it has obtained a full
+../tar_texi/tar.texi(,9625) record.
+../tar_texi/tar.texi(,9626)
+../tar_texi/tar.texi(,9627) This option is turned on by default when
@command{tar} is reading
+../tar_texi/tar.texi(,9628) an archive from standard input, or from a remote
machine. This is
+../tar_texi/tar.texi(,9629) because on BSD Unix systems, a read of a pipe will
return however
+../tar_texi/tar.texi(,9630) much happens to be in the pipe, even if it is less
than @command{tar}
+../tar_texi/tar.texi(,9631) requested. If this option was not used,
@command{tar} would fail as
+../tar_texi/tar.texi(,9632) soon as it read an incomplete record from the pipe.
+../tar_texi/tar.texi(,9633)
+../tar_texi/tar.texi(,9634) This option is also useful with the commands for
updating an archive.
+../tar_texi/tar.texi(,9635)
+../tar_texi/tar.texi(,9636) @end table
+../tar_texi/tar.texi(,9637)
+../tar_texi/tar.texi(,9638) Tape blocking
+../tar_texi/tar.texi(,9639)
+../tar_texi/tar.texi(FIXME,9640) @allow-recursion
+../tar_texi/tar.texi(FIXME,9640) @quote-arg
+../tar_texi/tar.texi(FIXME,9640)
+../tar_texi/tar.texi(,9641)
+../tar_texi/tar.texi(,9642) @cindex blocking factor
+../tar_texi/tar.texi(,9643) @cindex tape blocking
+../tar_texi/tar.texi(,9644)
+../tar_texi/tar.texi(,9645) When handling various tapes or cartridges, you
have to take care of
+../tar_texi/tar.texi(,9646) selecting a proper blocking, that is, the number
of disk blocks you
+../tar_texi/tar.texi(,9647) put together as a single tape block on the tape,
without intervening
+../tar_texi/tar.texi(,9648) tape gaps. A @dfn{tape gap} is a small landing
area on the tape
+../tar_texi/tar.texi(,9649) with no information on it, used for decelerating
the tape to a
+../tar_texi/tar.texi(,9650) full stop, and for later regaining the reading or
writing speed.
+../tar_texi/tar.texi(,9651) When the tape driver starts reading a record, the
record has to
+../tar_texi/tar.texi(,9652) be read whole without stopping, as a tape gap is
needed to stop the
+../tar_texi/tar.texi(,9653) tape motion without loosing information.
+../tar_texi/tar.texi(,9654)
+../tar_texi/tar.texi(,9655) @cindex Exabyte blocking
+../tar_texi/tar.texi(,9656) @cindex DAT blocking
+../tar_texi/tar.texi(,9657) Using higher blocking (putting more disk blocks
per tape block) will use
+../tar_texi/tar.texi(,9658) the tape more efficiently as there will be less
tape gaps. But reading
+../tar_texi/tar.texi(,9659) such tapes may be more difficult for the system,
as more memory will be
+../tar_texi/tar.texi(,9660) required to receive at once the whole record.
Further, if there is a
+../tar_texi/tar.texi(,9661) reading error on a huge record, this is less
likely that the system will
+../tar_texi/tar.texi(,9662) succeed in recovering the information. So,
blocking should not be too
+../tar_texi/tar.texi(,9663) low, nor it should be too high. @command{tar}
uses by default a blocking of
+../tar_texi/tar.texi(,9664) 20 for historical reasons, and it does not really
matter when reading or
+../tar_texi/tar.texi(,9665) writing to disk. Current tape technology would
easily accommodate higher
+../tar_texi/tar.texi(,9666) blockings. Sun recommends a blocking of 126 for
Exabytes and 96 for DATs.
+../tar_texi/tar.texi(,9667) We were told that for some DLT drives, the
blocking should be a multiple
+../tar_texi/tar.texi(,9668) of 4Kb, preferably 64Kb (@address@hidden 128}}) or
256 for decent performance.
+../tar_texi/tar.texi(,9669) Other manufacturers may use different
recommendations for the same tapes.
+../tar_texi/tar.texi(,9670) This might also depends of the buffering
techniques used inside modern
+../tar_texi/tar.texi(,9671) tape controllers. Some imposes a minimum
blocking, or a maximum blocking.
+../tar_texi/tar.texi(,9672) Others request blocking to be some exponent of two.
+../tar_texi/tar.texi(,9673)
+../tar_texi/tar.texi(,9674) So, there is no fixed rule for blocking. But
blocking at read time
+../tar_texi/tar.texi(,9675) should ideally be the same as blocking used at
write time. At one place
+../tar_texi/tar.texi(,9676) I know, with a wide variety of equipment, they
found it best to use a
+../tar_texi/tar.texi(,9677) blocking of 32 to guarantee that their tapes are
fully interchangeable.
+../tar_texi/tar.texi(,9678)
+../tar_texi/tar.texi(,9679) I was also told that, for recycled tapes, prior
erasure (by the same
+../tar_texi/tar.texi(,9680) drive unit that will be used to create the
archives) sometimes lowers
+../tar_texi/tar.texi(,9681) the error rates observed at rewriting time.
+../tar_texi/tar.texi(,9682)
+../tar_texi/tar.texi(,9683) I might also use @option{--number-blocks} instead
of
+../tar_texi/tar.texi(,9684) @option{--block-number}, so @option{--block} will
then expand to
+../tar_texi/tar.texi(,9685) @option{--blocking-factor} unambiguously.
+../tar_texi/tar.texi(,9686)
+../tar_texi/tar.texi(,9687) @node Many
+../tar_texi/tar.texi(,9688) @section Many Archives on One Tape
+../tar_texi/tar.texi(,9689)
+../tar_texi/tar.texi(FIXME,9690) @allow-recursion
+../tar_texi/tar.texi(FIXME,9690) @quote-arg
+../tar_texi/tar.texi(FIXME,9690)
+../tar_texi/tar.texi(,9691)
+../tar_texi/tar.texi(,9692) @findex ntape @r{device}
+../tar_texi/tar.texi(,9693) Most tape devices have two entries in the
@file{/dev} directory, or
+../tar_texi/tar.texi(,9694) entries that come in pairs, which differ only in
the minor number for
+../tar_texi/tar.texi(,9695) this device. Let's take for example
@file{/dev/tape}, which often
+../tar_texi/tar.texi(,9696) points to the only or usual tape device of a given
system. There might
+../tar_texi/tar.texi(,9697) be a corresponding @file{/dev/nrtape} or
@file{/dev/ntape}. The simpler
+../tar_texi/tar.texi(,9698) name is the @emph{rewinding} version of the
device, while the name
+../tar_texi/tar.texi(,9699) having @samp{nr} in it is the @emph{no rewinding}
version of the same
+../tar_texi/tar.texi(,9700) device.
+../tar_texi/tar.texi(,9701)
+../tar_texi/tar.texi(,9702) A rewinding tape device will bring back the tape
to its beginning point
+../tar_texi/tar.texi(,9703) automatically when this device is opened or
closed. Since @command{tar}
+../tar_texi/tar.texi(,9704) opens the archive file before using it and closes
it afterwards, this
+../tar_texi/tar.texi(,9705) means that a simple:
+../tar_texi/tar.texi(,9706)
+../tar_texi/tar.texi(,9707) @smallexample
+../tar_texi/tar.texi(,9708) $ @kbd{tar cf /dev/tape @var{directory}}
+../tar_texi/tar.texi(,9709) @end smallexample
+../tar_texi/tar.texi(,9710)
+../tar_texi/tar.texi(,9711) @noindent
+../tar_texi/tar.texi(,9712) will reposition the tape to its beginning both
prior and after saving
+../tar_texi/tar.texi(,9713) @var{directory} contents to it, thus erasing prior
tape contents and
+../tar_texi/tar.texi(,9714) making it so that any subsequent write operation
will destroy what has
+../tar_texi/tar.texi(,9715) just been saved.
+../tar_texi/tar.texi(,9716)
+../tar_texi/tar.texi(,9717) @cindex tape positioning
+../tar_texi/tar.texi(,9718) So, a rewinding device is normally meant to hold
one and only one file.
+../tar_texi/tar.texi(,9719) If you want to put more than one @command{tar}
archive on a given tape, you
+../tar_texi/tar.texi(,9720) will need to avoid using the rewinding version of
the tape device. You
+../tar_texi/tar.texi(,9721) will also have to pay special attention to tape
positioning. Errors in
+../tar_texi/tar.texi(,9722) positioning may overwrite the valuable data
already on your tape. Many
+../tar_texi/tar.texi(,9723) people, burnt by past experiences, will only use
rewinding devices and
+../tar_texi/tar.texi(,9724) limit themselves to one file per tape, precisely
to avoid the risk of
+../tar_texi/tar.texi(,9725) such errors. Be fully aware that writing at the
wrong position on a
+../tar_texi/tar.texi(,9726) tape loses all information past this point and
most probably until the
+../tar_texi/tar.texi(,9727) end of the tape, and this destroyed information
@emph{cannot} be
+../tar_texi/tar.texi(,9728) recovered.
+../tar_texi/tar.texi(,9729)
+../tar_texi/tar.texi(,9730) To save @var{directory-1} as a first archive at
the beginning of a
+../tar_texi/tar.texi(,9731) tape, and leave that tape ready for a second
archive, you should use:
+../tar_texi/tar.texi(,9732)
+../tar_texi/tar.texi(,9733) @smallexample
+../tar_texi/tar.texi(,9734) $ @kbd{mt -f /dev/nrtape rewind}
+../tar_texi/tar.texi(,9735) $ @kbd{tar cf /dev/nrtape @var{directory-1}}
+../tar_texi/tar.texi(,9736) @end smallexample
+../tar_texi/tar.texi(,9737)
+../tar_texi/tar.texi(,9738) @cindex tape marks
+../tar_texi/tar.texi(,9739) @dfn{Tape marks} are special magnetic patterns
written on the tape
+../tar_texi/tar.texi(,9740) media, which are later recognizable by the reading
hardware. These
+../tar_texi/tar.texi(,9741) marks are used after each file, when there are
many on a single tape.
+../tar_texi/tar.texi(,9742) An empty file (that is to say, two tape marks in a
row) signal the
+../tar_texi/tar.texi(,9743) logical end of the tape, after which no file
exist. Usually,
+../tar_texi/tar.texi(,9744) non-rewinding tape device drivers will react to
the close request issued
+../tar_texi/tar.texi(,9745) by @command{tar} by first writing two tape marks
after your archive, and by
+../tar_texi/tar.texi(,9746) backspacing over one of these. So, if you remove
the tape at that time
+../tar_texi/tar.texi(,9747) from the tape drive, it is properly terminated.
But if you write
+../tar_texi/tar.texi(,9748) another file at the current position, the second
tape mark will be
+../tar_texi/tar.texi(,9749) erased by the new information, leaving only one
tape mark between files.
+../tar_texi/tar.texi(,9750)
+../tar_texi/tar.texi(,9751) So, you may now save @var{directory-2} as a second
archive after the
+../tar_texi/tar.texi(,9752) first on the same tape by issuing the command:
+../tar_texi/tar.texi(,9753)
+../tar_texi/tar.texi(,9754) @smallexample
+../tar_texi/tar.texi(,9755) $ @kbd{tar cf /dev/nrtape @var{directory-2}}
+../tar_texi/tar.texi(,9756) @end smallexample
+../tar_texi/tar.texi(,9757)
+../tar_texi/tar.texi(,9758) @noindent
+../tar_texi/tar.texi(,9759) and so on for all the archives you want to put on
the same tape.
+../tar_texi/tar.texi(,9760)
+../tar_texi/tar.texi(,9761) Another usual case is that you do not write all
the archives the same
+../tar_texi/tar.texi(,9762) day, and you need to remove and store the tape
between two archive
+../tar_texi/tar.texi(,9763) sessions. In general, you must remember how many
files are already
+../tar_texi/tar.texi(,9764) saved on your tape. Suppose your tape already has
16 files on it, and
+../tar_texi/tar.texi(,9765) that you are ready to write the 17th. You have to
take care of skipping
+../tar_texi/tar.texi(,9766) the first 16 tape marks before saving
@var{directory-17}, say, by using
+../tar_texi/tar.texi(,9767) these commands:
+../tar_texi/tar.texi(,9768)
+../tar_texi/tar.texi(,9769) @smallexample
+../tar_texi/tar.texi(,9770) $ @kbd{mt -f /dev/nrtape rewind}
+../tar_texi/tar.texi(,9771) $ @kbd{mt -f /dev/nrtape fsf 16}
+../tar_texi/tar.texi(,9772) $ @kbd{tar cf /dev/nrtape @var{directory-17}}
+../tar_texi/tar.texi(,9773) @end smallexample
+../tar_texi/tar.texi(,9774)
+../tar_texi/tar.texi(,9775) In all the previous examples, we put aside
blocking considerations, but
+../tar_texi/tar.texi(,9776) you should do the proper things for that as well.
@xref{Blocking}.
+../tar_texi/tar.texi(,9777)
+../tar_texi/tar.texi(,9778) @menu
+../tar_texi/tar.texi(,9779) * Tape Positioning:: Tape Positions and
Tape Marks
+../tar_texi/tar.texi(,9780) * mt:: The @command{mt}
Utility
+../tar_texi/tar.texi(,9781) @end menu
+../tar_texi/tar.texi(,9782)
+../tar_texi/tar.texi(,9783) @node Tape Positioning
+../tar_texi/tar.texi(,9784) @subsection Tape Positions and Tape Marks
+../tar_texi/tar.texi(UNREVISED,9785) @quotation
+../tar_texi/tar.texi(UNREVISED,9785) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9785) @end quotation
+../tar_texi/tar.texi(UNREVISED,9785)
+../tar_texi/tar.texi(,9786)
+../tar_texi/tar.texi(,9787) Just as archives can store more than one file from
the file system,
+../tar_texi/tar.texi(,9788) tapes can store more than one archive file. To
keep track of where
+../tar_texi/tar.texi(,9789) archive files (or any other type of file stored on
tape) begin and
+../tar_texi/tar.texi(,9790) end, tape archive devices write magnetic @dfn{tape
marks} on the
+../tar_texi/tar.texi(,9791) archive media. Tape drives write one tape mark
between files,
+../tar_texi/tar.texi(,9792) two at the end of all the file entries.
+../tar_texi/tar.texi(,9793)
+../tar_texi/tar.texi(,9794) If you think of data as a series of records
"rrrr"'s, and tape marks as
+../tar_texi/tar.texi(,9795) "*"'s, a tape might look like the following:
+../tar_texi/tar.texi(,9796)
+../tar_texi/tar.texi(,9797) @smallexample
+../tar_texi/tar.texi(,9798)
rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
+../tar_texi/tar.texi(,9799) @end smallexample
+../tar_texi/tar.texi(,9800)
+../tar_texi/tar.texi(,9801) Tape devices read and write tapes using a
read/write @dfn{tape
+../tar_texi/tar.texi(,9802) head}---a physical part of the device which can
only access one
+../tar_texi/tar.texi(,9803) point on the tape at a time. When you use
@command{tar} to read or
+../tar_texi/tar.texi(,9804) write archive data from a tape device, the device
will begin reading
+../tar_texi/tar.texi(,9805) or writing from wherever on the tape the tape head
happens to be,
+../tar_texi/tar.texi(,9806) regardless of which archive or what part of the
archive the tape
+../tar_texi/tar.texi(,9807) head is on. Before writing an archive, you should
make sure that no
+../tar_texi/tar.texi(,9808) data on the tape will be overwritten (unless it is
no longer needed).
+../tar_texi/tar.texi(,9809) Before reading an archive, you should make sure
the tape head is at
+../tar_texi/tar.texi(,9810) the beginning of the archive you want to read.
You can do it manually
+../tar_texi/tar.texi(,9811) via @code{mt} utility (@pxref{mt}). The
@code{restore} script does
+../tar_texi/tar.texi(,9812) that automatically (@pxref{Scripted Restoration}).
+../tar_texi/tar.texi(,9813)
+../tar_texi/tar.texi(,9814) If you want to add new archive file entries to a
tape, you should
+../tar_texi/tar.texi(,9815) advance the tape to the end of the existing file
entries, backspace
+../tar_texi/tar.texi(,9816) over the last tape mark, and write the new archive
file. If you were
+../tar_texi/tar.texi(,9817) to add two archives to the example above, the tape
might look like the
+../tar_texi/tar.texi(,9818) following:
+../tar_texi/tar.texi(,9819)
+../tar_texi/tar.texi(,9820) @smallexample
+../tar_texi/tar.texi(,9821)
rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
+../tar_texi/tar.texi(,9822) @end smallexample
+../tar_texi/tar.texi(,9823)
+../tar_texi/tar.texi(,9824) @node mt
+../tar_texi/tar.texi(,9825) @subsection The @command{mt} Utility
+../tar_texi/tar.texi(UNREVISED,9826) @quotation
+../tar_texi/tar.texi(UNREVISED,9826) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,9826) @end quotation
+../tar_texi/tar.texi(UNREVISED,9826)
+../tar_texi/tar.texi(,9827)
+../tar_texi/tar.texi(FIXME,9829) @allow-recursion
+../tar_texi/tar.texi(FIXME,9829) @quote-arg
+../tar_texi/tar.texi(FIXME,9829)
+../tar_texi/tar.texi(,9830) @xref{Blocking Factor}.
+../tar_texi/tar.texi(,9831)
+../tar_texi/tar.texi(,9832) You can use the @command{mt} utility to advance or
rewind a tape past a
+../tar_texi/tar.texi(,9833) specified number of archive files on the tape.
This will allow you
+../tar_texi/tar.texi(,9834) to move to the beginning of an archive before
extracting or reading
+../tar_texi/tar.texi(,9835) it, or to the end of all the archives before
writing a new one.
+../tar_texi/tar.texi(FIXME,9837) @allow-recursion
+../tar_texi/tar.texi(FIXME,9837) @quote-arg
+../tar_texi/tar.texi(FIXME,9837)
+../tar_texi/tar.texi(,9838)
+../tar_texi/tar.texi(,9839) The syntax of the @command{mt} command is:
+../tar_texi/tar.texi(,9840)
+../tar_texi/tar.texi(,9841) @smallexample
+../tar_texi/tar.texi(,9842) @kbd{mt [-f @var{tapename}] @var{operation}
address@hidden
+../tar_texi/tar.texi(,9843) @end smallexample
+../tar_texi/tar.texi(,9844)
+../tar_texi/tar.texi(,9845) where @var{tapename} is the name of the tape
device, @var{number} is
+../tar_texi/tar.texi(,9846) the number of times an operation is performed
(with a default of one),
+../tar_texi/tar.texi(,9847) and @var{operation} is one of the following:
+../tar_texi/tar.texi(,9848)
+../tar_texi/tar.texi(FIXME,9849) @allow-recursion
+../tar_texi/tar.texi(FIXME,9849) @quote-arg
+../tar_texi/tar.texi(FIXME,9849)
+../tar_texi/tar.texi(,9850)
+../tar_texi/tar.texi(,9851) @table @option
+../tar_texi/tar.texi(,9852) @item eof
+../tar_texi/tar.texi(,9853) @itemx weof
+../tar_texi/tar.texi(,9854) Writes @var{number} tape marks at the current
position on the tape.
+../tar_texi/tar.texi(,9855)
+../tar_texi/tar.texi(,9856) @item fsf
+../tar_texi/tar.texi(,9857) Moves tape position forward @var{number} files.
+../tar_texi/tar.texi(,9858)
+../tar_texi/tar.texi(,9859) @item bsf
+../tar_texi/tar.texi(,9860) Moves tape position back @var{number} files.
+../tar_texi/tar.texi(,9861)
+../tar_texi/tar.texi(,9862) @item rewind
+../tar_texi/tar.texi(,9863) Rewinds the tape. (Ignores @var{number}).
+../tar_texi/tar.texi(,9864)
+../tar_texi/tar.texi(,9865) @item offline
+../tar_texi/tar.texi(,9866) @itemx rewoff1
+../tar_texi/tar.texi(,9867) Rewinds the tape and takes the tape device
off-line. (Ignores @var{number}).
+../tar_texi/tar.texi(,9868)
+../tar_texi/tar.texi(,9869) @item status
+../tar_texi/tar.texi(,9870) Prints status information about the tape unit.
+../tar_texi/tar.texi(,9871)
+../tar_texi/tar.texi(,9872) @end table
+../tar_texi/tar.texi(,9873)
+../tar_texi/tar.texi(FIXME,9874) @allow-recursion
+../tar_texi/tar.texi(FIXME,9874) @quote-arg
+../tar_texi/tar.texi(FIXME,9874)
+../tar_texi/tar.texi(,9875)
+../tar_texi/tar.texi(,9876) If you don't specify a @var{tapename},
@command{mt} uses the environment
+../tar_texi/tar.texi(,9877) variable @env{TAPE}; if @env{TAPE} is not set,
@command{mt} will use
+../tar_texi/tar.texi(,9878) the default device specified in your
@file{sys/mtio.h} file
+../tar_texi/tar.texi(,9879) (@code{DEFTAPE} variable). If this is not
defined, the program will
+../tar_texi/tar.texi(,9880) display a descriptive error message and exit with
code 1.
+../tar_texi/tar.texi(,9881)
+../tar_texi/tar.texi(,9882) @command{mt} returns a 0 exit status when the
operation(s) were
+../tar_texi/tar.texi(,9883) successful, 1 if the command was unrecognized, and
2 if an operation
+../tar_texi/tar.texi(,9884) failed.
+../tar_texi/tar.texi(,9885)
+../tar_texi/tar.texi(,9886) @node Using Multiple Tapes
+../tar_texi/tar.texi(,9887) @section Using Multiple Tapes
+../tar_texi/tar.texi(,9888)
+../tar_texi/tar.texi(,9889) Often you might want to write a large archive, one
larger than will fit
+../tar_texi/tar.texi(,9890) on the actual tape you are using. In such a case,
you can run multiple
+../tar_texi/tar.texi(,9891) @command{tar} commands, but this can be
inconvenient, particularly if you
+../tar_texi/tar.texi(,9892) are using options like @address@hidden or dumping
entire file systems.
+../tar_texi/tar.texi(,9893) Therefore, @command{tar} provides a special mode
for creating
+../tar_texi/tar.texi(,9894) multi-volume archives.
+../tar_texi/tar.texi(,9895)
+../tar_texi/tar.texi(,9896) @dfn{Multi-volume} archive is a single
@command{tar} archive, stored
+../tar_texi/tar.texi(,9897) on several media volumes of fixed size. Although
in this section we will
+../tar_texi/tar.texi(,9898) often call @samp{volume} a @dfn{tape}, there is
absolutely no
+../tar_texi/tar.texi(,9899) requirement for multi-volume archives to be stored
on tapes. Instead,
+../tar_texi/tar.texi(,9900) they can use whatever media type the user finds
convenient, they can
+../tar_texi/tar.texi(,9901) even be located on files.
+../tar_texi/tar.texi(,9902)
+../tar_texi/tar.texi(GNUTAR,9903) When creating a multi-volume arvhive,
../tar_texi/tar.texi(GNUTAR,9903) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9903) continues to fill
+../tar_texi/tar.texi(,9904) current volume until it runs out of space, then it
switches to
+../tar_texi/tar.texi(,9905) next volume (usually the operator is queried to
replace the tape on
+../tar_texi/tar.texi(,9906) this point), and continues working on the new
volume. This operation
+../tar_texi/tar.texi(GNUTAR,9907) continues untill all requested files are
dumped. If ../tar_texi/tar.texi(GNUTAR,9907) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9907) detects
+../tar_texi/tar.texi(,9908) end of media while dumping a file, such a file is
archived in split
+../tar_texi/tar.texi(,9909) form. Some very big files can even be split
across several volumes.
+../tar_texi/tar.texi(,9910)
+../tar_texi/tar.texi(GNUTAR,9911) Each volume is itself a valid
../tar_texi/tar.texi(GNUTAR,9911) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9911) archive, so it can be read
+../tar_texi/tar.texi(,9912) without any special options. Consequently any
file member residing
+../tar_texi/tar.texi(,9913) entirely on one volume can be extracted or
otherwise operated upon
+../tar_texi/tar.texi(,9914) without needing the other volume. Sure enough, to
extract a split
+../tar_texi/tar.texi(,9915) member you would need all volumes its parts reside
on.
+../tar_texi/tar.texi(,9916)
+../tar_texi/tar.texi(,9917) Multi-volume archives suffer from several
limitations. In particular,
+../tar_texi/tar.texi(,9918) they cannot be compressed.
+../tar_texi/tar.texi(,9919)
+../tar_texi/tar.texi(GNUTAR,9920) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,9920) is able to create multi-volume
archives of two formats
+../tar_texi/tar.texi(,9921) (@pxref{Formats}): @samp{GNU} and @samp{POSIX}.
+../tar_texi/tar.texi(,9922)
+../tar_texi/tar.texi(,9923) @menu
+../tar_texi/tar.texi(,9924) * Multi-Volume Archives:: Archives Longer
than One Tape or Disk
+../tar_texi/tar.texi(,9925) * Tape Files:: Tape Files
+../tar_texi/tar.texi(,9926) * Tarcat:: Concatenate
Volumes into a Single Archive
+../tar_texi/tar.texi(,9927)
+../tar_texi/tar.texi(,9928) @end menu
+../tar_texi/tar.texi(,9929)
+../tar_texi/tar.texi(,9930) @node Multi-Volume Archives
+../tar_texi/tar.texi(,9931) @subsection Archives Longer than One Tape or Disk
+../tar_texi/tar.texi(,9932) @cindex Multi-volume archives
+../tar_texi/tar.texi(,9933)
+../tar_texi/tar.texi(,9934) @opindex multi-volume
+../tar_texi/tar.texi(,9935) To create an archive that is larger than will fit
on a single unit of
+../tar_texi/tar.texi(,9936) the media, use the @option{--multi-volume}
(@option{-M}) option in conjunction with
+../tar_texi/tar.texi(,9937) the @option{--create} option (@pxref{create}). A
@dfn{multi-volume}
+../tar_texi/tar.texi(,9938) archive can be manipulated like any other archive
(provided the
+../tar_texi/tar.texi(,9939) @option{--multi-volume} option is specified), but
is stored on more
+../tar_texi/tar.texi(,9940) than one tape or disk.
+../tar_texi/tar.texi(,9941)
+../tar_texi/tar.texi(,9942) When you specify @option{--multi-volume},
@command{tar} does not report an
+../tar_texi/tar.texi(,9943) error when it comes to the end of an archive
volume (when reading), or
+../tar_texi/tar.texi(,9944) the end of the media (when writing). Instead, it
prompts you to load
+../tar_texi/tar.texi(,9945) a new storage volume. If the archive is on a
magnetic tape, you
+../tar_texi/tar.texi(,9946) should change tapes when you see the prompt; if
the archive is on a
+../tar_texi/tar.texi(,9947) floppy disk, you should change disks; etc.
+../tar_texi/tar.texi(,9948)
+../tar_texi/tar.texi(,9949) @table @option
+../tar_texi/tar.texi(,9950) @item --multi-volume
+../tar_texi/tar.texi(,9951) @itemx -M
+../tar_texi/tar.texi(,9952) Creates a multi-volume archive, when used in
conjunction with
+../tar_texi/tar.texi(,9953) @option{--create} (@option{-c}). To perform any
other operation on a multi-volume
+../tar_texi/tar.texi(,9954) archive, specify @option{--multi-volume} in
conjunction with that
+../tar_texi/tar.texi(,9955) operation.
+../tar_texi/tar.texi(,9956) For example:
+../tar_texi/tar.texi(,9957)
+../tar_texi/tar.texi(,9958) @smallexample
+../tar_texi/tar.texi(,9959) $ @kbd{tar --create --multi-volume
--file=/dev/tape @var{files}}
+../tar_texi/tar.texi(,9960) @end smallexample
+../tar_texi/tar.texi(,9961) @end table
+../tar_texi/tar.texi(,9962)
+../tar_texi/tar.texi(,9963) The method @command{tar} uses to detect end of
tape is not perfect, and
+../tar_texi/tar.texi(,9964) fails on some operating systems or on some
devices. If @command{tar}
+../tar_texi/tar.texi(,9965) cannot detect the end of the tape itself, you can
use
+../tar_texi/tar.texi(,9966) @option{--tape-length} option to inform it about
the capacity of the
+../tar_texi/tar.texi(,9967) tape:
+../tar_texi/tar.texi(,9968)
+../tar_texi/tar.texi(,9969) @anchor{tape-length}
+../tar_texi/tar.texi(,9970) @table @option
+../tar_texi/tar.texi(,9971) @opindex tape-length
+../tar_texi/tar.texi(,9972) @item address@hidden
+../tar_texi/tar.texi(,9973) @itemx -L @var{size}
+../tar_texi/tar.texi(,9974) Set maximum length of a volume. The @var{size}
argument should then
+../tar_texi/tar.texi(,9975) be the usable size of the tape in units of 1024
bytes. This option
+../tar_texi/tar.texi(,9976) selects @option{--multi-volume} automatically.
For example:
+../tar_texi/tar.texi(,9977)
+../tar_texi/tar.texi(,9978) @smallexample
+../tar_texi/tar.texi(,9979) $ @kbd{tar --create --tape-length=41943040
--file=/dev/tape @var{files}}
+../tar_texi/tar.texi(,9980) @end smallexample
+../tar_texi/tar.texi(,9981) @end table
+../tar_texi/tar.texi(,9982)
+../tar_texi/tar.texi(,9983) @anchor{change volume prompt}
+../tar_texi/tar.texi(GNUTAR,9984) When ../tar_texi/tar.texi(GNUTAR,9984)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,9984) comes to the end
of a storage media, it asks you to
+../tar_texi/tar.texi(,9985) change the volume. The built-in prompt for POSIX
locale
+../tar_texi/tar.texi(GNUTAR,9986) address@hidden you run @acronym{GNU}
@command{tar} under a different locale, the
+../tar_texi/tar.texi(,9987) translation to the locale's language will be
used.}:
+../tar_texi/tar.texi(,9988)
+../tar_texi/tar.texi(,9989) @smallexample
+../tar_texi/tar.texi(,9990) Prepare volume address@hidden for address@hidden'
and hit return:
+../tar_texi/tar.texi(,9991) @end smallexample
+../tar_texi/tar.texi(,9992)
+../tar_texi/tar.texi(,9993) @noindent
+../tar_texi/tar.texi(,9994) where @var{n} is the ordinal number of the volume
to be created and
+../tar_texi/tar.texi(,9995) @var{archive} is archive file or device name.
+../tar_texi/tar.texi(,9996)
+../tar_texi/tar.texi(,9997) When prompting for a new tape, @command{tar}
accepts any of the following
+../tar_texi/tar.texi(,9998) responses:
+../tar_texi/tar.texi(,9999)
+../tar_texi/tar.texi(,10000) @table @kbd
+../tar_texi/tar.texi(,10001) @item ?
+../tar_texi/tar.texi(,10002) Request @command{tar} to explain possible
responses
+../tar_texi/tar.texi(,10003) @item q
+../tar_texi/tar.texi(,10004) Request @command{tar} to exit immediately.
+../tar_texi/tar.texi(,10005) @item n @var{file-name}
+../tar_texi/tar.texi(,10006) Request @command{tar} to write the next volume on
the file @var{file-name}.
+../tar_texi/tar.texi(,10007) @item !
+../tar_texi/tar.texi(,10008) Request @command{tar} to run a subshell. This
option can be disabled
+../tar_texi/tar.texi(,10009) by giving @option{--restrict} command line option
to
+../tar_texi/tar.texi(,10010) @address@hidden@xref{--restrict}, for more
information about
+../tar_texi/tar.texi(,10011) this option}.
+../tar_texi/tar.texi(,10012) @item y
+../tar_texi/tar.texi(,10013) Request @command{tar} to begin writing the next
volume.
+../tar_texi/tar.texi(,10014) @end table
+../tar_texi/tar.texi(,10015)
+../tar_texi/tar.texi(,10016) (You should only type @samp{y} after you have
changed the tape;
+../tar_texi/tar.texi(,10017) otherwise @command{tar} will write over the
volume it just finished.)
+../tar_texi/tar.texi(,10018)
+../tar_texi/tar.texi(,10019) @cindex Volume number file
+../tar_texi/tar.texi(,10020) @cindex volno file
+../tar_texi/tar.texi(,10021) @anchor{volno-file}
+../tar_texi/tar.texi(,10022) @opindex volno-file
+../tar_texi/tar.texi(,10023) The volume number used by @command{tar} in its
tape-changing prompt
+../tar_texi/tar.texi(,10024) can be changed; if you give the
+../tar_texi/tar.texi(,10025) @address@hidden option, then
+../tar_texi/tar.texi(,10026) @var{file-of-number} should be an unexisting file
to be created, or
+../tar_texi/tar.texi(,10027) else, a file already containing a decimal number.
That number will be
+../tar_texi/tar.texi(,10028) used as the volume number of the first volume
written. When
+../tar_texi/tar.texi(,10029) @command{tar} is finished, it will rewrite the
file with the
+../tar_texi/tar.texi(,10030) now-current volume number. (This does not change
the volume number
+../tar_texi/tar.texi(,10031) written on a tape label, as per @ref{label}, it
@emph{only} affects
+../tar_texi/tar.texi(,10032) the number used in the prompt.)
+../tar_texi/tar.texi(,10033)
+../tar_texi/tar.texi(,10034) @cindex End-of-archive info script
+../tar_texi/tar.texi(,10035) @cindex Info script
+../tar_texi/tar.texi(,10036) @anchor{info-script}
+../tar_texi/tar.texi(,10037) @opindex info-script
+../tar_texi/tar.texi(,10038) @opindex new-volume-script
+../tar_texi/tar.texi(,10039) If you want more elaborate behavior than this,
you can write a special
+../tar_texi/tar.texi(,10040) @dfn{new volume script}, that will be responsible
for changing the
+../tar_texi/tar.texi(,10041) volume, and instruct @command{tar} to use it
instead of its normal
+../tar_texi/tar.texi(,10042) prompting procedure:
+../tar_texi/tar.texi(,10043)
+../tar_texi/tar.texi(,10044) @table @option
+../tar_texi/tar.texi(,10045) @item address@hidden
+../tar_texi/tar.texi(,10046) @itemx address@hidden
+../tar_texi/tar.texi(,10047) @itemx -F @var{script-name}
+../tar_texi/tar.texi(,10048) Specify the full name of the volume script to
use. The script can be
+../tar_texi/tar.texi(,10049) used to eject cassettes, or to broadcast messages
such as
+../tar_texi/tar.texi(,10050) @samp{Someone please come change my tape} when
performing unattended
+../tar_texi/tar.texi(,10051) backups.
+../tar_texi/tar.texi(,10052) @end table
+../tar_texi/tar.texi(,10053)
+../tar_texi/tar.texi(,10054) The @var{script-name} is executed without any
command line
+../tar_texi/tar.texi(,10055) arguments. It inherits @command{tar}'s shell
environment.
+../tar_texi/tar.texi(,10056) Additional data is passed to it via the following
+../tar_texi/tar.texi(,10057) environment variables:
+../tar_texi/tar.texi(,10058)
+../tar_texi/tar.texi(,10059) @table @env
+../tar_texi/tar.texi(,10060) @vrindex TAR_VERSION, info script environment
variable
+../tar_texi/tar.texi(,10061) @item TAR_VERSION
+../tar_texi/tar.texi(GNUTAR,10062) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10062) version number.
+../tar_texi/tar.texi(,10063)
+../tar_texi/tar.texi(,10064) @vrindex TAR_ARCHIVE, info script environment
variable
+../tar_texi/tar.texi(,10065) @item TAR_ARCHIVE
+../tar_texi/tar.texi(,10066) The name of the archive @command{tar} is
processing.
+../tar_texi/tar.texi(,10067)
+../tar_texi/tar.texi(,10068) @vrindex TAR_VOLUME, info script environment
variable
+../tar_texi/tar.texi(,10069) @item TAR_VOLUME
+../tar_texi/tar.texi(,10070) Ordinal number of the volume @command{tar} is
about to start.
+../tar_texi/tar.texi(,10071)
+../tar_texi/tar.texi(,10072) @vrindex TAR_SUBCOMMAND, info script environment
variable
+../tar_texi/tar.texi(,10073) @item TAR_SUBCOMMAND
+../tar_texi/tar.texi(,10074) Short option describing the operation
@command{tar} is executing
+../tar_texi/tar.texi(,10075) @xref{Operations}, for a complete list of
subcommand options.
+../tar_texi/tar.texi(,10076)
+../tar_texi/tar.texi(,10077) @vrindex TAR_FORMAT, info script environment
variable
+../tar_texi/tar.texi(,10078) @item TAR_FORMAT
+../tar_texi/tar.texi(,10079) Format of the archive being processed.
@xref{Formats}, for a complete
+../tar_texi/tar.texi(,10080) list of archive format names.
+../tar_texi/tar.texi(,10081) @end table
+../tar_texi/tar.texi(,10082)
+../tar_texi/tar.texi(,10083) The volume script can instruct @command{tar} to
use new archive name,
+../tar_texi/tar.texi(,10084) by writing in to file descriptor 3 (see below for
an example).
+../tar_texi/tar.texi(,10085)
+../tar_texi/tar.texi(,10086) If the info script fails, @command{tar} exits;
otherwise, it begins
+../tar_texi/tar.texi(,10087) writing the next volume.
+../tar_texi/tar.texi(,10088)
+../tar_texi/tar.texi(,10089) If you want @command{tar} to cycle through a
series of files or tape
+../tar_texi/tar.texi(,10090) drives, there are three approaches to choose
from. First of all, you
+../tar_texi/tar.texi(,10091) can give @command{tar} multiple @option{--file}
options. In this case
+../tar_texi/tar.texi(,10092) the specified files will be used, in sequence, as
the successive
+../tar_texi/tar.texi(,10093) volumes of the archive. Only when the first one
in the sequence needs
+../tar_texi/tar.texi(,10094) to be used again will @command{tar} prompt for a
tape change (or run
+../tar_texi/tar.texi(,10095) the info script). For example, suppose someone
has two tape drives on
+../tar_texi/tar.texi(,10096) a system named @file{/dev/tape0} and
@file{/dev/tape1}. For having
+../tar_texi/tar.texi(GNUTAR,10097) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10097) to switch to the second drive
when it needs to write the
+../tar_texi/tar.texi(,10098) second tape, and then back to the first tape,
etc., just do either of:
+../tar_texi/tar.texi(,10099)
+../tar_texi/tar.texi(,10100) @smallexample
+../tar_texi/tar.texi(,10101) $ @kbd{tar --create --multi-volume
--file=/dev/tape0 --file=/dev/tape1 @var{files}}
+../tar_texi/tar.texi(,10102) $ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
+../tar_texi/tar.texi(,10103) @end smallexample
+../tar_texi/tar.texi(,10104)
+../tar_texi/tar.texi(,10105) The second method is to use the @samp{n} response
to the tape-change
+../tar_texi/tar.texi(,10106) prompt.
+../tar_texi/tar.texi(,10107)
+../tar_texi/tar.texi(,10108) Finally, the most flexible approach is to use a
volume script, that
+../tar_texi/tar.texi(,10109) writes new archive name to the file descriptor
#3. For example, the
+../tar_texi/tar.texi(,10110) following volume script will create a series of
archive files, named
+../tar_texi/tar.texi(,10111) @address@hidden@var{vol}}, where @var{archive} is
the name of the
+../tar_texi/tar.texi(,10112) archive being created (as given by
@option{--file} option) and
+../tar_texi/tar.texi(,10113) @var{vol} is the ordinal number of the archive
being created:
+../tar_texi/tar.texi(,10114)
+../tar_texi/tar.texi(,10115) @smallexample
+../tar_texi/tar.texi(,10116) @group
+../tar_texi/tar.texi(,10117) #! /bin/sh
+../tar_texi/tar.texi(,10118) echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
+../tar_texi/tar.texi(,10119)
+../tar_texi/tar.texi(,10120) name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
+../tar_texi/tar.texi(,10121) case $TAR_SUBCOMMAND in
+../tar_texi/tar.texi(,10122) -c) ;;
+../tar_texi/tar.texi(,10123) -d|-x|-t) test -r address@hidden:address@hidden
|| exit 1
+../tar_texi/tar.texi(,10124) ;;
+../tar_texi/tar.texi(,10125) *) exit 1
+../tar_texi/tar.texi(,10126) esac
+../tar_texi/tar.texi(,10127)
+../tar_texi/tar.texi(,10128) echo address@hidden:address@hidden >&3
+../tar_texi/tar.texi(,10129) @end group
+../tar_texi/tar.texi(,10130) @end smallexample
+../tar_texi/tar.texi(,10131)
+../tar_texi/tar.texi(,10132) The same script cant be used while listing,
comparing or extracting
+../tar_texi/tar.texi(,10133) from the created archive. For example:
+../tar_texi/tar.texi(,10134)
+../tar_texi/tar.texi(,10135) @smallexample
+../tar_texi/tar.texi(,10136) @group
+../tar_texi/tar.texi(,10137) # @r{Create a multi-volume archive:}
+../tar_texi/tar.texi(,10138) $ @kbd{tar -c -L1024 -f archive.tar -F new-volume
.}
+../tar_texi/tar.texi(,10139) # @r{Extract from the created archive:}
+../tar_texi/tar.texi(,10140) $ @kbd{tar -x -f archive.tar -F new-volume .}
+../tar_texi/tar.texi(,10141) @end group
+../tar_texi/tar.texi(,10142) @end smallexample
+../tar_texi/tar.texi(,10143)
+../tar_texi/tar.texi(,10144) @noindent
+../tar_texi/tar.texi(,10145) Notice, that the first command had to use
@option{-L} option, since
+../tar_texi/tar.texi(GNUTAR,10146) otherwise
../tar_texi/tar.texi(GNUTAR,10146) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10146) will end up writing everything
to file
+../tar_texi/tar.texi(,10147) @file{archive.tar}.
+../tar_texi/tar.texi(,10148)
+../tar_texi/tar.texi(,10149) You can read each individual volume of a
multi-volume archive as if it
+../tar_texi/tar.texi(,10150) were an archive by itself. For example, to list
the contents of one
+../tar_texi/tar.texi(,10151) volume, use @option{--list}, without
@option{--multi-volume} specified.
+../tar_texi/tar.texi(,10152) To extract an archive member from one volume
(assuming it is described
+../tar_texi/tar.texi(,10153) that volume), use @option{--extract}, again
without
+../tar_texi/tar.texi(,10154) @option{--multi-volume}.
+../tar_texi/tar.texi(,10155)
+../tar_texi/tar.texi(,10156) If an archive member is split across volumes
(i.e. its entry begins on
+../tar_texi/tar.texi(,10157) one volume of the media and ends on another), you
need to specify
+../tar_texi/tar.texi(,10158) @option{--multi-volume} to extract it
successfully. In this case, you
+../tar_texi/tar.texi(,10159) should load the volume where the archive member
starts, and use
+../tar_texi/tar.texi(,10160) @samp{tar --extract address@hidden will prompt
for later
+../tar_texi/tar.texi(,10161) volumes as it needs them. @xref{extracting
archives}, for more
+../tar_texi/tar.texi(,10162) information about extracting archives.
+../tar_texi/tar.texi(,10163)
+../tar_texi/tar.texi(,10164) Multi-volume archives can be modified like any
other archive. To add
+../tar_texi/tar.texi(,10165) files to a multi-volume archive, you need to only
mount the last
+../tar_texi/tar.texi(,10166) volume of the archive media (and new volumes, if
needed). For all
+../tar_texi/tar.texi(,10167) other operations, you need to use the entire
archive.
+../tar_texi/tar.texi(,10168)
+../tar_texi/tar.texi(,10169) If a multi-volume archive was labeled using
+../tar_texi/tar.texi(,10170) @address@hidden (@pxref{label}) when it was
+../tar_texi/tar.texi(,10171) created, @command{tar} will not automatically
label volumes which are
+../tar_texi/tar.texi(,10172) added later. To label subsequent volumes, specify
+../tar_texi/tar.texi(,10173) @address@hidden again in conjunction with the
+../tar_texi/tar.texi(,10174) @option{--append}, @option{--update} or
@option{--concatenate} operation.
+../tar_texi/tar.texi(,10175)
+../tar_texi/tar.texi(,10176) Notice that multi-volume support is a GNU
extension and the archives
+../tar_texi/tar.texi(GNUTAR,10177) created in this mode should be read only
using ../tar_texi/tar.texi(GNUTAR,10177) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10177) . If you
+../tar_texi/tar.texi(,10178) absolutely have to process such archives using a
third-party @command{tar}
+../tar_texi/tar.texi(,10179) implementation, read @ref{Split Recovery}.
+../tar_texi/tar.texi(,10180)
+../tar_texi/tar.texi(,10181) @node Tape Files
+../tar_texi/tar.texi(,10182) @subsection Tape Files
+../tar_texi/tar.texi(UNREVISED,10183) @quotation
+../tar_texi/tar.texi(UNREVISED,10183) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,10183) @end quotation
+../tar_texi/tar.texi(UNREVISED,10183)
+../tar_texi/tar.texi(,10184)
+../tar_texi/tar.texi(,10185) To give the archive a name which will be recorded
in it, use the
+../tar_texi/tar.texi(,10186) @address@hidden (@option{-V @var{volume-label}})
+../tar_texi/tar.texi(,10187) option. This will write a special block
identifying
+../tar_texi/tar.texi(,10188) @var{volume-label} as the name of the archive to
the front of the
+../tar_texi/tar.texi(,10189) archive which will be displayed when the archive
is listed with
+../tar_texi/tar.texi(,10190) @option{--list}. If you are creating a
multi-volume archive with
+../tar_texi/tar.texi(,10191) @option{--multi-volume} (@pxref{Using Multiple
Tapes}), then the
+../tar_texi/tar.texi(,10192) volume label will have @samp{Volume @var{nnn}}
appended to the name
+../tar_texi/tar.texi(,10193) you give, where @var{nnn} is the number of the
volume of the archive.
+../tar_texi/tar.texi(,10194) (If you use the @address@hidden) option when
+../tar_texi/tar.texi(,10195) reading an archive, it checks to make sure the
label on the tape
+../tar_texi/tar.texi(,10196) matches the one you give. @xref{label}.
+../tar_texi/tar.texi(,10197)
+../tar_texi/tar.texi(,10198) When @command{tar} writes an archive to tape, it
creates a single
+../tar_texi/tar.texi(,10199) tape file. If multiple archives are written to
the same tape, one
+../tar_texi/tar.texi(,10200) after the other, they each get written as
separate tape files. When
+../tar_texi/tar.texi(,10201) extracting, it is necessary to position the tape
at the right place
+../tar_texi/tar.texi(,10202) before running @command{tar}. To do this, use
the @command{mt} command.
+../tar_texi/tar.texi(,10203) For more information on the @command{mt} command
and on the organization
+../tar_texi/tar.texi(,10204) of tapes into a sequence of tape files, see
@ref{mt}.
+../tar_texi/tar.texi(,10205)
+../tar_texi/tar.texi(,10206) People seem to often do:
+../tar_texi/tar.texi(,10207)
+../tar_texi/tar.texi(,10208) @smallexample
+../tar_texi/tar.texi(,10209) @kbd{--label="@var{some-prefix} `date
address@hidden"}
+../tar_texi/tar.texi(,10210) @end smallexample
+../tar_texi/tar.texi(,10211)
+../tar_texi/tar.texi(,10212) or such, for pushing a common date in all volumes
or an archive set.
+../tar_texi/tar.texi(,10213)
+../tar_texi/tar.texi(,10214) @node Tarcat
+../tar_texi/tar.texi(,10215) @subsection Concatenate Volumes into a Single
Archive
+../tar_texi/tar.texi(,10216)
+../tar_texi/tar.texi(,10217) @pindex tarcat
+../tar_texi/tar.texi(GNUTAR,10218) Sometimes it is necessary to convert
existing ../tar_texi/tar.texi(GNUTAR,10218) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10218) multi-volume
+../tar_texi/tar.texi(,10219) archive to a single @command{tar} archive.
Simply concatenating all
+../tar_texi/tar.texi(,10220) volumes into one will not work, since each volume
carries an additional
+../tar_texi/tar.texi(GNUTAR,10221) information at the beginning.
../tar_texi/tar.texi(GNUTAR,10221) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10221) is shipped with the shell
+../tar_texi/tar.texi(,10222) script @command{tarcat} designed for this purpose.
+../tar_texi/tar.texi(,10223)
+../tar_texi/tar.texi(,10224) The script takes a list of files comprising a
multi-volume archive
+../tar_texi/tar.texi(,10225) and creates the resulting archive at the standard
output. For example:
+../tar_texi/tar.texi(,10226)
+../tar_texi/tar.texi(,10227) @smallexample
+../tar_texi/tar.texi(,10228) @kbd{tarcat vol.1 vol.2 vol.3 | tar tf -}
+../tar_texi/tar.texi(,10229) @end smallexample
+../tar_texi/tar.texi(,10230)
+../tar_texi/tar.texi(,10231) The script implements a simple heuristics to
determine the format of
+../tar_texi/tar.texi(,10232) the first volume file and to decide how to
process the rest of the
+../tar_texi/tar.texi(,10233) files. However, it makes no attempt to verify
whether the files are
+../tar_texi/tar.texi(,10234) given in order or even if they are valid
@command{tar} archives.
+../tar_texi/tar.texi(,10235) It uses @command{dd} and does not filter its
standard error, so you
+../tar_texi/tar.texi(,10236) will usually see lots of spurious messages.
+../tar_texi/tar.texi(,10237)
+../tar_texi/tar.texi(FIXME,10238) @allow-recursion
+../tar_texi/tar.texi(FIXME,10238) @quote-arg
+../tar_texi/tar.texi(FIXME,10238)
+../tar_texi/tar.texi(,10239)
+../tar_texi/tar.texi(,10240) @node label
+../tar_texi/tar.texi(,10241) @section Including a Label in the Archive
+../tar_texi/tar.texi(,10242) @cindex Labeling an archive
+../tar_texi/tar.texi(,10243) @cindex Labels on the archive media
+../tar_texi/tar.texi(,10244) @cindex Labeling multi-volume archives
+../tar_texi/tar.texi(UNREVISED,10245) @quotation
+../tar_texi/tar.texi(UNREVISED,10245) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/tar.texi(UNREVISED,10245) @end quotation
+../tar_texi/tar.texi(UNREVISED,10245)
+../tar_texi/tar.texi(,10246)
+../tar_texi/tar.texi(,10247) @opindex label
+../tar_texi/tar.texi(,10248) To avoid problems caused by misplaced paper
labels on the archive
+../tar_texi/tar.texi(,10249) media, you can include a @dfn{label} entry---an
archive member which
+../tar_texi/tar.texi(,10250) contains the name of the archive---in the archive
itself. Use the
+../tar_texi/tar.texi(,10251) @address@hidden (@option{-V @var{archive-label}})
+../tar_texi/tar.texi(,10252) option in conjunction with the @option{--create}
operation to include
+../tar_texi/tar.texi(,10253) a label entry in the archive as it is being
created.
+../tar_texi/tar.texi(,10254)
+../tar_texi/tar.texi(,10255) @table @option
+../tar_texi/tar.texi(,10256) @item address@hidden
+../tar_texi/tar.texi(,10257) @itemx -V @var{archive-label}
+../tar_texi/tar.texi(,10258) Includes an @dfn{archive-label} at the beginning
of the archive when
+../tar_texi/tar.texi(,10259) the archive is being created, when used in
conjunction with the
+../tar_texi/tar.texi(,10260) @option{--create} operation. Checks to make sure
the archive label
+../tar_texi/tar.texi(,10261) matches the one specified (when used in
conjunction with any other
+../tar_texi/tar.texi(,10262) operation.
+../tar_texi/tar.texi(,10263) @end table
+../tar_texi/tar.texi(,10264)
+../tar_texi/tar.texi(,10265) If you create an archive using both
+../tar_texi/tar.texi(,10266) @address@hidden (@option{-V @var{archive-label}})
+../tar_texi/tar.texi(,10267) and @option{--multi-volume} (@option{-M}), each
volume of the archive
+../tar_texi/tar.texi(,10268) will have an archive label of the form
@address@hidden
+../tar_texi/tar.texi(,10269) Volume @var{n}}, where @var{n} is 1 for the first
volume, 2 for the
+../tar_texi/tar.texi(,10270) next, and so on. @xref{Using Multiple Tapes}, for
information on
+../tar_texi/tar.texi(,10271) creating multiple volume archives.
+../tar_texi/tar.texi(,10272)
+../tar_texi/tar.texi(,10273) @cindex Volume label, listing
+../tar_texi/tar.texi(,10274) @cindex Listing volume label
+../tar_texi/tar.texi(,10275) The volume label will be displayed by
@option{--list} along with
+../tar_texi/tar.texi(,10276) the file contents. If verbose display is
requested, it will also be
+../tar_texi/tar.texi(,10277) explicitely marked as in the example below:
+../tar_texi/tar.texi(,10278)
+../tar_texi/tar.texi(,10279) @smallexample
+../tar_texi/tar.texi(,10280) @group
+../tar_texi/tar.texi(,10281) $ @kbd{tar --verbose --list --file=iamanarchive}
+../tar_texi/tar.texi(,10282) V--------- 0 0 0 1992-03-07 12:01
iamalabel--Volume Header--
+../tar_texi/tar.texi(,10283) -rw-r--r-- ringo user 40 1990-05-21 13:30
iamafilename
+../tar_texi/tar.texi(,10284) @end group
+../tar_texi/tar.texi(,10285) @end smallexample
+../tar_texi/tar.texi(,10286)
+../tar_texi/tar.texi(,10287) @opindex test-label
+../tar_texi/tar.texi(,10288) @anchor{--test-label option}
+../tar_texi/tar.texi(,10289) However, @option{--list} option will cause
listing entire
+../tar_texi/tar.texi(,10290) contents of the archive, which may be undesirable
(for example, if the
+../tar_texi/tar.texi(,10291) archive is stored on a tape). You can request
checking only the volume
+../tar_texi/tar.texi(,10292) by specifying @option{--test-label} option. This
option reads only the
+../tar_texi/tar.texi(,10293) first block of an archive, so it can be used with
slow storage
+../tar_texi/tar.texi(,10294) devices. For example:
+../tar_texi/tar.texi(,10295)
+../tar_texi/tar.texi(,10296) @smallexample
+../tar_texi/tar.texi(,10297) @group
+../tar_texi/tar.texi(,10298) $ @kbd{tar --test-label --file=iamanarchive}
+../tar_texi/tar.texi(,10299) iamalabel
+../tar_texi/tar.texi(,10300) @end group
+../tar_texi/tar.texi(,10301) @end smallexample
+../tar_texi/tar.texi(,10302)
+../tar_texi/tar.texi(,10303) If @option{--test-label} is used with a single
command line
+../tar_texi/tar.texi(,10304) argument, @command{tar} compares the volume label
with the
+../tar_texi/tar.texi(,10305) argument. It exits with code 0 if the two
strings match, and with code
+../tar_texi/tar.texi(,10306) 2 otherwise. In this case no output is
displayed. For example:
+../tar_texi/tar.texi(,10307)
+../tar_texi/tar.texi(,10308) @smallexample
+../tar_texi/tar.texi(,10309) @group
+../tar_texi/tar.texi(,10310) $ @kbd{tar --test-label --file=iamanarchive
'iamalable'}
+../tar_texi/tar.texi(,10311) @result{} 0
+../tar_texi/tar.texi(,10312) $ @kbd{tar --test-label --file=iamanarchive
'iamalable' alabel}
+../tar_texi/tar.texi(,10313) @result{} 1
+../tar_texi/tar.texi(,10314) @end group
+../tar_texi/tar.texi(,10315) @end smallexample
+../tar_texi/tar.texi(,10316)
+../tar_texi/tar.texi(,10317) If you request any operation, other than
@option{--create}, along
+../tar_texi/tar.texi(,10318) with using @option{--label} option, @command{tar}
will first check if
+../tar_texi/tar.texi(,10319) the archive label matches the one specified and
will refuse to proceed
+../tar_texi/tar.texi(,10320) if it does not. Use this as a safety precaution
to avoid accidentally
+../tar_texi/tar.texi(,10321) overwriting existing archives. For example, if
you wish to add files
+../tar_texi/tar.texi(,10322) to @file{archive}, presumably labelled with
string @samp{My volume},
+../tar_texi/tar.texi(,10323) you will get:
+../tar_texi/tar.texi(,10324)
+../tar_texi/tar.texi(,10325) @smallexample
+../tar_texi/tar.texi(,10326) @group
+../tar_texi/tar.texi(,10327) $ @kbd{tar -rf archive --label 'My volume' .}
+../tar_texi/tar.texi(,10328) tar: Archive not labeled to match `My volume'
+../tar_texi/tar.texi(,10329) @end group
+../tar_texi/tar.texi(,10330) @end smallexample
+../tar_texi/tar.texi(,10331)
+../tar_texi/tar.texi(,10332) @noindent
+../tar_texi/tar.texi(,10333) in case its label does not match. This will work
even if
+../tar_texi/tar.texi(,10334) @file{archive} is not labelled at all.
+../tar_texi/tar.texi(,10335)
+../tar_texi/tar.texi(,10336) Similarly, @command{tar} will refuse to list or
extract the
+../tar_texi/tar.texi(,10337) archive if its label doesn't match the
@var{archive-label}
+../tar_texi/tar.texi(,10338) specified. In those cases, @var{archive-label}
argument is interpreted
+../tar_texi/tar.texi(,10339) as a globbing-style pattern which must match the
actual magnetic
+../tar_texi/tar.texi(,10340) volume label. @xref{exclude}, for a precise
description of how match
+../tar_texi/tar.texi(,10341) is address@hidden versions of @command{tar} used
full
+../tar_texi/tar.texi(,10342) regular expression matching, or before that, only
exact string
+../tar_texi/tar.texi(,10343) matching, instead of wildcard matchers. We
decided for the sake of
+../tar_texi/tar.texi(,10344) simplicity to use a uniform matching device
through
+../tar_texi/tar.texi(,10345) @command{tar}.}. If the switch
@option{--multi-volume} (@option{-M}) is being used,
+../tar_texi/tar.texi(,10346) the volume label matcher will also suffix
@var{archive-label} by
+../tar_texi/tar.texi(,10347) @address@hidden Volume [1-9]*}} if the initial
match fails, before giving
+../tar_texi/tar.texi(,10348) up. Since the volume numbering is automatically
added in labels at
+../tar_texi/tar.texi(,10349) creation time, it sounded logical to equally help
the user taking care
+../tar_texi/tar.texi(,10350) of it when the archive is being read.
+../tar_texi/tar.texi(,10351)
+../tar_texi/tar.texi(,10352) The @option{--label} was once called
@option{--volume}, but is not
+../tar_texi/tar.texi(,10353) available under that name anymore.
+../tar_texi/tar.texi(,10354)
+../tar_texi/tar.texi(,10355) You can also use @option{--label} to get a
common information on
+../tar_texi/tar.texi(,10356) all tapes of a series. For having this
information different in each
+../tar_texi/tar.texi(,10357) series created through a single script used on a
regular basis, just
+../tar_texi/tar.texi(,10358) manage to get some date string as part of the
label. For example:
+../tar_texi/tar.texi(,10359)
+../tar_texi/tar.texi(,10360) @smallexample
+../tar_texi/tar.texi(,10361) @group
+../tar_texi/tar.texi(,10362) $ @kbd{tar cfMV /dev/tape "Daily backup for `date
+%Y-%m-%d`"}
+../tar_texi/tar.texi(,10363) $ @kbd{tar --create --file=/dev/tape
--multi-volume \
+../tar_texi/tar.texi(,10364) --volume="Daily backup for `date +%Y-%m-%d`"}
+../tar_texi/tar.texi(,10365) @end group
+../tar_texi/tar.texi(,10366) @end smallexample
+../tar_texi/tar.texi(,10367)
+../tar_texi/tar.texi(,10368) Also note that each label has its own date and
time, which corresponds
+../tar_texi/tar.texi(GNUTAR,10369) to when ../tar_texi/tar.texi(GNUTAR,10369)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,10369) initially
attempted to write it,
+../tar_texi/tar.texi(,10370) often soon after the operator launches
@command{tar} or types the
+../tar_texi/tar.texi(,10371) carriage return telling that the next tape is
ready. Comparing date
+../tar_texi/tar.texi(,10372) labels does give an idea of tape throughput only
if the delays for
+../tar_texi/tar.texi(,10373) rewinding tapes and the operator switching them
were negligible, which
+../tar_texi/tar.texi(,10374) is usually not the case.
+../tar_texi/tar.texi(,10375)
+../tar_texi/tar.texi(,10376) @node verify
+../tar_texi/tar.texi(,10377) @section Verifying Data as It is Stored
+../tar_texi/tar.texi(,10378) @cindex Verifying a write operation
+../tar_texi/tar.texi(,10379) @cindex Double-checking a write operation
+../tar_texi/tar.texi(,10380)
+../tar_texi/tar.texi(,10381) @table @option
+../tar_texi/tar.texi(,10382) @item -W
+../tar_texi/tar.texi(,10383) @itemx --verify
+../tar_texi/tar.texi(,10384) @opindex verify, short description
+../tar_texi/tar.texi(,10385) Attempt to verify the archive after writing.
+../tar_texi/tar.texi(,10386) @end table
+../tar_texi/tar.texi(,10387)
+../tar_texi/tar.texi(,10388) This option causes @command{tar} to verify the
archive after writing it.
+../tar_texi/tar.texi(,10389) Each volume is checked after it is written, and
any discrepancies
+../tar_texi/tar.texi(,10390) are recorded on the standard error output.
+../tar_texi/tar.texi(,10391)
+../tar_texi/tar.texi(,10392) Verification requires that the archive be on a
back-space-able medium.
+../tar_texi/tar.texi(,10393) This means pipes, some cartridge tape drives, and
some other devices
+../tar_texi/tar.texi(,10394) cannot be verified.
+../tar_texi/tar.texi(,10395)
+../tar_texi/tar.texi(,10396) You can insure the accuracy of an archive by
comparing files in the
+../tar_texi/tar.texi(,10397) system with archive members. @command{tar} can
compare an archive to the
+../tar_texi/tar.texi(,10398) file system as the archive is being written, to
verify a write
+../tar_texi/tar.texi(,10399) operation, or can compare a previously written
archive, to insure that
+../tar_texi/tar.texi(,10400) it is up to date.
+../tar_texi/tar.texi(,10401)
+../tar_texi/tar.texi(xopindex,10402) @opindex address@hidden, using with
@option{--create}}../tar_texi/tar.texi(xopindex,10402)
+../tar_texi/tar.texi(xopindex,10403) @opindex address@hidden, using with
@option{--verify}}../tar_texi/tar.texi(xopindex,10403)
+../tar_texi/tar.texi(,10404) To check for discrepancies in an archive
immediately after it is
+../tar_texi/tar.texi(,10405) written, use the @option{--verify} (@option{-W})
option in conjunction with
+../tar_texi/tar.texi(,10406) the @option{--create} operation. When this
option is
+../tar_texi/tar.texi(,10407) specified, @command{tar} checks archive members
against their counterparts
+../tar_texi/tar.texi(,10408) in the file system, and reports discrepancies on
the standard error.
+../tar_texi/tar.texi(,10409)
+../tar_texi/tar.texi(,10410) To verify an archive, you must be able to read it
from before the end
+../tar_texi/tar.texi(,10411) of the last written entry. This option is useful
for detecting data
+../tar_texi/tar.texi(,10412) errors on some tapes. Archives written to pipes,
some cartridge tape
+../tar_texi/tar.texi(,10413) drives, and some other devices cannot be verified.
+../tar_texi/tar.texi(,10414)
+../tar_texi/tar.texi(,10415) One can explicitly compare an already made
archive with the file
+../tar_texi/tar.texi(,10416) system by using the @option{--compare}
(@option{--diff}, @option{-d})
+../tar_texi/tar.texi(,10417) option, instead of using the more automatic
@option{--verify} option.
+../tar_texi/tar.texi(,10418) @xref{compare}.
+../tar_texi/tar.texi(,10419)
+../tar_texi/tar.texi(,10420) Note that these two options have a slightly
different intent. The
+../tar_texi/tar.texi(,10421) @option{--compare} option checks how identical
are the logical contents of some
+../tar_texi/tar.texi(,10422) archive with what is on your disks, while the
@option{--verify} option is
+../tar_texi/tar.texi(,10423) really for checking if the physical contents
agree and if the recording
+../tar_texi/tar.texi(,10424) media itself is of dependable quality. So, for
the @option{--verify}
+../tar_texi/tar.texi(,10425) operation, @command{tar} tries to defeat all
in-memory cache pertaining to
+../tar_texi/tar.texi(,10426) the archive, while it lets the speed optimization
undisturbed for the
+../tar_texi/tar.texi(,10427) @option{--compare} option. If you nevertheless
use @option{--compare} for
+../tar_texi/tar.texi(,10428) media verification, you may have to defeat the
in-memory cache yourself,
+../tar_texi/tar.texi(,10429) maybe by opening and reclosing the door latch of
your recording unit,
+../tar_texi/tar.texi(,10430) forcing some doubt in your operating system about
the fact this is really
+../tar_texi/tar.texi(,10431) the same volume as the one just written or read.
+../tar_texi/tar.texi(,10432)
+../tar_texi/tar.texi(,10433) The @option{--verify} option would not be
necessary if drivers were indeed
+../tar_texi/tar.texi(,10434) able to detect dependably all write failures.
This sometimes require many
+../tar_texi/tar.texi(,10435) magnetic heads, some able to read after the
writes occurred. One would
+../tar_texi/tar.texi(,10436) not say that drivers unable to detect all cases
are necessarily flawed,
+../tar_texi/tar.texi(,10437) as long as programming is concerned.
+../tar_texi/tar.texi(,10438)
+../tar_texi/tar.texi(,10439) The @option{--verify} (@option{-W}) option will
not work in
+../tar_texi/tar.texi(,10440) conjunction with the @option{--multi-volume}
(@option{-M}) option or
+../tar_texi/tar.texi(,10441) the @option{--append} (@option{-r}),
@option{--update} (@option{-u})
+../tar_texi/tar.texi(,10442) and @option{--delete} operations.
@xref{Operations}, for more
+../tar_texi/tar.texi(,10443) information on these operations.
+../tar_texi/tar.texi(,10444)
+../tar_texi/tar.texi(,10445) Also, since @command{tar} normally strips leading
@samp{/} from file
+../tar_texi/tar.texi(,10446) names (@pxref{absolute}), a command like
@samp{tar --verify -cf
+../tar_texi/tar.texi(,10447) /tmp/foo.tar /etc} will work as desired only if
the working directory is
+../tar_texi/tar.texi(,10448) @file{/}, as @command{tar} uses the archive's
relative member names
+../tar_texi/tar.texi(,10449) (e.g., @file{etc/motd}) when verifying the
archive.
+../tar_texi/tar.texi(,10450)
+../tar_texi/tar.texi(,10451) @node Write Protection
+../tar_texi/tar.texi(,10452) @section Write Protection
+../tar_texi/tar.texi(,10453)
+../tar_texi/tar.texi(,10454) Almost all tapes and diskettes, and in a few rare
cases, even disks can
+../tar_texi/tar.texi(,10455) be @dfn{write protected}, to protect data on them
from being changed.
+../tar_texi/tar.texi(,10456) Once an archive is written, you should write
protect the media to prevent
+../tar_texi/tar.texi(,10457) the archive from being accidentally overwritten
or deleted. (This will
+../tar_texi/tar.texi(,10458) protect the archive from being changed with a
tape or floppy drive---it
+../tar_texi/tar.texi(,10459) will not protect it from magnet fields or other
physical hazards).
+../tar_texi/tar.texi(,10460)
+../tar_texi/tar.texi(,10461) The write protection device itself is usually an
integral part of the
+../tar_texi/tar.texi(,10462) physical media, and can be a two position (write
enabled/write
+../tar_texi/tar.texi(,10463) disabled) switch, a notch which can be popped out
or covered, a ring
+../tar_texi/tar.texi(,10464) which can be removed from the center of a tape
reel, or some other
+../tar_texi/tar.texi(,10465) changeable feature.
+../tar_texi/tar.texi(,10466)
+../tar_texi/tar.texi(,10467) @node Changes
+../tar_texi/tar.texi(,10468) @appendix Changes
+../tar_texi/tar.texi(,10469)
+../tar_texi/tar.texi(,10470) This appendix lists some important user-visible
changes between
+../tar_texi/tar.texi(GNUTAR,10471) version ../tar_texi/tar.texi(GNUTAR,10471)
@acronym{GNU} @command{tar}../tar_texi/tar.texi(GNUTAR,10471) 1.15.92 and
previous versions. An up-to-date
+../tar_texi/tar.texi(,10472) version of this document is available at
+../tar_texi/tar.texi(,10473)
@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the
+../tar_texi/tar.texi(GNUTAR,10474) @acronym{GNU} @command{tar} documentation
page}.
+../tar_texi/tar.texi(,10475)
+../tar_texi/tar.texi(,10476) @table @asis
+../tar_texi/tar.texi(,10477) @item Use of globbing patterns when listing and
extracting.
+../tar_texi/tar.texi(,10478)
+../tar_texi/tar.texi(,10479) Previous versions of GNU tar assumed shell-style
globbing when
+../tar_texi/tar.texi(,10480) extracting from or listing an archive. For
example:
+../tar_texi/tar.texi(,10481)
+../tar_texi/tar.texi(,10482) @smallexample
+../tar_texi/tar.texi(,10483) $ @kbd{tar xf foo.tar '*.c'}
+../tar_texi/tar.texi(,10484) @end smallexample
+../tar_texi/tar.texi(,10485)
+../tar_texi/tar.texi(,10486) would extract all files whose names end in
@samp{.c}. This behavior
+../tar_texi/tar.texi(,10487) was not documented and was incompatible with
traditional tar
+../tar_texi/tar.texi(,10488) implementations. Therefore, starting from
version 1.15.91, GNU tar
+../tar_texi/tar.texi(,10489) no longer uses globbing by default. For example,
the above invocation
+../tar_texi/tar.texi(,10490) is now interpreted as a request to extract from
the archive the file
+../tar_texi/tar.texi(,10491) named @file{*.c}.
+../tar_texi/tar.texi(,10492)
+../tar_texi/tar.texi(,10493) To facilitate transition to the new behavior for
those users who got
+../tar_texi/tar.texi(,10494) used to the previous incorrect one, @command{tar}
will print a warning
+../tar_texi/tar.texi(,10495) if it finds out that a requested member was not
found in the archive
+../tar_texi/tar.texi(,10496) and its name looks like a globbing pattern. For
example:
+../tar_texi/tar.texi(,10497)
+../tar_texi/tar.texi(,10498) @smallexample
+../tar_texi/tar.texi(,10499) $ @kbd{tar xf foo.tar '*.c'}
+../tar_texi/tar.texi(,10500) tar: Pattern matching characters used in file
names. Please,
+../tar_texi/tar.texi(,10501) tar: use --wildcards to enable pattern matching,
or --no-wildcards to
+../tar_texi/tar.texi(,10502) tar: suppress this warning.
+../tar_texi/tar.texi(,10503) tar: *.c: Not found in archive
+../tar_texi/tar.texi(,10504) tar: Error exit delayed from previous errors
+../tar_texi/tar.texi(,10505) @end smallexample
+../tar_texi/tar.texi(,10506)
+../tar_texi/tar.texi(,10507) To treat member names as globbing patterns, use
--wildcards option.
+../tar_texi/tar.texi(,10508) If you want to tar to mimic the behavior of
versions prior to 1.15.91,
+../tar_texi/tar.texi(,10509) add this option to your @env{TAR_OPTIONS}
variable.
+../tar_texi/tar.texi(,10510)
+../tar_texi/tar.texi(,10511) @xref{wildcards}, for the detailed discussion of
the use of globbing
+../tar_texi/tar.texi(GNUTAR,10512) patterns by
../tar_texi/tar.texi(GNUTAR,10512) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10512) .
+../tar_texi/tar.texi(,10513)
+../tar_texi/tar.texi(,10514) @item Use of short option @option{-o}.
+../tar_texi/tar.texi(,10515)
+../tar_texi/tar.texi(GNUTAR,10516) Earlier versions of
../tar_texi/tar.texi(GNUTAR,10516) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10516) understood @option{-o} command
line
+../tar_texi/tar.texi(,10517) option as a synonym for @option{--old-archive}.
+../tar_texi/tar.texi(,10518)
+../tar_texi/tar.texi(GNUTAR,10519) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10519) starting from version 1.13.90
understands this option as
+../tar_texi/tar.texi(,10520) a synonym for @option{--no-same-owner}. This is
compatible with
+../tar_texi/tar.texi(,10521) UNIX98 @command{tar} implementations.
+../tar_texi/tar.texi(,10522)
+../tar_texi/tar.texi(,10523) However, to facilitate transition, @option{-o}
option retains its
+../tar_texi/tar.texi(,10524) old semantics when it is used with one of
archive-creation commands.
+../tar_texi/tar.texi(,10525) Users are encouraged to use
@option{--format=oldgnu} instead.
+../tar_texi/tar.texi(,10526)
+../tar_texi/tar.texi(,10527) It is especially important, since versions of
@acronym{GNU} Automake
+../tar_texi/tar.texi(,10528) up to and including 1.8.4 invoke tar with this
option to produce
+../tar_texi/tar.texi(,10529) distribution tarballs. @xref{Formats,v7}, for
the detailed discussion
+../tar_texi/tar.texi(,10530) of this issue and its implications.
+../tar_texi/tar.texi(,10531)
+../tar_texi/tar.texi(FIXME,10534) @allow-recursion
+../tar_texi/tar.texi(FIXME,10534) @quote-arg
+../tar_texi/tar.texi(FIXME,10534) .
+../tar_texi/tar.texi(,10535) @xref{Options, tar-v7, Changing Automake's
Behavior,
+../tar_texi/tar.texi(,10536) automake, GNU Automake}, for a description on how
to use various
+../tar_texi/tar.texi(,10537) archive formats with @command{automake}.
+../tar_texi/tar.texi(,10538)
+../tar_texi/tar.texi(GNUTAR,10539) Future versions of
../tar_texi/tar.texi(GNUTAR,10539) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10539) will understand @option{-o}
only as a
+../tar_texi/tar.texi(,10540) synonym for @option{--no-same-owner}.
+../tar_texi/tar.texi(,10541)
+../tar_texi/tar.texi(,10542) @item Use of short option @option{-l}
+../tar_texi/tar.texi(,10543)
+../tar_texi/tar.texi(GNUTAR,10544) Earlier versions of
../tar_texi/tar.texi(GNUTAR,10544) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10544) understood @option{-l} option
as a
+../tar_texi/tar.texi(,10545) synonym for @option{--one-file-system}. Since
such usage contradicted
+../tar_texi/tar.texi(,10546) to UNIX98 specification and harmed compatibility
with other
+../tar_texi/tar.texi(,10547) implementation, it was declared deprecated in
version 1.14. However,
+../tar_texi/tar.texi(,10548) to facilitate transition to its new semantics, it
was supported by
+../tar_texi/tar.texi(,10549) versions 1.15 and 1.15.90. The present use of
@option{-l} as a short
+../tar_texi/tar.texi(,10550) variant of @option{--check-links} was introduced
in version 1.15.91.
+../tar_texi/tar.texi(,10551)
+../tar_texi/tar.texi(,10552) @item Use of options @option{--portability} and
@option{--old-archive}
+../tar_texi/tar.texi(,10553)
+../tar_texi/tar.texi(,10554) These options are deprecated. Please use
@option{--format=v7} instead.
+../tar_texi/tar.texi(,10555)
+../tar_texi/tar.texi(,10556) @item Use of option @option{--posix}
+../tar_texi/tar.texi(,10557)
+../tar_texi/tar.texi(,10558) This option is deprecated. Please use
@option{--format=posix} instead.
+../tar_texi/tar.texi(,10559) @end table
+../tar_texi/tar.texi(,10560)
+../tar_texi/tar.texi(,10561) @node Configuring Help Summary
+../tar_texi/tar.texi(,10562) @appendix Configuring Help Summary
+../tar_texi/tar.texi(,10563)
+../tar_texi/tar.texi(,10564) Running @kbd{tar --help} displays the short
@command{tar} option
+../tar_texi/tar.texi(,10565) summary (@pxref{help}). This summary is organised
by @dfn{groups} of
+../tar_texi/tar.texi(,10566) semantically close options. The options within
each group are printed
+../tar_texi/tar.texi(,10567) in the following order: a short option,
eventually followed by a list
+../tar_texi/tar.texi(,10568) of corresponding long option names, followed by a
short description of
+../tar_texi/tar.texi(,10569) the option. For example, here is an excerpt from
the actual @kbd{tar
+../tar_texi/tar.texi(,10570) --help} output:
+../tar_texi/tar.texi(,10571)
+../tar_texi/tar.texi(,10572) @verbatim
+../tar_texi/tar.texi(,10573) Main operation mode:
+../tar_texi/tar.texi(,10574)
+../tar_texi/tar.texi(,10575) -A, --catenate, --concatenate append tar
files to an archive
+../tar_texi/tar.texi(,10576) -c, --create create a new archive
+../tar_texi/tar.texi(,10577) -d, --diff, --compare find differences
between archive and
+../tar_texi/tar.texi(,10578) file system
+../tar_texi/tar.texi(,10579) --delete delete from the
archive
+../tar_texi/tar.texi(,10580) @end verbatim
+../tar_texi/tar.texi(,10581)
+../tar_texi/tar.texi(,10582) @vrindex ARGP_HELP_FMT, environment variable
+../tar_texi/tar.texi(,10583) The exact visual representation of the help
output is configurable via
+../tar_texi/tar.texi(,10584) @env{ARGP_HELP_FMT} environment variable. The
value of this variable
+../tar_texi/tar.texi(,10585) is a comma-separated list of @dfn{format
variable} assignments. There
+../tar_texi/tar.texi(,10586) are two kinds of format variables. An @dfn{offset
variable} keeps the
+../tar_texi/tar.texi(,10587) offset of some part of help output text from the
leftmost column on
+../tar_texi/tar.texi(,10588) the screen. A @dfn{boolean} variable is a flag
that toggles some
+../tar_texi/tar.texi(,10589) output feature on or off. Depending on the type
of the corresponding
+../tar_texi/tar.texi(,10590) variable, there are two kinds of assignments:
+../tar_texi/tar.texi(,10591)
+../tar_texi/tar.texi(,10592) @table @asis
+../tar_texi/tar.texi(,10593) @item Offset assignment
+../tar_texi/tar.texi(,10594)
+../tar_texi/tar.texi(,10595) The assignment to an offset variable has the
following syntax:
+../tar_texi/tar.texi(,10596)
+../tar_texi/tar.texi(,10597) @smallexample
+../tar_texi/tar.texi(,10598) @address@hidden
+../tar_texi/tar.texi(,10599) @end smallexample
+../tar_texi/tar.texi(,10600)
+../tar_texi/tar.texi(,10601) @noindent
+../tar_texi/tar.texi(,10602) where @var{variable} is the variable name, and
@var{value} is a
+../tar_texi/tar.texi(,10603) numeric value to be assigned to the variable.
+../tar_texi/tar.texi(,10604)
+../tar_texi/tar.texi(,10605) @item Boolean assignment
+../tar_texi/tar.texi(,10606)
+../tar_texi/tar.texi(,10607) To assign @code{true} value to a variable, simply
put this variable name. To
+../tar_texi/tar.texi(,10608) assign @code{false} value, prefix the variable
name with @samp{no-}. For
+../tar_texi/tar.texi(,10609) example:
+../tar_texi/tar.texi(,10610)
+../tar_texi/tar.texi(,10611) @smallexample
+../tar_texi/tar.texi(,10612) @group
+../tar_texi/tar.texi(,10613) # Assign @code{true} value:
+../tar_texi/tar.texi(,10614) dup-args
+../tar_texi/tar.texi(,10615) # Assign @code{false} value:
+../tar_texi/tar.texi(,10616) no-dup-args
+../tar_texi/tar.texi(,10617) @end group
+../tar_texi/tar.texi(,10618) @end smallexample
+../tar_texi/tar.texi(,10619) @end table
+../tar_texi/tar.texi(,10620)
+../tar_texi/tar.texi(,10621) Following variables are declared:
+../tar_texi/tar.texi(,10622)
+../tar_texi/tar.texi(,10623) @deftypevr {Help Output} boolean dup-args
+../tar_texi/tar.texi(,10624) If true, arguments for an option are shown with
both short and long
+../tar_texi/tar.texi(,10625) options, even when a given option has both forms,
for example:
+../tar_texi/tar.texi(,10626)
+../tar_texi/tar.texi(,10627) @smallexample
+../tar_texi/tar.texi(,10628) -f ARCHIVE, --file=ARCHIVE use archive file or
device ARCHIVE
+../tar_texi/tar.texi(,10629) @end smallexample
+../tar_texi/tar.texi(,10630)
+../tar_texi/tar.texi(,10631) If false, then if an option has both short and
long forms, the
+../tar_texi/tar.texi(,10632) argument is only shown with the long one, for
example:
+../tar_texi/tar.texi(,10633)
+../tar_texi/tar.texi(,10634) @smallexample
+../tar_texi/tar.texi(,10635) -f, --file=ARCHIVE use archive file or
device ARCHIVE
+../tar_texi/tar.texi(,10636) @end smallexample
+../tar_texi/tar.texi(,10637)
+../tar_texi/tar.texi(,10638) @noindent
+../tar_texi/tar.texi(,10639) and a message indicating that the argument is
applicable to both
+../tar_texi/tar.texi(,10640) forms is printed below the options. This message
can be disabled
+../tar_texi/tar.texi(,10641) using @code{dup-args-note} (see below).
+../tar_texi/tar.texi(,10642)
+../tar_texi/tar.texi(,10643) The default is false.
+../tar_texi/tar.texi(,10644) @end deftypevr
+../tar_texi/tar.texi(,10645)
+../tar_texi/tar.texi(,10646) @deftypevr {Help Output} boolean dup-args-note
+../tar_texi/tar.texi(,10647) If this variable is true, which is the default,
the following notice
+../tar_texi/tar.texi(,10648) is displayed at the end of the help output:
+../tar_texi/tar.texi(,10649)
+../tar_texi/tar.texi(,10650) @quotation
+../tar_texi/tar.texi(,10651) Mandatory or optional arguments to long options
are also mandatory or
+../tar_texi/tar.texi(,10652) optional for any corresponding short options.
+../tar_texi/tar.texi(,10653) @end quotation
+../tar_texi/tar.texi(,10654)
+../tar_texi/tar.texi(,10655) Setting @code{no-dup-args-note} inhibits this
message. Normally, only one of
+../tar_texi/tar.texi(,10656) variables @code{dup-args} or @code{dup-args-note}
should be set.
+../tar_texi/tar.texi(,10657) @end deftypevr
+../tar_texi/tar.texi(,10658)
+../tar_texi/tar.texi(,10659) @deftypevr {Help Output} offset short-opt-col
+../tar_texi/tar.texi(,10660) Column in which short options start. Default is 2.
+../tar_texi/tar.texi(,10661)
+../tar_texi/tar.texi(,10662) @smallexample
+../tar_texi/tar.texi(,10663) @group
+../tar_texi/tar.texi(,10664) $ @kbd{tar --help|grep ARCHIVE}
+../tar_texi/tar.texi(,10665) -f, --file=ARCHIVE use archive file or device
ARCHIVE
+../tar_texi/tar.texi(,10666) $ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar
--help|grep ARCHIVE}
+../tar_texi/tar.texi(,10667) -f, --file=ARCHIVE use archive file or
device ARCHIVE
+../tar_texi/tar.texi(,10668) @end group
+../tar_texi/tar.texi(,10669) @end smallexample
+../tar_texi/tar.texi(,10670) @end deftypevr
+../tar_texi/tar.texi(,10671)
+../tar_texi/tar.texi(,10672) @deftypevr {Help Output} offset long-opt-col
+../tar_texi/tar.texi(,10673) Column in which long options start. Default is 6.
For example:
+../tar_texi/tar.texi(,10674)
+../tar_texi/tar.texi(,10675) @smallexample
+../tar_texi/tar.texi(,10676) @group
+../tar_texi/tar.texi(,10677) $ @kbd{tar --help|grep ARCHIVE}
+../tar_texi/tar.texi(,10678) -f, --file=ARCHIVE use archive file or device
ARCHIVE
+../tar_texi/tar.texi(,10679) $ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar
--help|grep ARCHIVE}
+../tar_texi/tar.texi(,10680) -f, --file=ARCHIVE use archive file
or device ARCHIVE
+../tar_texi/tar.texi(,10681) @end group
+../tar_texi/tar.texi(,10682) @end smallexample
+../tar_texi/tar.texi(,10683) @end deftypevr
+../tar_texi/tar.texi(,10684)
+../tar_texi/tar.texi(,10685) @deftypevr {Help Output} offset doc-opt-col
+../tar_texi/tar.texi(,10686) Column in which @dfn{doc options} start. A doc
option isn't actually
+../tar_texi/tar.texi(,10687) an option, but rather an arbitrary piece of
documentation that is
+../tar_texi/tar.texi(,10688) displayed in much the same manner as the options.
For example, in
+../tar_texi/tar.texi(,10689) the description of @option{--format} option:
+../tar_texi/tar.texi(,10690)
+../tar_texi/tar.texi(,10691) @smallexample
+../tar_texi/tar.texi(,10692) @group
+../tar_texi/tar.texi(,10693) -H, --format=FORMAT create archive of
the given format.
+../tar_texi/tar.texi(,10694)
+../tar_texi/tar.texi(,10695) FORMAT is one of the following:
+../tar_texi/tar.texi(,10696)
+../tar_texi/tar.texi(,10697) gnu GNU tar 1.13.x format
+../tar_texi/tar.texi(,10698) oldgnu GNU format as per
tar <= 1.12
+../tar_texi/tar.texi(,10699) pax POSIX 1003.1-2001
(pax) format
+../tar_texi/tar.texi(,10700) posix same as pax
+../tar_texi/tar.texi(,10701) ustar POSIX 1003.1-1988
(ustar) format
+../tar_texi/tar.texi(,10702) v7 old V7 tar format
+../tar_texi/tar.texi(,10703) @end group
+../tar_texi/tar.texi(,10704) @end smallexample
+../tar_texi/tar.texi(,10705)
+../tar_texi/tar.texi(,10706) @noindent
+../tar_texi/tar.texi(,10707) the format names are doc options. Thus, if you set
+../tar_texi/tar.texi(,10708) @kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part
of the help output
+../tar_texi/tar.texi(,10709) will look as follows:
+../tar_texi/tar.texi(,10710)
+../tar_texi/tar.texi(,10711) @smallexample
+../tar_texi/tar.texi(,10712) @group
+../tar_texi/tar.texi(,10713) -H, --format=FORMAT create archive of
the given format.
+../tar_texi/tar.texi(,10714)
+../tar_texi/tar.texi(,10715) FORMAT is one of the following:
+../tar_texi/tar.texi(,10716)
+../tar_texi/tar.texi(,10717) gnu GNU tar 1.13.x
format
+../tar_texi/tar.texi(,10718) oldgnu GNU format as
per tar <= 1.12
+../tar_texi/tar.texi(,10719) pax POSIX
1003.1-2001 (pax) format
+../tar_texi/tar.texi(,10720) posix same as pax
+../tar_texi/tar.texi(,10721) ustar POSIX
1003.1-1988 (ustar) format
+../tar_texi/tar.texi(,10722) v7 old V7 tar format
+../tar_texi/tar.texi(,10723) @end group
+../tar_texi/tar.texi(,10724) @end smallexample
+../tar_texi/tar.texi(,10725) @end deftypevr
+../tar_texi/tar.texi(,10726)
+../tar_texi/tar.texi(,10727) @deftypevr {Help Output} offset opt-doc-col
+../tar_texi/tar.texi(,10728) Column in which option description starts.
Default is 29.
+../tar_texi/tar.texi(,10729)
+../tar_texi/tar.texi(,10730) @smallexample
+../tar_texi/tar.texi(,10731) @group
+../tar_texi/tar.texi(,10732) $ @kbd{tar --help|grep ARCHIVE}
+../tar_texi/tar.texi(,10733) -f, --file=ARCHIVE use archive file or
device ARCHIVE
+../tar_texi/tar.texi(,10734) $ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar
--help|grep ARCHIVE}
+../tar_texi/tar.texi(,10735) -f, --file=ARCHIVE use archive file or device
ARCHIVE
+../tar_texi/tar.texi(,10736) $ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar
--help|grep ARCHIVE}
+../tar_texi/tar.texi(,10737) -f, --file=ARCHIVE
+../tar_texi/tar.texi(,10738) use archive file or device ARCHIVE
+../tar_texi/tar.texi(,10739) @end group
+../tar_texi/tar.texi(,10740) @end smallexample
+../tar_texi/tar.texi(,10741)
+../tar_texi/tar.texi(,10742) @noindent
+../tar_texi/tar.texi(,10743) Notice, that the description starts on a separate
line if
+../tar_texi/tar.texi(,10744) @code{opt-doc-col} value is too small.
+../tar_texi/tar.texi(,10745) @end deftypevr
+../tar_texi/tar.texi(,10746)
+../tar_texi/tar.texi(,10747) @deftypevr {Help Output} offset header-col
+../tar_texi/tar.texi(,10748) Column in which @dfn{group headers} are printed.
A group header is a
+../tar_texi/tar.texi(,10749) descriptive text preceding an option group. For
example, in the
+../tar_texi/tar.texi(,10750) following text:
+../tar_texi/tar.texi(,10751)
+../tar_texi/tar.texi(,10752) @verbatim
+../tar_texi/tar.texi(,10753) Main operation mode:
+../tar_texi/tar.texi(,10754)
+../tar_texi/tar.texi(,10755) -A, --catenate, --concatenate append tar
files to
+../tar_texi/tar.texi(,10756) an archive
+../tar_texi/tar.texi(,10757) -c, --create create a new archive
+../tar_texi/tar.texi(,10758) @end verbatim
+../tar_texi/tar.texi(,10759) @noindent
+../tar_texi/tar.texi(,10760) @samp{Main operation mode:} is the group header.
+../tar_texi/tar.texi(,10761)
+../tar_texi/tar.texi(,10762) The default value is 1.
+../tar_texi/tar.texi(,10763) @end deftypevr
+../tar_texi/tar.texi(,10764)
+../tar_texi/tar.texi(,10765) @deftypevr {Help Output} offset usage-indent
+../tar_texi/tar.texi(,10766) Indentation of wrapped usage lines. Affects
@option{--usage}
+../tar_texi/tar.texi(,10767) output. Default is 12.
+../tar_texi/tar.texi(,10768) @end deftypevr
+../tar_texi/tar.texi(,10769)
+../tar_texi/tar.texi(,10770) @deftypevr {Help Output} offset rmargin
+../tar_texi/tar.texi(,10771) Right margin of the text output. Used for
wrapping.
+../tar_texi/tar.texi(,10772) @end deftypevr
+../tar_texi/tar.texi(,10773)
+../tar_texi/tar.texi(,10774) @node Tar Internals
+../tar_texi/tar.texi(,10775) @appendix Tar Internals
+../tar_texi/intern.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/intern.texi(,2) @c Copyright (C) 2006 Free Software Foundation,
Inc.
+../tar_texi/intern.texi(,3) @c This file is distributed under GFDL 1.1 or any
later version
+../tar_texi/intern.texi(,4) @c published by the Free Software Foundation.
+../tar_texi/intern.texi(,5)
+../tar_texi/intern.texi(,6) @menu
+../tar_texi/intern.texi(,7) * Standard:: Basic Tar Format
+../tar_texi/intern.texi(,8) * Extensions:: @acronym{GNU} Extensions to
the Archive Format
+../tar_texi/intern.texi(,9) * Sparse Formats:: Storing Sparse Files
+../tar_texi/intern.texi(,10) * Snapshot Files::
+../tar_texi/intern.texi(,11) * Dumpdir::
+../tar_texi/intern.texi(,12) @end menu
+../tar_texi/intern.texi(,13)
+../tar_texi/intern.texi(,14) @node Standard
+../tar_texi/intern.texi(,15) @unnumberedsec Basic Tar Format
+../tar_texi/intern.texi(UNREVISED,16) @quotation
+../tar_texi/intern.texi(UNREVISED,16) @emph{(This message will disappear, once
this node revised.)}
+../tar_texi/intern.texi(UNREVISED,16) @end quotation
+../tar_texi/intern.texi(UNREVISED,16)
+../tar_texi/intern.texi(,17)
+../tar_texi/intern.texi(,18) While an archive may contain many files, the
archive itself is a
+../tar_texi/intern.texi(,19) single ordinary file. Like any other file, an
archive file can be
+../tar_texi/intern.texi(,20) written to a storage device such as a tape or
disk, sent through a
+../tar_texi/intern.texi(,21) pipe or over a network, saved on the active file
system, or even
+../tar_texi/intern.texi(,22) stored in another archive. An archive file is
not easy to read or
+../tar_texi/intern.texi(,23) manipulate without using the @command{tar}
utility or Tar mode in
+../tar_texi/intern.texi(,24) @acronym{GNU} Emacs.
+../tar_texi/intern.texi(,25)
+../tar_texi/intern.texi(,26) Physically, an archive consists of a series of
file entries terminated
+../tar_texi/intern.texi(,27) by an end-of-archive entry, which consists of two
512 blocks of zero
+../tar_texi/intern.texi(,28) bytes. A file
+../tar_texi/intern.texi(,29) entry usually describes one of the files in the
archive (an
+../tar_texi/intern.texi(,30) @dfn{archive member}), and consists of a file
header and the contents
+../tar_texi/intern.texi(,31) of the file. File headers contain file names and
statistics, checksum
+../tar_texi/intern.texi(,32) information which @command{tar} uses to detect
file corruption, and
+../tar_texi/intern.texi(,33) information about file types.
+../tar_texi/intern.texi(,34)
+../tar_texi/intern.texi(,35) Archives are permitted to have more than one
member with the same
+../tar_texi/intern.texi(,36) member name. One way this situation can occur is
if more than one
+../tar_texi/intern.texi(,37) version of a file has been stored in the archive.
For information
+../tar_texi/intern.texi(,38) about adding new versions of a file to an
archive, see @ref{update}.
+../tar_texi/intern.texi(FIXME-xref,40) @quote-arg
+../tar_texi/intern.texi(FIXME-xref,40)
+../tar_texi/intern.texi(,41)
+../tar_texi/intern.texi(,42) In addition to entries describing archive
members, an archive may
+../tar_texi/intern.texi(,43) contain entries which @command{tar} itself uses
to store information.
+../tar_texi/intern.texi(,44) @xref{label}, for an example of such an archive
entry.
+../tar_texi/intern.texi(,45)
+../tar_texi/intern.texi(,46) A @command{tar} archive file contains a series of
blocks. Each block
+../tar_texi/intern.texi(,47) contains @code{BLOCKSIZE} bytes. Although this
format may be thought
+../tar_texi/intern.texi(,48) of as being on magnetic tape, other media are
often used.
+../tar_texi/intern.texi(,49)
+../tar_texi/intern.texi(,50) Each file archived is represented by a header
block which describes
+../tar_texi/intern.texi(,51) the file, followed by zero or more blocks which
give the contents
+../tar_texi/intern.texi(,52) of the file. At the end of the archive file
there are two 512-byte blocks
+../tar_texi/intern.texi(,53) filled with binary zeros as an end-of-file
marker. A reasonable system
+../tar_texi/intern.texi(,54) should write such end-of-file marker at the end
of an archive, but
+../tar_texi/intern.texi(,55) must not assume that such a block exists when
reading an archive. In
+../tar_texi/intern.texi(GNUTAR,56) particular
../tar_texi/intern.texi(GNUTAR,56) @acronym{GNU}
@command{tar}../tar_texi/intern.texi(GNUTAR,56) always issues a warning if it
does not encounter it.
+../tar_texi/intern.texi(,57)
+../tar_texi/intern.texi(,58) The blocks may be @dfn{blocked} for physical I/O
operations.
+../tar_texi/intern.texi(,59) Each record of @var{n} blocks (where @var{n} is
set by the
+../tar_texi/intern.texi(,60) @address@hidden (@option{-b @var{512-size}})
option to @command{tar}) is written with a single
+../tar_texi/intern.texi(,61) @address@hidden ()}} operation. On magnetic
tapes, the result of
+../tar_texi/intern.texi(,62) such a write is a single record. When writing an
archive,
+../tar_texi/intern.texi(,63) the last record of blocks should be written at
the full size, with
+../tar_texi/intern.texi(,64) blocks after the zero block containing all zeros.
When reading
+../tar_texi/intern.texi(,65) an archive, a reasonable system should properly
handle an archive
+../tar_texi/intern.texi(,66) whose last record is shorter than the rest, or
which contains garbage
+../tar_texi/intern.texi(,67) records after a zero block.
+../tar_texi/intern.texi(,68)
+../tar_texi/intern.texi(GNUTAR,69) The header block is defined in C as
follows. In the ../tar_texi/intern.texi(GNUTAR,69) @acronym{GNU}
@command{tar}../tar_texi/intern.texi(GNUTAR,69)
+../tar_texi/intern.texi(,70) distribution, this is part of file
@file{src/tar.h}:
+../tar_texi/intern.texi(,71)
+../tar_texi/intern.texi(,72) @smallexample
+../tar_texi/header.texi(,1) @comment GNU tar Archive Format description.
+../tar_texi/header.texi(,2) @comment
+../tar_texi/header.texi(,3) @comment Copyright (C) 1988, 1989, 1991, 1992,
1993, 1994, 1995, 1996, 1997,
+../tar_texi/header.texi(,4) @comment 2000, 2001, 2003, 2004, 2005, 2006 Free
Software Foundation, Inc.
+../tar_texi/header.texi(,5) @comment
+../tar_texi/header.texi(,6) @comment This program is free software; you can
redistribute it and/or modify it
+../tar_texi/header.texi(,7) @comment under the terms of the GNU General
Public License as published by the
+../tar_texi/header.texi(,8) @comment Free Software Foundation; either
version 2, or (at your option) any later
+../tar_texi/header.texi(,9) @comment version.
+../tar_texi/header.texi(,10) @comment
+../tar_texi/header.texi(,11) @comment This program is distributed in the
hope that it will be useful, but
+../tar_texi/header.texi(,12) @comment WITHOUT ANY WARRANTY; without even the
implied warranty of
+../tar_texi/header.texi(,13) @comment MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General
+../tar_texi/header.texi(,14) @comment Public License for more details.
+../tar_texi/header.texi(,15) @comment
+../tar_texi/header.texi(,16) @comment You should have received a copy of the
GNU General Public License along
+../tar_texi/header.texi(,17) @comment with this program; if not, write to
the Free Software Foundation, Inc.,
+../tar_texi/header.texi(,18) @comment 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
+../tar_texi/header.texi(,19)
+../tar_texi/header.texi(,20) /address@hidden tar Header Block, from POSIX
1003.1-1990. }*/
+../tar_texi/header.texi(,21)
+../tar_texi/header.texi(,22) /address@hidden POSIX header. }*/
+../tar_texi/header.texi(,23)
+../tar_texi/header.texi(,24) struct posix_header
+../tar_texi/header.texi(,25) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,26) char name[100]; /address@hidden
0 }*/
+../tar_texi/header.texi(,27) char mode[8]; /address@hidden
100 }*/
+../tar_texi/header.texi(,28) char uid[8]; /address@hidden
108 }*/
+../tar_texi/header.texi(,29) char gid[8]; /address@hidden
116 }*/
+../tar_texi/header.texi(,30) char size[12]; /address@hidden
124 }*/
+../tar_texi/header.texi(,31) char mtime[12]; /address@hidden
136 }*/
+../tar_texi/header.texi(,32) char chksum[8]; /address@hidden
148 }*/
+../tar_texi/header.texi(,33) char typeflag; /address@hidden
156 }*/
+../tar_texi/header.texi(,34) char linkname[100]; /address@hidden
157 }*/
+../tar_texi/header.texi(,35) char magic[6]; /address@hidden
257 }*/
+../tar_texi/header.texi(,36) char version[2]; /address@hidden
263 }*/
+../tar_texi/header.texi(,37) char uname[32]; /address@hidden
265 }*/
+../tar_texi/header.texi(,38) char gname[32]; /address@hidden
297 }*/
+../tar_texi/header.texi(,39) char devmajor[8]; /address@hidden
329 }*/
+../tar_texi/header.texi(,40) char devminor[8]; /address@hidden
337 }*/
+../tar_texi/header.texi(,41) char prefix[155]; /address@hidden
345 }*/
+../tar_texi/header.texi(,42) /address@hidden
500 }*/
+../tar_texi/header.texi(,43) @};
+../tar_texi/header.texi(,44)
+../tar_texi/header.texi(,45) #define TMAGIC "ustar" /address@hidden
ustar and a null }*/
+../tar_texi/header.texi(,46) #define TMAGLEN 6
+../tar_texi/header.texi(,47) #define TVERSION "00" /address@hidden
00 and no null }*/
+../tar_texi/header.texi(,48) #define TVERSLEN 2
+../tar_texi/header.texi(,49)
+../tar_texi/header.texi(,50) /address@hidden Values used in typeflag field.
}*/
+../tar_texi/header.texi(,51) #define REGTYPE '0' /address@hidden
regular file }*/
+../tar_texi/header.texi(,52) #define AREGTYPE '\0' /address@hidden
regular file }*/
+../tar_texi/header.texi(,53) #define LNKTYPE '1' /address@hidden
link }*/
+../tar_texi/header.texi(,54) #define SYMTYPE '2' /address@hidden
reserved }*/
+../tar_texi/header.texi(,55) #define CHRTYPE '3' /address@hidden
character special }*/
+../tar_texi/header.texi(,56) #define BLKTYPE '4' /address@hidden
block special }*/
+../tar_texi/header.texi(,57) #define DIRTYPE '5' /address@hidden
directory }*/
+../tar_texi/header.texi(,58) #define FIFOTYPE '6' /address@hidden
FIFO special }*/
+../tar_texi/header.texi(,59) #define CONTTYPE '7' /address@hidden
reserved }*/
+../tar_texi/header.texi(,60)
+../tar_texi/header.texi(,61) #define XHDTYPE 'x' /address@hidden
Extended header referring to the
+../tar_texi/header.texi(,62) next file in
the archive }*/
+../tar_texi/header.texi(,63) #define XGLTYPE 'g' /address@hidden
Global extended header }*/
+../tar_texi/header.texi(,64)
+../tar_texi/header.texi(,65) /address@hidden Bits used in the mode field,
values in octal. }*/
+../tar_texi/header.texi(,66) #define TSUID 04000 /address@hidden
set UID on execution }*/
+../tar_texi/header.texi(,67) #define TSGID 02000 /address@hidden
set GID on execution }*/
+../tar_texi/header.texi(,68) #define TSVTX 01000 /address@hidden
reserved }*/
+../tar_texi/header.texi(,69) /address@hidden
file permissions }*/
+../tar_texi/header.texi(,70) #define TUREAD 00400 /address@hidden
read by owner }*/
+../tar_texi/header.texi(,71) #define TUWRITE 00200 /address@hidden
write by owner }*/
+../tar_texi/header.texi(,72) #define TUEXEC 00100 /address@hidden
execute/search by owner }*/
+../tar_texi/header.texi(,73) #define TGREAD 00040 /address@hidden
read by group }*/
+../tar_texi/header.texi(,74) #define TGWRITE 00020 /address@hidden
write by group }*/
+../tar_texi/header.texi(,75) #define TGEXEC 00010 /address@hidden
execute/search by group }*/
+../tar_texi/header.texi(,76) #define TOREAD 00004 /address@hidden
read by other }*/
+../tar_texi/header.texi(,77) #define TOWRITE 00002 /address@hidden
write by other }*/
+../tar_texi/header.texi(,78) #define TOEXEC 00001 /address@hidden
execute/search by other }*/
+../tar_texi/header.texi(,79)
+../tar_texi/header.texi(,80) /address@hidden tar Header Block, GNU extensions.
}*/
+../tar_texi/header.texi(,81)
+../tar_texi/header.texi(,82) /address@hidden In GNU tar, SYMTYPE is for to
symbolic links, and CONTTYPE is for
+../tar_texi/header.texi(,83) contiguous files, so maybe disobeying the
`reserved' comment in POSIX
+../tar_texi/header.texi(,84) header description. I suspect these were
meant to be used this way, and
+../tar_texi/header.texi(,85) should not have really been `reserved' in the
published standards. }*/
+../tar_texi/header.texi(,86)
+../tar_texi/header.texi(,87) /address@hidden *BEWARE* *BEWARE* *BEWARE* that
the following information is still
+../tar_texi/header.texi(,88) boiling, and may change. Even if the OLDGNU
format description should be
+../tar_texi/header.texi(,89) accurate, the so-called GNU format is not yet
fully decided. It is
+../tar_texi/header.texi(,90) surely meant to use only extensions allowed by
POSIX, but the sketch
+../tar_texi/header.texi(,91) below repeats some ugliness from the OLDGNU
format, which should rather
+../tar_texi/header.texi(,92) go away. Sparse files should be saved in such
a way that they do *not*
+../tar_texi/header.texi(,93) require two passes at archive creation time.
Huge files get some POSIX
+../tar_texi/header.texi(,94) fields to overflow, alternate solutions have
to be sought for this. }*/
+../tar_texi/header.texi(,95)
+../tar_texi/header.texi(,96) /address@hidden Descriptor for a single file
hole. }*/
+../tar_texi/header.texi(,97)
+../tar_texi/header.texi(,98) struct sparse
+../tar_texi/header.texi(,99) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,100) char offset[12]; /address@hidden
0 }*/
+../tar_texi/header.texi(,101) char numbytes[12]; /address@hidden
12 }*/
+../tar_texi/header.texi(,102) /address@hidden
24 }*/
+../tar_texi/header.texi(,103) @};
+../tar_texi/header.texi(,104)
+../tar_texi/header.texi(,105) /address@hidden Sparse files are not supported
in POSIX ustar format. For sparse files
+../tar_texi/header.texi(,106) with a POSIX header, a GNU extra header is
provided which holds overall
+../tar_texi/header.texi(,107) sparse information and a few sparse
descriptors. When an old GNU header
+../tar_texi/header.texi(,108) replaces both the POSIX header and the GNU
extra header, it holds some
+../tar_texi/header.texi(,109) sparse descriptors too. Whether POSIX or
not, if more sparse descriptors
+../tar_texi/header.texi(,110) are still needed, they are put into as many
successive sparse headers as
+../tar_texi/header.texi(,111) necessary. The following constants tell how
many sparse descriptors fit
+../tar_texi/header.texi(,112) in each kind of header able to hold them. }*/
+../tar_texi/header.texi(,113)
+../tar_texi/header.texi(,114) #define SPARSES_IN_EXTRA_HEADER 16
+../tar_texi/header.texi(,115) #define SPARSES_IN_OLDGNU_HEADER 4
+../tar_texi/header.texi(,116) #define SPARSES_IN_SPARSE_HEADER 21
+../tar_texi/header.texi(,117)
+../tar_texi/header.texi(,118) /address@hidden Extension header for sparse
files, used immediately after the GNU extra
+../tar_texi/header.texi(,119) header, and used only if all sparse
information cannot fit into that
+../tar_texi/header.texi(,120) extra header. There might even be many such
extension headers, one after
+../tar_texi/header.texi(,121) the other, until all sparse information has
been recorded. }*/
+../tar_texi/header.texi(,122)
+../tar_texi/header.texi(,123) struct sparse_header
+../tar_texi/header.texi(,124) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,125) struct sparse sp[SPARSES_IN_SPARSE_HEADER];
+../tar_texi/header.texi(,126) /address@hidden
0 }*/
+../tar_texi/header.texi(,127) char isextended; /address@hidden
504 }*/
+../tar_texi/header.texi(,128) /address@hidden
505 }*/
+../tar_texi/header.texi(,129) @};
+../tar_texi/header.texi(,130)
+../tar_texi/header.texi(,131) /address@hidden The old GNU format header
conflicts with POSIX format in such a way that
+../tar_texi/header.texi(,132) POSIX archives may fool old GNU tar's, and
POSIX tar's might well be
+../tar_texi/header.texi(,133) fooled by old GNU tar archives. An old GNU
format header uses the space
+../tar_texi/header.texi(,134) used by the prefix field in a POSIX header,
and cumulates information
+../tar_texi/header.texi(,135) normally found in a GNU extra header. With
an old GNU tar header, we
+../tar_texi/header.texi(,136) never see any POSIX header nor GNU extra
header. Supplementary sparse
+../tar_texi/header.texi(,137) headers are allowed, however. }*/
+../tar_texi/header.texi(,138)
+../tar_texi/header.texi(,139) struct oldgnu_header
+../tar_texi/header.texi(,140) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,141) char unused_pad1[345]; /address@hidden
0 }*/
+../tar_texi/header.texi(,142) char atime[12]; /address@hidden
345 Incr. archive: atime of the file }*/
+../tar_texi/header.texi(,143) char ctime[12]; /address@hidden
357 Incr. archive: ctime of the file }*/
+../tar_texi/header.texi(,144) char offset[12]; /address@hidden
369 Multivolume archive: the offset of
+../tar_texi/header.texi(,145) the start of
this volume }*/
+../tar_texi/header.texi(,146) char longnames[4]; /address@hidden
381 Not used }*/
+../tar_texi/header.texi(,147) char unused_pad2; /address@hidden
385 }*/
+../tar_texi/header.texi(,148) struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
+../tar_texi/header.texi(,149) /address@hidden
386 }*/
+../tar_texi/header.texi(,150) char isextended; /address@hidden
482 Sparse file: Extension sparse header
+../tar_texi/header.texi(,151) follows }*/
+../tar_texi/header.texi(,152) char realsize[12]; /address@hidden
483 Sparse file: Real size}*/
+../tar_texi/header.texi(,153) /address@hidden
495 }*/
+../tar_texi/header.texi(,154) @};
+../tar_texi/header.texi(,155)
+../tar_texi/header.texi(,156) /address@hidden OLDGNU_MAGIC uses both magic and
version fields, which are contiguous.
+../tar_texi/header.texi(,157) Found in an archive, it indicates an old GNU
header format, which will be
+../tar_texi/header.texi(,158) hopefully become obsolescent. With
OLDGNU_MAGIC, uname and gname are
+../tar_texi/header.texi(,159) valid, though the header is not truly POSIX
conforming. }*/
+../tar_texi/header.texi(,160) #define OLDGNU_MAGIC "ustar " /address@hidden
7 chars and a null }*/
+../tar_texi/header.texi(,161)
+../tar_texi/header.texi(,162) /address@hidden The standards committee allows
only capital A through capital Z for
+../tar_texi/header.texi(,163) user-defined expansion. Other letters in use
include:
+../tar_texi/header.texi(,164)
+../tar_texi/header.texi(,165) 'A' Solaris Access Control List
+../tar_texi/header.texi(,166) 'E' Solaris Extended Attribute File
+../tar_texi/header.texi(,167) 'I' Inode only, as in 'star'
+../tar_texi/header.texi(,168) 'X' POSIX 1003.1-2001 eXtended (VU version)
}*/
+../tar_texi/header.texi(,169)
+../tar_texi/header.texi(,170) /address@hidden This is a dir entry that
contains the names of files that were in the
+../tar_texi/header.texi(,171) dir at the time the dump was made. }*/
+../tar_texi/header.texi(,172) #define GNUTYPE_DUMPDIR 'D'
+../tar_texi/header.texi(,173)
+../tar_texi/header.texi(,174) /address@hidden Identifies the *next* file on
the tape as having a long linkname. }*/
+../tar_texi/header.texi(,175) #define GNUTYPE_LONGLINK 'K'
+../tar_texi/header.texi(,176)
+../tar_texi/header.texi(,177) /address@hidden Identifies the *next* file on
the tape as having a long name. }*/
+../tar_texi/header.texi(,178) #define GNUTYPE_LONGNAME 'L'
+../tar_texi/header.texi(,179)
+../tar_texi/header.texi(,180) /address@hidden This is the continuation of a
file that began on another volume. }*/
+../tar_texi/header.texi(,181) #define GNUTYPE_MULTIVOL 'M'
+../tar_texi/header.texi(,182)
+../tar_texi/header.texi(,183) /address@hidden For storing filenames that do
not fit into the main header. }*/
+../tar_texi/header.texi(,184) #define GNUTYPE_NAMES 'N'
+../tar_texi/header.texi(,185)
+../tar_texi/header.texi(,186) /address@hidden This is for sparse files. }*/
+../tar_texi/header.texi(,187) #define GNUTYPE_SPARSE 'S'
+../tar_texi/header.texi(,188)
+../tar_texi/header.texi(,189) /address@hidden This file is a tape/volume
header. Ignore it on extraction. }*/
+../tar_texi/header.texi(,190) #define GNUTYPE_VOLHDR 'V'
+../tar_texi/header.texi(,191)
+../tar_texi/header.texi(,192) /address@hidden Solaris extended header }*/
+../tar_texi/header.texi(,193) #define SOLARIS_XHDTYPE 'X'
+../tar_texi/header.texi(,194)
+../tar_texi/header.texi(,195) /address@hidden J@"org Schilling star header }*/
+../tar_texi/header.texi(,196)
+../tar_texi/header.texi(,197) struct star_header
+../tar_texi/header.texi(,198) @{ /address@hidden
byte offset }*/
+../tar_texi/header.texi(,199) char name[100]; /address@hidden
0 }*/
+../tar_texi/header.texi(,200) char mode[8]; /address@hidden
100 }*/
+../tar_texi/header.texi(,201) char uid[8]; /address@hidden
108 }*/
+../tar_texi/header.texi(,202) char gid[8]; /address@hidden
116 }*/
+../tar_texi/header.texi(,203) char size[12]; /address@hidden
124 }*/
+../tar_texi/header.texi(,204) char mtime[12]; /address@hidden
136 }*/
+../tar_texi/header.texi(,205) char chksum[8]; /address@hidden
148 }*/
+../tar_texi/header.texi(,206) char typeflag; /address@hidden
156 }*/
+../tar_texi/header.texi(,207) char linkname[100]; /address@hidden
157 }*/
+../tar_texi/header.texi(,208) char magic[6]; /address@hidden
257 }*/
+../tar_texi/header.texi(,209) char version[2]; /address@hidden
263 }*/
+../tar_texi/header.texi(,210) char uname[32]; /address@hidden
265 }*/
+../tar_texi/header.texi(,211) char gname[32]; /address@hidden
297 }*/
+../tar_texi/header.texi(,212) char devmajor[8]; /address@hidden
329 }*/
+../tar_texi/header.texi(,213) char devminor[8]; /address@hidden
337 }*/
+../tar_texi/header.texi(,214) char prefix[131]; /address@hidden
345 }*/
+../tar_texi/header.texi(,215) char atime[12]; /address@hidden
476 }*/
+../tar_texi/header.texi(,216) char ctime[12]; /address@hidden
488 }*/
+../tar_texi/header.texi(,217) /address@hidden
500 }*/
+../tar_texi/header.texi(,218) @};
+../tar_texi/header.texi(,219)
+../tar_texi/header.texi(,220) #define SPARSES_IN_STAR_HEADER 4
+../tar_texi/header.texi(,221) #define SPARSES_IN_STAR_EXT_HEADER 21
+../tar_texi/header.texi(,222)
+../tar_texi/header.texi(,223) struct star_in_header
+../tar_texi/header.texi(,224) @{
+../tar_texi/header.texi(,225) char fill[345]; /address@hidden 0
Everything that is before t_prefix }*/
+../tar_texi/header.texi(,226) char prefix[1]; /address@hidden 345
t_name prefix }*/
+../tar_texi/header.texi(,227) char fill2; /address@hidden 346 }*/
+../tar_texi/header.texi(,228) char fill3[8]; /address@hidden 347 }*/
+../tar_texi/header.texi(,229) char isextended; /address@hidden 355 }*/
+../tar_texi/header.texi(,230) struct sparse sp[SPARSES_IN_STAR_HEADER];
/address@hidden 356 }*/
+../tar_texi/header.texi(,231) char realsize[12]; /address@hidden 452
Actual size of the file }*/
+../tar_texi/header.texi(,232) char offset[12]; /address@hidden 464
Offset of multivolume contents }*/
+../tar_texi/header.texi(,233) char atime[12]; /address@hidden 476 }*/
+../tar_texi/header.texi(,234) char ctime[12]; /address@hidden 488 }*/
+../tar_texi/header.texi(,235) char mfill[8]; /address@hidden 500 }*/
+../tar_texi/header.texi(,236) char xmagic[4]; /address@hidden 508
"tar" }*/
+../tar_texi/header.texi(,237) @};
+../tar_texi/header.texi(,238)
+../tar_texi/header.texi(,239) struct star_ext_header
+../tar_texi/header.texi(,240) @{
+../tar_texi/header.texi(,241) struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
+../tar_texi/header.texi(,242) char isextended;
+../tar_texi/header.texi(,243) @};
+../tar_texi/header.texi(,244)
+../tar_texi/intern.texi(,74) @end smallexample
+../tar_texi/intern.texi(,75)
+../tar_texi/intern.texi(,76) All characters in header blocks are represented
by using 8-bit
+../tar_texi/intern.texi(,77) characters in the local variant of ASCII. Each
field within the
+../tar_texi/intern.texi(,78) structure is contiguous; that is, there is no
padding used within
+../tar_texi/intern.texi(,79) the structure. Each character on the archive
medium is stored
+../tar_texi/intern.texi(,80) contiguously.
+../tar_texi/intern.texi(,81)
+../tar_texi/intern.texi(,82) Bytes representing the contents of files (after
the header block
+../tar_texi/intern.texi(,83) of each file) are not translated in any way and
are not constrained
+../tar_texi/intern.texi(,84) to represent characters in any character set.
The @command{tar} format
+../tar_texi/intern.texi(,85) does not distinguish text files from binary
files, and no translation
+../tar_texi/intern.texi(,86) of file contents is performed.
+../tar_texi/intern.texi(,87)
+../tar_texi/intern.texi(,88) The @code{name}, @code{linkname}, @code{magic},
@code{uname}, and
+../tar_texi/intern.texi(,89) @code{gname} are null-terminated character
strings. All other fields
+../tar_texi/intern.texi(,90) are zero-filled octal numbers in ASCII. Each
numeric field of width
+../tar_texi/intern.texi(,91) @var{w} contains @var{w} minus 1 digits, and a
null.
+../tar_texi/intern.texi(,92)
+../tar_texi/intern.texi(,93) The @code{name} field is the file name of the
file, with directory names
+../tar_texi/intern.texi(,94) (if any) preceding the file name, separated by
slashes.
+../tar_texi/intern.texi(,95)
+../tar_texi/intern.texi(FIXME,96) @allow-recursion
+../tar_texi/intern.texi(FIXME,96) @quote-arg
+../tar_texi/intern.texi(FIXME,96)
+../tar_texi/intern.texi(,97)
+../tar_texi/intern.texi(,98) The @code{mode} field provides nine bits
specifying file permissions
+../tar_texi/intern.texi(,99) and three bits to specify the Set UID, Set GID,
and Save Text
+../tar_texi/intern.texi(,100) (@dfn{sticky}) modes. Values for these bits are
defined above.
+../tar_texi/intern.texi(,101) When special permissions are required to create
a file with a given
+../tar_texi/intern.texi(,102) mode, and the user restoring files from the
archive does not hold such
+../tar_texi/intern.texi(,103) permissions, the mode bit(s) specifying those
special permissions
+../tar_texi/intern.texi(,104) are ignored. Modes which are not supported by
the operating system
+../tar_texi/intern.texi(,105) restoring files from the archive will be
ignored. Unsupported modes
+../tar_texi/intern.texi(,106) should be faked up when creating or updating an
archive; e.g., the
+../tar_texi/intern.texi(,107) group permission could be copied from the
@emph{other} permission.
+../tar_texi/intern.texi(,108)
+../tar_texi/intern.texi(,109) The @code{uid} and @code{gid} fields are the
numeric user and group
+../tar_texi/intern.texi(,110) ID of the file owners, respectively. If the
operating system does
+../tar_texi/intern.texi(,111) not support numeric user or group IDs, these
fields should be ignored.
+../tar_texi/intern.texi(,112)
+../tar_texi/intern.texi(,113) The @code{size} field is the size of the file in
bytes; linked files
+../tar_texi/intern.texi(FIXME-xref,115) are archived with this field specified
as zero. ../tar_texi/intern.texi(FIXME-xref,115) @quote-arg
+../tar_texi/intern.texi(FIXME-xref,115)
+../tar_texi/intern.texi(,116)
+../tar_texi/intern.texi(,117) The @code{mtime} field is the data modification
time of the file at
+../tar_texi/intern.texi(,118) the time it was archived. It is the ASCII
representation of the octal
+../tar_texi/intern.texi(,119) value of the last time the file's contents were
modified, represented
+../tar_texi/intern.texi(,120) as an integer number of
+../tar_texi/intern.texi(,121) seconds since January 1, 1970, 00:00 Coordinated
Universal Time.
+../tar_texi/intern.texi(,122)
+../tar_texi/intern.texi(,123) The @code{chksum} field is the ASCII
representation of the octal value
+../tar_texi/intern.texi(,124) of the simple sum of all bytes in the header
block. Each 8-bit
+../tar_texi/intern.texi(,125) byte in the header is added to an unsigned
integer, initialized to
+../tar_texi/intern.texi(,126) zero, the precision of which shall be no less
than seventeen bits.
+../tar_texi/intern.texi(,127) When calculating the checksum, the @code{chksum}
field is treated as
+../tar_texi/intern.texi(,128) if it were all blanks.
+../tar_texi/intern.texi(,129)
+../tar_texi/intern.texi(,130) The @code{typeflag} field specifies the type of
file archived. If a
+../tar_texi/intern.texi(,131) particular implementation does not recognize or
permit the specified
+../tar_texi/intern.texi(,132) type, the file will be extracted as if it were a
regular file. As this
+../tar_texi/intern.texi(,133) action occurs, @command{tar} issues a warning to
the standard error.
+../tar_texi/intern.texi(,134)
+../tar_texi/intern.texi(,135) The @code{atime} and @code{ctime} fields are
used in making incremental
+../tar_texi/intern.texi(,136) backups; they store, respectively, the
particular file's access and
+../tar_texi/intern.texi(,137) status change times.
+../tar_texi/intern.texi(,138)
+../tar_texi/intern.texi(,139) The @code{offset} is used by the
@option{--multi-volume} (@option{-M}) option, when
+../tar_texi/intern.texi(,140) making a multi-volume archive. The offset is
number of bytes into
+../tar_texi/intern.texi(,141) the file that we need to restart at to continue
the file on the next
+../tar_texi/intern.texi(,142) tape, i.e., where we store the location that a
continued file is
+../tar_texi/intern.texi(,143) continued at.
+../tar_texi/intern.texi(,144)
+../tar_texi/intern.texi(,145) The following fields were added to deal with
sparse files. A file
+../tar_texi/intern.texi(,146) is @dfn{sparse} if it takes in unallocated
blocks which end up being
+../tar_texi/intern.texi(,147) represented as zeros, i.e., no useful data. A
test to see if a file
+../tar_texi/intern.texi(,148) is sparse is to look at the number blocks
allocated for it versus the
+../tar_texi/intern.texi(,149) number of characters in the file; if there are
fewer blocks allocated
+../tar_texi/intern.texi(,150) for the file than would normally be allocated
for a file of that
+../tar_texi/intern.texi(,151) size, then the file is sparse. This is the
method @command{tar} uses to
+../tar_texi/intern.texi(,152) detect a sparse file, and once such a file is
detected, it is treated
+../tar_texi/intern.texi(,153) differently from non-sparse files.
+../tar_texi/intern.texi(,154)
+../tar_texi/intern.texi(,155) Sparse files are often @code{dbm} files, or
other database-type files
+../tar_texi/intern.texi(,156) which have data at some points and emptiness in
the greater part of
+../tar_texi/intern.texi(,157) the file. Such files can appear to be very
large when an @samp{ls
+../tar_texi/intern.texi(,158) -l} is done on them, when in truth, there may be
a very small amount
+../tar_texi/intern.texi(,159) of important data contained in the file. It is
thus undesirable
+../tar_texi/intern.texi(,160) to have @command{tar} think that it must back up
this entire file, as
+../tar_texi/intern.texi(,161) great quantities of room are wasted on empty
blocks, which can lead
+../tar_texi/intern.texi(,162) to running out of room on a tape far earlier
than is necessary.
+../tar_texi/intern.texi(,163) Thus, sparse files are dealt with so that these
empty blocks are
+../tar_texi/intern.texi(,164) not written to the tape. Instead, what is
written to the tape is a
+../tar_texi/intern.texi(,165) description, of sorts, of the sparse file: where
the holes are, how
+../tar_texi/intern.texi(,166) big the holes are, and how much data is found at
the end of the hole.
+../tar_texi/intern.texi(,167) This way, the file takes up potentially far less
room on the tape,
+../tar_texi/intern.texi(,168) and when the file is extracted later on, it will
look exactly the way
+../tar_texi/intern.texi(,169) it looked beforehand. The following is a
description of the fields
+../tar_texi/intern.texi(,170) used to handle a sparse file:
+../tar_texi/intern.texi(,171)
+../tar_texi/intern.texi(,172) The @code{sp} is an array of @code{struct
sparse}. Each @code{struct
+../tar_texi/intern.texi(,173) sparse} contains two 12-character strings which
represent an offset
+../tar_texi/intern.texi(,174) into the file and a number of bytes to be
written at that offset.
+../tar_texi/intern.texi(,175) The offset is absolute, and not relative to the
offset in preceding
+../tar_texi/intern.texi(,176) array element.
+../tar_texi/intern.texi(,177)
+../tar_texi/intern.texi(,178) The header can hold four of these @code{struct
sparse} at the moment;
+../tar_texi/intern.texi(,179) if more are needed, they are not stored in the
header.
+../tar_texi/intern.texi(,180)
+../tar_texi/intern.texi(,181) The @code{isextended} flag is set when an
@code{extended_header}
+../tar_texi/intern.texi(,182) is needed to deal with a file. Note that this
means that this flag
+../tar_texi/intern.texi(,183) can only be set when dealing with a sparse file,
and it is only set
+../tar_texi/intern.texi(,184) in the event that the description of the file
will not fit in the
+../tar_texi/intern.texi(,185) allotted room for sparse structures in the
header. In other words,
+../tar_texi/intern.texi(,186) an extended_header is needed.
+../tar_texi/intern.texi(,187)
+../tar_texi/intern.texi(,188) The @code{extended_header} structure is used for
sparse files which
+../tar_texi/intern.texi(,189) need more sparse structures than can fit in the
header. The header can
+../tar_texi/intern.texi(,190) fit 4 such structures; if more are needed, the
flag @code{isextended}
+../tar_texi/intern.texi(,191) gets set and the next block is an
@code{extended_header}.
+../tar_texi/intern.texi(,192)
+../tar_texi/intern.texi(,193) Each @code{extended_header} structure contains
an array of 21
+../tar_texi/intern.texi(,194) sparse structures, along with a similar
@code{isextended} flag
+../tar_texi/intern.texi(,195) that the header had. There can be an
indeterminate number of such
+../tar_texi/intern.texi(,196) @code{extended_header}s to describe a sparse
file.
+../tar_texi/intern.texi(,197)
+../tar_texi/intern.texi(,198) @table @asis
+../tar_texi/intern.texi(,199)
+../tar_texi/intern.texi(,200) @item @code{REGTYPE}
+../tar_texi/intern.texi(,201) @itemx @code{AREGTYPE}
+../tar_texi/intern.texi(,202) These flags represent a regular file. In order
to be compatible
+../tar_texi/intern.texi(,203) with older versions of @command{tar}, a
@code{typeflag} value of
+../tar_texi/intern.texi(,204) @code{AREGTYPE} should be silently recognized as
a regular file.
+../tar_texi/intern.texi(,205) New archives should be created using
@code{REGTYPE}. Also, for
+../tar_texi/intern.texi(,206) backward compatibility, @command{tar} treats a
regular file whose name
+../tar_texi/intern.texi(,207) ends with a slash as a directory.
+../tar_texi/intern.texi(,208)
+../tar_texi/intern.texi(,209) @item @code{LNKTYPE}
+../tar_texi/intern.texi(,210) This flag represents a file linked to another
file, of any type,
+../tar_texi/intern.texi(,211) previously archived. Such files are identified
in Unix by each
+../tar_texi/intern.texi(,212) file having the same device and inode number.
The linked-to name is
+../tar_texi/intern.texi(,213) specified in the @code{linkname} field with a
trailing null.
+../tar_texi/intern.texi(,214)
+../tar_texi/intern.texi(,215) @item @code{SYMTYPE}
+../tar_texi/intern.texi(,216) This represents a symbolic link to another file.
The linked-to name
+../tar_texi/intern.texi(,217) is specified in the @code{linkname} field with a
trailing null.
+../tar_texi/intern.texi(,218)
+../tar_texi/intern.texi(,219) @item @code{CHRTYPE}
+../tar_texi/intern.texi(,220) @itemx @code{BLKTYPE}
+../tar_texi/intern.texi(,221) These represent character special files and
block special files
+../tar_texi/intern.texi(,222) respectively. In this case the @code{devmajor}
and @code{devminor}
+../tar_texi/intern.texi(,223) fields will contain the major and minor device
numbers respectively.
+../tar_texi/intern.texi(,224) Operating systems may map the device
specifications to their own
+../tar_texi/intern.texi(,225) local specification, or may ignore the entry.
+../tar_texi/intern.texi(,226)
+../tar_texi/intern.texi(,227) @item @code{DIRTYPE}
+../tar_texi/intern.texi(,228) This flag specifies a directory or
sub-directory. The directory
+../tar_texi/intern.texi(,229) name in the @code{name} field should end with a
slash. On systems where
+../tar_texi/intern.texi(,230) disk allocation is performed on a directory
basis, the @code{size} field
+../tar_texi/intern.texi(,231) will contain the maximum number of bytes (which
may be rounded to
+../tar_texi/intern.texi(,232) the nearest disk block allocation unit) which
the directory may
+../tar_texi/intern.texi(,233) hold. A @code{size} field of zero indicates no
such limiting. Systems
+../tar_texi/intern.texi(,234) which do not support limiting in this manner
should ignore the
+../tar_texi/intern.texi(,235) @code{size} field.
+../tar_texi/intern.texi(,236)
+../tar_texi/intern.texi(,237) @item @code{FIFOTYPE}
+../tar_texi/intern.texi(,238) This specifies a FIFO special file. Note that
the archiving of a
+../tar_texi/intern.texi(,239) FIFO file archives the existence of this file
and not its contents.
+../tar_texi/intern.texi(,240)
+../tar_texi/intern.texi(,241) @item @code{CONTTYPE}
+../tar_texi/intern.texi(,242) This specifies a contiguous file, which is the
same as a normal
+../tar_texi/intern.texi(,243) file except that, in operating systems which
support it, all its
+../tar_texi/intern.texi(,244) space is allocated contiguously on the disk.
Operating systems
+../tar_texi/intern.texi(,245) which do not allow contiguous allocation should
silently treat this
+../tar_texi/intern.texi(,246) type as a normal file.
+../tar_texi/intern.texi(,247)
+../tar_texi/intern.texi(,248) @item @code{A} @dots{} @code{Z}
+../tar_texi/intern.texi(,249) These are reserved for custom implementations.
Some of these are
+../tar_texi/intern.texi(,250) used in the @acronym{GNU} modified format, as
described below.
+../tar_texi/intern.texi(,251)
+../tar_texi/intern.texi(,252) @end table
+../tar_texi/intern.texi(,253)
+../tar_texi/intern.texi(,254) Other values are reserved for specification in
future revisions of
+../tar_texi/intern.texi(,255) the P1003 standard, and should not be used by
any @command{tar} program.
+../tar_texi/intern.texi(,256)
+../tar_texi/intern.texi(,257) The @code{magic} field indicates that this
archive was output in
+../tar_texi/intern.texi(,258) the P1003 archive format. If this field
contains @code{TMAGIC},
+../tar_texi/intern.texi(,259) the @code{uname} and @code{gname} fields will
contain the ASCII
+../tar_texi/intern.texi(,260) representation of the owner and group of the
file respectively.
+../tar_texi/intern.texi(,261) If found, the user and group IDs are used rather
than the values in
+../tar_texi/intern.texi(,262) the @code{uid} and @code{gid} fields.
+../tar_texi/intern.texi(,263)
+../tar_texi/intern.texi(,264) For references, see ISO/IEC 9945-1:1990 or IEEE
Std 1003.1-1990, pages
+../tar_texi/intern.texi(,265) 169-173 (section 10.1) for
@cite{Archive/Interchange File Format}; and
+../tar_texi/intern.texi(,266) IEEE Std 1003.2-1992, pages 380-388 (section
4.48) and pages 936-940
+../tar_texi/intern.texi(,267) (section E.4.48) for @cite{pax - Portable
archive interchange}.
+../tar_texi/intern.texi(,268)
+../tar_texi/intern.texi(,269) @node Extensions
+../tar_texi/intern.texi(,270) @unnumberedsec @acronym{GNU} Extensions to the
Archive Format
+../tar_texi/intern.texi(UNREVISED,271) @quotation
+../tar_texi/intern.texi(UNREVISED,271) @emph{(This message will disappear,
once this node revised.)}
+../tar_texi/intern.texi(UNREVISED,271) @end quotation
+../tar_texi/intern.texi(UNREVISED,271)
+../tar_texi/intern.texi(,272)
+../tar_texi/intern.texi(,273) The @acronym{GNU} format uses additional file
types to describe new types of
+../tar_texi/intern.texi(,274) files in an archive. These are listed below.
+../tar_texi/intern.texi(,275)
+../tar_texi/intern.texi(,276) @table @code
+../tar_texi/intern.texi(,277) @item GNUTYPE_DUMPDIR
+../tar_texi/intern.texi(,278) @itemx 'D'
+../tar_texi/intern.texi(,279) This represents a directory and a list of files
created by the
+../tar_texi/intern.texi(,280) @option{--incremental} (@option{-G}) option.
The @code{size} field gives the total
+../tar_texi/intern.texi(,281) size of the associated list of files. Each file
name is preceded by
+../tar_texi/intern.texi(,282) either a @samp{Y} (the file should be in this
archive) or an @samp{N}.
+../tar_texi/intern.texi(,283) (The file is a directory, or is not stored in
the archive.) Each file
+../tar_texi/intern.texi(,284) name is terminated by a null. There is an
additional null after the
+../tar_texi/intern.texi(,285) last file name.
+../tar_texi/intern.texi(,286)
+../tar_texi/intern.texi(,287) @item GNUTYPE_MULTIVOL
+../tar_texi/intern.texi(,288) @itemx 'M'
+../tar_texi/intern.texi(,289) This represents a file continued from another
volume of a multi-volume
+../tar_texi/intern.texi(,290) archive created with the @option{--multi-volume}
(@option{-M}) option. The original
+../tar_texi/intern.texi(,291) type of the file is not given here. The
@code{size} field gives the
+../tar_texi/intern.texi(,292) maximum size of this piece of the file (assuming
the volume does
+../tar_texi/intern.texi(,293) not end before the file is written out). The
@code{offset} field
+../tar_texi/intern.texi(,294) gives the offset from the beginning of the file
where this part of
+../tar_texi/intern.texi(,295) the file begins. Thus @code{size} plus
@code{offset} should equal
+../tar_texi/intern.texi(,296) the original size of the file.
+../tar_texi/intern.texi(,297)
+../tar_texi/intern.texi(,298) @item GNUTYPE_SPARSE
+../tar_texi/intern.texi(,299) @itemx 'S'
+../tar_texi/intern.texi(,300) This flag indicates that we are dealing with a
sparse file. Note
+../tar_texi/intern.texi(,301) that archiving a sparse file requires special
operations to find
+../tar_texi/intern.texi(,302) holes in the file, which mark the positions of
these holes, along
+../tar_texi/intern.texi(,303) with the number of bytes of data to be found
after the hole.
+../tar_texi/intern.texi(,304)
+../tar_texi/intern.texi(,305) @item GNUTYPE_VOLHDR
+../tar_texi/intern.texi(,306) @itemx 'V'
+../tar_texi/intern.texi(,307) This file type is used to mark the volume header
that was given with
+../tar_texi/intern.texi(,308) the @address@hidden (@option{-V
@var{archive-label}}) option when the archive was created. The @code{name}
+../tar_texi/intern.texi(,309) field contains the @code{name} given after the
@address@hidden (@option{-V @var{archive-label}}) option.
+../tar_texi/intern.texi(,310) The @code{size} field is zero. Only the first
file in each volume
+../tar_texi/intern.texi(,311) of an archive should have this type.
+../tar_texi/intern.texi(,312)
+../tar_texi/intern.texi(,313) @end table
+../tar_texi/intern.texi(,314)
+../tar_texi/intern.texi(,315) You may have trouble reading a @acronym{GNU}
format archive on a
+../tar_texi/intern.texi(,316) address@hidden system if the options
@option{--incremental} (@option{-G}),
+../tar_texi/intern.texi(,317) @option{--multi-volume} (@option{-M}),
@option{--sparse} (@option{-S}), or @address@hidden (@option{-V
@var{archive-label}}) were
+../tar_texi/intern.texi(,318) used when writing the archive. In general, if
@command{tar} does not
+../tar_texi/intern.texi(,319) use the @acronym{GNU}-added fields of the
header, other versions of
+../tar_texi/intern.texi(,320) @command{tar} should be able to read the
archive. Otherwise, the
+../tar_texi/intern.texi(,321) @command{tar} program will give an error, the
most likely one being a
+../tar_texi/intern.texi(,322) checksum error.
+../tar_texi/intern.texi(,323)
+../tar_texi/intern.texi(,324) @node Sparse Formats
+../tar_texi/intern.texi(,325) @unnumberedsec Storing Sparse Files
+../tar_texi/sparse.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/sparse.texi(,2) @c Copyright (C) 2006 Free Software Foundation,
Inc.
+../tar_texi/sparse.texi(,3) @c This file is distributed under GFDL 1.1 or any
later version
+../tar_texi/sparse.texi(,4) @c published by the Free Software Foundation.
+../tar_texi/sparse.texi(,5)
+../tar_texi/sparse.texi(,6) @cindex sparse formats
+../tar_texi/sparse.texi(,7) @cindex sparse versions
+../tar_texi/sparse.texi(,8) The notion of sparse file, and the ways of
handling it from the point
+../tar_texi/sparse.texi(GNUTAR,9) of view of ../tar_texi/sparse.texi(GNUTAR,9)
@acronym{GNU} @command{tar}../tar_texi/sparse.texi(GNUTAR,9) user have been
described in detail in
+../tar_texi/sparse.texi(GNUTAR,10) @ref{sparse}. This chapter describes the
internal format ../tar_texi/sparse.texi(GNUTAR,10) @acronym{GNU}
@command{tar}../tar_texi/sparse.texi(GNUTAR,10)
+../tar_texi/sparse.texi(,11) uses to store such files.
+../tar_texi/sparse.texi(,12)
+../tar_texi/sparse.texi(GNUTAR,13) The support for sparse files in
../tar_texi/sparse.texi(GNUTAR,13) @acronym{GNU}
@command{tar}../tar_texi/sparse.texi(GNUTAR,13) has a long history. The
+../tar_texi/sparse.texi(,14) earliest version featuring this support that I
was able to find was 1.09,
+../tar_texi/sparse.texi(,15) released in November, 1990. The format
introduced back then is called
+../tar_texi/sparse.texi(,16) @dfn{old GNU} sparse format and in spite of the
fact that its design
+../tar_texi/sparse.texi(GNUTAR,17) contained many flaws, it was the only
format ../tar_texi/sparse.texi(GNUTAR,17) @acronym{GNU}
@command{tar}../tar_texi/sparse.texi(GNUTAR,17) supported
+../tar_texi/sparse.texi(,18) until version 1.14 (May, 2004), which introduced
initial support for
+../tar_texi/sparse.texi(,19) sparse archives in @acronym{PAX} archives
(@pxref{posix}). This
+../tar_texi/sparse.texi(,20) format was not free from design flows, either and
it was subsequently
+../tar_texi/sparse.texi(,21) improved in versions 1.15.2 (November, 2005) and
1.15.92 (June,
+../tar_texi/sparse.texi(,22) 2006).
+../tar_texi/sparse.texi(,23)
+../tar_texi/sparse.texi(GNUTAR,24) In addition to GNU sparse format,
../tar_texi/sparse.texi(GNUTAR,24) @acronym{GNU}
@command{tar}../tar_texi/sparse.texi(GNUTAR,24) is able to read and
+../tar_texi/sparse.texi(,25) extract sparse files archived by @command{star}.
+../tar_texi/sparse.texi(,26)
+../tar_texi/sparse.texi(,27) The following subsections describe each format in
detail.
+../tar_texi/sparse.texi(,28)
+../tar_texi/sparse.texi(,29) @menu
+../tar_texi/sparse.texi(,30) * Old GNU Format::
+../tar_texi/sparse.texi(,31) * PAX 0:: PAX Format, Versions 0.0
and 0.1
+../tar_texi/sparse.texi(,32) * PAX 1:: PAX Format, Version 1.0
+../tar_texi/sparse.texi(,33) @end menu
+../tar_texi/sparse.texi(,34)
+../tar_texi/sparse.texi(,35) @node Old GNU Format
+../tar_texi/sparse.texi(,36) @appendixsubsec Old GNU Format
+../tar_texi/sparse.texi(,37)
+../tar_texi/sparse.texi(,38) @cindex sparse formats, Old GNU
+../tar_texi/sparse.texi(,39) @cindex Old GNU sparse format
+../tar_texi/sparse.texi(,40) The format introduced some time around 1990 (v.
1.09). It was
+../tar_texi/sparse.texi(,41) designed on top of standard @code{ustar} headers
in such an
+../tar_texi/sparse.texi(,42) unfortunate way that some of its fields overwrote
fields required by
+../tar_texi/sparse.texi(,43) POSIX.
+../tar_texi/sparse.texi(,44)
+../tar_texi/sparse.texi(,45) An old GNU sparse header is designated by type
@samp{S}
+../tar_texi/sparse.texi(,46) (@code{GNUTYPE_SPARSE}) and has the following
layout:
+../tar_texi/sparse.texi(,47)
+../tar_texi/sparse.texi(,48) @multitable @columnfractions 0.10 0.10 0.20 0.20
0.40
+../tar_texi/sparse.texi(,49) @headitem Offset @tab Size @tab Name @tab Data
type @tab Contents
+../tar_texi/sparse.texi(,50) @item 0 @tab 345 @tab @tab N/A
@tab Not used.
+../tar_texi/sparse.texi(,51) @item 345 @tab 12 @tab atime @tab
Number @tab @code{atime} of the file.
+../tar_texi/sparse.texi(,52) @item 357 @tab 12 @tab ctime @tab
Number @tab @code{ctime} of the file .
+../tar_texi/sparse.texi(,53) @item 369 @tab 12 @tab offset @tab
Number @tab For
+../tar_texi/sparse.texi(,54) multivolume archives: the offset of the start of
this volume.
+../tar_texi/sparse.texi(,55) @item 381 @tab 4 @tab @tab N/A
@tab Not used.
+../tar_texi/sparse.texi(,56) @item 385 @tab 1 @tab @tab N/A
@tab Not used.
+../tar_texi/sparse.texi(,57) @item 386 @tab 96 @tab sp @tab
@code{sparse_header} @tab (4 entries) File map.
+../tar_texi/sparse.texi(,58) @item 482 @tab 1 @tab isextended @tab
Bool @tab @code{1} if an
+../tar_texi/sparse.texi(,59) extension sparse header follows, @code{0}
otherwise.
+../tar_texi/sparse.texi(,60) @item 483 @tab 12 @tab realsize @tab
Number @tab Real size of the file.
+../tar_texi/sparse.texi(,61) @end multitable
+../tar_texi/sparse.texi(,62)
+../tar_texi/sparse.texi(,63) Each of @code{sparse_header} object at offset 386
describes a single
+../tar_texi/sparse.texi(,64) data chunk. It has the following structure:
+../tar_texi/sparse.texi(,65)
+../tar_texi/sparse.texi(,66) @multitable @columnfractions 0.10 0.10 0.20 0.60
+../tar_texi/sparse.texi(,67) @headitem Offset @tab Size @tab Data type @tab
Contents
+../tar_texi/sparse.texi(,68) @item 0 @tab 12 @tab Number @tab
Offset of the
+../tar_texi/sparse.texi(,69) beginning of the chunk.
+../tar_texi/sparse.texi(,70) @item 12 @tab 12 @tab Number @tab
Size of the chunk.
+../tar_texi/sparse.texi(,71) @end multitable
+../tar_texi/sparse.texi(,72)
+../tar_texi/sparse.texi(,73) If the member contains more than four chunks, the
@code{isextended}
+../tar_texi/sparse.texi(,74) field of the header has the value @code{1} and
the main header is
+../tar_texi/sparse.texi(,75) followed by one or more @dfn{extension headers}.
Each such header has
+../tar_texi/sparse.texi(,76) the following structure:
+../tar_texi/sparse.texi(,77)
+../tar_texi/sparse.texi(,78) @multitable @columnfractions 0.10 0.10 0.20 0.20
0.40
+../tar_texi/sparse.texi(,79) @headitem Offset @tab Size @tab Name @tab Data
type @tab Contents
+../tar_texi/sparse.texi(,80) @item 0 @tab 21 @tab sp @tab
@code{sparse_header} @tab
+../tar_texi/sparse.texi(,81) (21 entires) File map.
+../tar_texi/sparse.texi(,82) @item 504 @tab 1 @tab isextended @tab
Bool @tab @code{1} if an
+../tar_texi/sparse.texi(,83) extension sparse header follows, or @code{0}
otherwise.
+../tar_texi/sparse.texi(,84) @end multitable
+../tar_texi/sparse.texi(,85)
+../tar_texi/sparse.texi(,86) A header with @code{isextended=0} ends the map.
+../tar_texi/sparse.texi(,87)
+../tar_texi/sparse.texi(,88) @node PAX 0
+../tar_texi/sparse.texi(,89) @appendixsubsec PAX Format, Versions 0.0 and 0.1
+../tar_texi/sparse.texi(,90)
+../tar_texi/sparse.texi(,91) @cindex sparse formats, v.0.0
+../tar_texi/sparse.texi(,92) There are two formats available in this branch.
The version @code{0.0}
+../tar_texi/sparse.texi(,93) is the initial version of sparse format used by
@command{tar}
+../tar_texi/sparse.texi(,94) versions 1.14--1.15.1. The sparse file map is
kept in extended
+../tar_texi/sparse.texi(,95) (@code{x}) PAX header variables:
+../tar_texi/sparse.texi(,96)
+../tar_texi/sparse.texi(,97) @table @code
+../tar_texi/sparse.texi(,98) @vrindex GNU.sparse.size, extended header variable
+../tar_texi/sparse.texi(,99) @item GNU.sparse.size
+../tar_texi/sparse.texi(,100) Real size of the stored file
+../tar_texi/sparse.texi(,101)
+../tar_texi/sparse.texi(,102) @item GNU.sparse.numblocks
+../tar_texi/sparse.texi(,103) @vrindex GNU.sparse.numblocks, extended header
variable
+../tar_texi/sparse.texi(,104) Number of blocks in the sparse map
+../tar_texi/sparse.texi(,105)
+../tar_texi/sparse.texi(,106) @item GNU.sparse.offset
+../tar_texi/sparse.texi(,107) @vrindex GNU.sparse.offset, extended header
variable
+../tar_texi/sparse.texi(,108) Offset of the data block
+../tar_texi/sparse.texi(,109)
+../tar_texi/sparse.texi(,110) @item GNU.sparse.numbytes
+../tar_texi/sparse.texi(,111) @vrindex GNU.sparse.numbytes, extended header
variable
+../tar_texi/sparse.texi(,112) Size of the data block
+../tar_texi/sparse.texi(,113) @end table
+../tar_texi/sparse.texi(,114)
+../tar_texi/sparse.texi(,115) The latter two variables repeat for each data
block, so the overall
+../tar_texi/sparse.texi(,116) structure is like this:
+../tar_texi/sparse.texi(,117)
+../tar_texi/sparse.texi(,118) @smallexample
+../tar_texi/sparse.texi(,119) @group
+../tar_texi/sparse.texi(,120) address@hidden
+../tar_texi/sparse.texi(,121) address@hidden
+../tar_texi/sparse.texi(,122) repeat @var{numblocks} times
+../tar_texi/sparse.texi(,123) address@hidden
+../tar_texi/sparse.texi(,124) address@hidden
+../tar_texi/sparse.texi(,125) end repeat
+../tar_texi/sparse.texi(,126) @end group
+../tar_texi/sparse.texi(,127) @end smallexample
+../tar_texi/sparse.texi(,128)
+../tar_texi/sparse.texi(,129) This format presented the following two problems:
+../tar_texi/sparse.texi(,130)
+../tar_texi/sparse.texi(,131) @enumerate 1
+../tar_texi/sparse.texi(,132) @item
+../tar_texi/sparse.texi(,133) Whereas the POSIX specification allows a
variable to appear multiple
+../tar_texi/sparse.texi(,134) times in a header, it requires that only the
last occurrence be
+../tar_texi/sparse.texi(,135) meaningful. Thus, multiple ocurrences of
@code{GNU.sparse.offset} and
+../tar_texi/sparse.texi(,136) @code{GNU.sparse.numbytes} are conficting with
the POSIX specs.
+../tar_texi/sparse.texi(,137)
+../tar_texi/sparse.texi(,138) @item
+../tar_texi/sparse.texi(,139) Attempting to extract such archives using a
third-party @command{tar}s
+../tar_texi/sparse.texi(,140) results in extraction of sparse files in
@emph{compressed form}. If
+../tar_texi/sparse.texi(,141) the @command{tar} implementation in question
does not support POSIX
+../tar_texi/sparse.texi(,142) format, it will also extract a file containing
extension header
+../tar_texi/sparse.texi(,143) attributes. This file can be used to expand the
file to its original
+../tar_texi/sparse.texi(,144) state. However, posix-aware @command{tar}s will
usually ignore the
+../tar_texi/sparse.texi(,145) unknown variables, which makes restoring the
file more
+../tar_texi/sparse.texi(,146) difficult. @xref{extracting sparse v.0.x,
Extraction of sparse
+../tar_texi/sparse.texi(,147) members in v.0.0 format}, for the detailed
description of how to
+../tar_texi/sparse.texi(,148) restore such members using non-GNU
@command{tar}s.
+../tar_texi/sparse.texi(,149) @end enumerate
+../tar_texi/sparse.texi(,150)
+../tar_texi/sparse.texi(,151) @cindex sparse formats, v.0.1
+../tar_texi/sparse.texi(GNUTAR,152) @acronym{GNU}
@command{tar}../tar_texi/sparse.texi(GNUTAR,152) 1.15.2 introduced sparse
format version @code{0.1}, which
+../tar_texi/sparse.texi(,153) attempted to solve these problems. As its
predecessor, this format
+../tar_texi/sparse.texi(,154) stores sparse map in the extended POSIX header.
It retains
+../tar_texi/sparse.texi(,155) @code{GNU.sparse.size} and
@code{GNU.sparse.numblocks} variables, but
+../tar_texi/sparse.texi(,156) instead of
@code{GNU.sparse.offset}/@code{GNU.sparse.numbytes} pairs
+../tar_texi/sparse.texi(,157) it uses a single variable:
+../tar_texi/sparse.texi(,158)
+../tar_texi/sparse.texi(,159) @table @code
+../tar_texi/sparse.texi(,160) @item GNU.sparse.map
+../tar_texi/sparse.texi(,161) @vrindex GNU.sparse.map, extended header variable
+../tar_texi/sparse.texi(,162) Map of non-null data chunks. It is a string
consisting of
+../tar_texi/sparse.texi(,163) comma-separated values
"@var{offset},@var{size}[,@var{offset-1},@var{size-1}...]"
+../tar_texi/sparse.texi(,164) @end table
+../tar_texi/sparse.texi(,165)
+../tar_texi/sparse.texi(,166) To address the 2nd problem, the @code{name}
field in @code{ustar}
+../tar_texi/sparse.texi(,167) is replaced with a special name, constructed
using the following pattern:
+../tar_texi/sparse.texi(,168)
+../tar_texi/sparse.texi(,169) @smallexample
+../tar_texi/sparse.texi(,170) %d/GNUSparseFile.%p/%f
+../tar_texi/sparse.texi(,171) @end smallexample
+../tar_texi/sparse.texi(,172)
+../tar_texi/sparse.texi(,173) @vrindex GNU.sparse.name, extended header
variable
+../tar_texi/sparse.texi(,174) The real name of the sparse file is stored in
the variable
+../tar_texi/sparse.texi(,175) @code{GNU.sparse.name}. Thus, those
@command{tar} implementations
+../tar_texi/sparse.texi(,176) that are not aware of GNU extensions will at
least extract the files
+../tar_texi/sparse.texi(,177) into separate directories, giving the user a
possibility to expand it
+../tar_texi/sparse.texi(,178) afterwards. @xref{extracting sparse v.0.x,
Extraction of sparse
+../tar_texi/sparse.texi(,179) members in v.0.1 format}, for the detailed
description of how to
+../tar_texi/sparse.texi(,180) restore such members using non-GNU
@command{tar}s.
+../tar_texi/sparse.texi(,181)
+../tar_texi/sparse.texi(,182) The resulting @code{GNU.sparse.map} string can
be @emph{very} long.
+../tar_texi/sparse.texi(,183) Although POSIX does not impose any limit on the
length of a @code{x}
+../tar_texi/sparse.texi(,184) header variable, this possibly can confuse some
tars.
+../tar_texi/sparse.texi(,185)
+../tar_texi/sparse.texi(,186) @node PAX 1
+../tar_texi/sparse.texi(,187) @appendixsubsec PAX Format, Version 1.0
+../tar_texi/sparse.texi(,188)
+../tar_texi/sparse.texi(,189) @cindex sparse formats, v.1.0
+../tar_texi/sparse.texi(GNUTAR,190) The version @code{1.0} of sparse format
was introduced with ../tar_texi/sparse.texi(GNUTAR,190) @acronym{GNU}
@command{tar}../tar_texi/sparse.texi(GNUTAR,190)
+../tar_texi/sparse.texi(,191) 1.15.92. Its main objective was to make the
resulting file
+../tar_texi/sparse.texi(,192) extractable with little effort even by non-posix
aware @command{tar}
+../tar_texi/sparse.texi(,193) implementations. Starting from this version,
the extended header
+../tar_texi/sparse.texi(,194) preceding a sparse member always contains the
following variables that
+../tar_texi/sparse.texi(,195) identify the format being used:
+../tar_texi/sparse.texi(,196)
+../tar_texi/sparse.texi(,197) @table @code
+../tar_texi/sparse.texi(,198) @item GNU.sparse.major
+../tar_texi/sparse.texi(,199) @vrindex GNU.sparse.major, extended header
variable
+../tar_texi/sparse.texi(,200) Major version
+../tar_texi/sparse.texi(,201)
+../tar_texi/sparse.texi(,202) @item GNU.sparse.minor
+../tar_texi/sparse.texi(,203) @vrindex GNU.sparse.minor, extended header
variable
+../tar_texi/sparse.texi(,204) Minor version
+../tar_texi/sparse.texi(,205) @end table
+../tar_texi/sparse.texi(,206)
+../tar_texi/sparse.texi(,207) The @code{name} field in @code{ustar} header
contains a special name,
+../tar_texi/sparse.texi(,208) constructed using the following pattern:
+../tar_texi/sparse.texi(,209)
+../tar_texi/sparse.texi(,210) @smallexample
+../tar_texi/sparse.texi(,211) %d/GNUSparseFile.%p/%f
+../tar_texi/sparse.texi(,212) @end smallexample
+../tar_texi/sparse.texi(,213)
+../tar_texi/sparse.texi(,214) @vrindex GNU.sparse.name, extended header
variable, in v.1.0
+../tar_texi/sparse.texi(,215) @vrindex GNU.sparse.realsize, extended header
variable
+../tar_texi/sparse.texi(,216) The real name of the sparse file is stored in
the variable
+../tar_texi/sparse.texi(,217) @code{GNU.sparse.name}. The real size of the
file is stored in the
+../tar_texi/sparse.texi(,218) variable @code{GNU.sparse.realsize}.
+../tar_texi/sparse.texi(,219)
+../tar_texi/sparse.texi(,220) The sparse map itself is stored in the file data
block, preceding the actual
+../tar_texi/sparse.texi(,221) file data. It consists of a series of octal
numbers of arbitrary length, delimited
+../tar_texi/sparse.texi(,222) by newlines. The map is padded with nulls to the
nearest block boundary.
+../tar_texi/sparse.texi(,223)
+../tar_texi/sparse.texi(,224) The first number gives the number of entries in
the map. Following are map entries,
+../tar_texi/sparse.texi(,225) each one consisting of two numbers giving the
offset and size of the
+../tar_texi/sparse.texi(,226) data block it describes.
+../tar_texi/sparse.texi(,227)
+../tar_texi/sparse.texi(,228) The format is designed in such a way that
non-posix aware tars and tars not
+../tar_texi/sparse.texi(,229) supporting @code{GNU.sparse.*} keywords will
extract each sparse file
+../tar_texi/sparse.texi(,230) in its condensed form with the file map
prepended and will place it
+../tar_texi/sparse.texi(,231) into a separate directory. Then, using a simple
program it would be
+../tar_texi/sparse.texi(GNUTAR,232) possible to expand the file to its
original form even without ../tar_texi/sparse.texi(GNUTAR,232) @acronym{GNU}
@command{tar}../tar_texi/sparse.texi(GNUTAR,232) .
+../tar_texi/sparse.texi(,233) @xref{Sparse Recovery}, for the detailed
information on how to extract
+../tar_texi/sparse.texi(GNUTAR,234) sparse members without
../tar_texi/sparse.texi(GNUTAR,234) @acronym{GNU}
@command{tar}../tar_texi/sparse.texi(GNUTAR,234) .
+../tar_texi/sparse.texi(,235)
+../tar_texi/intern.texi(,327)
+../tar_texi/intern.texi(,328) @node Snapshot Files
+../tar_texi/intern.texi(,329) @unnumberedsec Format of the Incremental
Snapshot Files
+../tar_texi/snapshot.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/snapshot.texi(,2) @c Copyright (C) 2005 Free Software Foundation,
Inc.
+../tar_texi/snapshot.texi(,3) @c Written by Sergey Poznyakoff
+../tar_texi/snapshot.texi(,4) @c This file is distributed under GFDL 1.1 or
any later version
+../tar_texi/snapshot.texi(,5) @c published by the Free Software Foundation.
+../tar_texi/snapshot.texi(,6)
+../tar_texi/snapshot.texi(,7) A @dfn{snapshot file} (or @dfn{directory
file}) is created during
+../tar_texi/snapshot.texi(,8) incremental backups (@pxref{Incremental Dumps}).
It
+../tar_texi/snapshot.texi(,9) contains the status of the filesystem at the
time of the dump and is
+../tar_texi/snapshot.texi(,10) used to determine which files were modified
since the last backup.
+../tar_texi/snapshot.texi(,11)
+../tar_texi/snapshot.texi(GNUTAR,12) ../tar_texi/snapshot.texi(GNUTAR,12)
@acronym{GNU} @command{tar}../tar_texi/snapshot.texi(GNUTAR,12) version
1.15.92 supports two snapshot file
+../tar_texi/snapshot.texi(,13) formats. The first format, called @dfn{format
0}, is the one used by
+../tar_texi/snapshot.texi(GNUTAR,14) @acronym{GNU}
@command{tar}../tar_texi/snapshot.texi(GNUTAR,14) versions up to 1.15.1. The
second format, called @dfn{format
+../tar_texi/snapshot.texi(,15) 1} is an extended version of this format, that
contains more metadata
+../tar_texi/snapshot.texi(,16) and allows for further extensions.
+../tar_texi/snapshot.texi(,17)
+../tar_texi/snapshot.texi(,18) @samp{Format 0} snapshot file begins with a
line containing a
+../tar_texi/snapshot.texi(,19) decimal number that represents the UNIX
timestamp of the beginning of
+../tar_texi/snapshot.texi(,20) the last archivation. This line is followed by
directory metadata
+../tar_texi/snapshot.texi(,21) descriptions, one per line. Each description
has the following format:
+../tar_texi/snapshot.texi(,22)
+../tar_texi/snapshot.texi(,23) @smallexample
+../tar_texi/snapshot.texi(,24) address@hidden@var{dev} @var{inode} @var{name}
+../tar_texi/snapshot.texi(,25) @end smallexample
+../tar_texi/snapshot.texi(,26)
+../tar_texi/snapshot.texi(,27) @noindent
+../tar_texi/snapshot.texi(,28) where optional @var{nfs} is a single plus
character (@samp{+}) if this
+../tar_texi/snapshot.texi(,29) directory is located on an NFS-mounted
partition, @var{dev} and
+../tar_texi/snapshot.texi(,30) @var{inode} are the device and inode numbers of
the directory, and
+../tar_texi/snapshot.texi(,31) @var{name} is the directory name.
+../tar_texi/snapshot.texi(,32)
+../tar_texi/snapshot.texi(,33) @samp{Format 1} snapshot file begins with a
line specifying the
+../tar_texi/snapshot.texi(,34) format of the file. This line has the following
structure:
+../tar_texi/snapshot.texi(,35)
+../tar_texi/snapshot.texi(,36) @smallexample
+../tar_texi/snapshot.texi(,37) @samp{GNU address@hidden@address@hidden
+../tar_texi/snapshot.texi(,38) @end smallexample
+../tar_texi/snapshot.texi(,39)
+../tar_texi/snapshot.texi(,40) @noindent
+../tar_texi/snapshot.texi(GNUTAR,41) where @var{tar-version} is the version of
../tar_texi/snapshot.texi(GNUTAR,41) @acronym{GNU}
@command{tar}../tar_texi/snapshot.texi(GNUTAR,41) implementation
+../tar_texi/snapshot.texi(,42) that created this snapshot, and
@var{incr-format-version} is the
+../tar_texi/snapshot.texi(,43) version number of the snapshot format (in this
case @samp{1}).
+../tar_texi/snapshot.texi(,44)
+../tar_texi/snapshot.texi(,45) The following line contains two decimal
numbers, representing the
+../tar_texi/snapshot.texi(,46) time of the last backup. First number is the
number of seconds, the
+../tar_texi/snapshot.texi(,47) second one is the number of nanoseconds, since
the beginning of the
+../tar_texi/snapshot.texi(,48) epoch.
+../tar_texi/snapshot.texi(,49)
+../tar_texi/snapshot.texi(,50) Following lines contain directory metadate,
one line per
+../tar_texi/snapshot.texi(,51) directory. The line format is:
+../tar_texi/snapshot.texi(,52)
+../tar_texi/snapshot.texi(,53) @smallexample
+../tar_texi/snapshot.texi(,54) address@hidden@var{mtime-sec} @var{mtime-nsec}
@var{dev} @var{inode} @var{name}
+../tar_texi/snapshot.texi(,55) @end smallexample
+../tar_texi/snapshot.texi(,56)
+../tar_texi/snapshot.texi(,57) @noindent
+../tar_texi/snapshot.texi(,58) where @var{mtime-sec} and @var{mtime-nsec}
represent the last
+../tar_texi/snapshot.texi(,59) modification time of this directory with
nanosecond precision;
+../tar_texi/snapshot.texi(,60) @var{nfs}, @var{dev}, @var{inode} and
@var{name} have the same meaning
+../tar_texi/snapshot.texi(,61) as with @samp{format 0}.
+../tar_texi/snapshot.texi(,62)
+../tar_texi/snapshot.texi(,63)
+../tar_texi/snapshot.texi(,64) @c End of snapshot.texi
+../tar_texi/snapshot.texi(,65)
+../tar_texi/snapshot.texi(,66)
+../tar_texi/intern.texi(,331)
+../tar_texi/intern.texi(,332) @node Dumpdir
+../tar_texi/intern.texi(,333) @unnumberedsec Dumpdir
+../tar_texi/dumpdir.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/dumpdir.texi(,2) @c Copyright (C) 2006 Free Software Foundation,
Inc.
+../tar_texi/dumpdir.texi(,3) @c Written by Sergey Poznyakoff
+../tar_texi/dumpdir.texi(,4) @c This file is distributed under GFDL 1.1 or any
later version
+../tar_texi/dumpdir.texi(,5) @c published by the Free Software Foundation.
+../tar_texi/dumpdir.texi(,6)
+../tar_texi/dumpdir.texi(,7) Incremental archives keep information about
contents of each
+../tar_texi/dumpdir.texi(,8) dumped directory in special data blocks called
@dfn{dumpdirs}.
+../tar_texi/dumpdir.texi(,9)
+../tar_texi/dumpdir.texi(,10) Dumpdir is a sequence of entries of the
following form:
+../tar_texi/dumpdir.texi(,11)
+../tar_texi/dumpdir.texi(,12) @smallexample
+../tar_texi/dumpdir.texi(,13) @var{C} @var{filename} \0
+../tar_texi/dumpdir.texi(,14) @end smallexample
+../tar_texi/dumpdir.texi(,15)
+../tar_texi/dumpdir.texi(,16) @noindent
+../tar_texi/dumpdir.texi(,17) where @var{C} is one of the @dfn{control codes}
described below,
+../tar_texi/dumpdir.texi(,18) @var{filename} is the name of the file @var{C}
operates upon, and
+../tar_texi/dumpdir.texi(,19) @samp{\0} represents a nul character (ASCII 0).
The white space
+../tar_texi/dumpdir.texi(,20) characters were added for readability, real
dumpdirs do not contain
+../tar_texi/dumpdir.texi(,21) them.
+../tar_texi/dumpdir.texi(,22)
+../tar_texi/dumpdir.texi(,23) Each dumpdir ends with a single nul character.
+../tar_texi/dumpdir.texi(,24)
+../tar_texi/dumpdir.texi(,25) The following table describes control codes
and their meanings:
+../tar_texi/dumpdir.texi(,26)
+../tar_texi/dumpdir.texi(,27) @table @samp
+../tar_texi/dumpdir.texi(,28) @item Y
+../tar_texi/dumpdir.texi(,29) @var{filename} is contained in the archive.
+../tar_texi/dumpdir.texi(,30)
+../tar_texi/dumpdir.texi(,31) @item N
+../tar_texi/dumpdir.texi(,32) @var{filename} was present in the directory at
the time the archive
+../tar_texi/dumpdir.texi(,33) was made, yet it was not dumped to the archive,
because it had not
+../tar_texi/dumpdir.texi(,34) changed since the last backup.
+../tar_texi/dumpdir.texi(,35)
+../tar_texi/dumpdir.texi(,36) @item D
+../tar_texi/dumpdir.texi(,37) @var{filename} is a directory.
+../tar_texi/dumpdir.texi(,38)
+../tar_texi/dumpdir.texi(,39) @item R
+../tar_texi/dumpdir.texi(,40) This code requests renaming of the
@var{filename} to the name
+../tar_texi/dumpdir.texi(,41) specified with the following @samp{T} command.
+../tar_texi/dumpdir.texi(,42)
+../tar_texi/dumpdir.texi(,43) @item T
+../tar_texi/dumpdir.texi(,44) Specify target file name for @samp{R} command
(see below).
+../tar_texi/dumpdir.texi(,45)
+../tar_texi/dumpdir.texi(,46) @item X
+../tar_texi/dumpdir.texi(,47) Specify @dfn{temporary directory} name for a
rename operation (see below).
+../tar_texi/dumpdir.texi(,48) @end table
+../tar_texi/dumpdir.texi(,49)
+../tar_texi/dumpdir.texi(,50) Codes @samp{Y}, @samp{N} and @samp{D} require
@var{filename} argument
+../tar_texi/dumpdir.texi(,51) to be a relative file name to the directory this
dumpdir describes,
+../tar_texi/dumpdir.texi(,52) whereas codes @samp{R}, @samp{T} and @samp{X}
require their argument
+../tar_texi/dumpdir.texi(,53) to be an absolute file name.
+../tar_texi/dumpdir.texi(,54)
+../tar_texi/dumpdir.texi(,55) The three codes @samp{R}, @samp{T} and @samp{X}
specify a
+../tar_texi/dumpdir.texi(,56) @dfn{renaming operation}. In the simplest case
it is:
+../tar_texi/dumpdir.texi(,57)
+../tar_texi/dumpdir.texi(,58) @smallexample
+../tar_texi/dumpdir.texi(,59) address@hidden@file{dest}\0
+../tar_texi/dumpdir.texi(,60) @end smallexample
+../tar_texi/dumpdir.texi(,61)
+../tar_texi/dumpdir.texi(,62) @noindent
+../tar_texi/dumpdir.texi(,63) which means ``rename file @file{source} to file
@file{dest}''.
+../tar_texi/dumpdir.texi(,64)
+../tar_texi/dumpdir.texi(,65) However, there are cases that require using a
@dfn{temporary
+../tar_texi/dumpdir.texi(,66) directory}. For example, consider the following
scenario:
+../tar_texi/dumpdir.texi(,67)
+../tar_texi/dumpdir.texi(,68) @enumerate 1
+../tar_texi/dumpdir.texi(,69) @item
+../tar_texi/dumpdir.texi(,70) Previous run dumped a directory @file{foo} which
contained the
+../tar_texi/dumpdir.texi(,71) following three directories:
+../tar_texi/dumpdir.texi(,72)
+../tar_texi/dumpdir.texi(,73) @smallexample
+../tar_texi/dumpdir.texi(,74) a
+../tar_texi/dumpdir.texi(,75) b
+../tar_texi/dumpdir.texi(,76) c
+../tar_texi/dumpdir.texi(,77) @end smallexample
+../tar_texi/dumpdir.texi(,78)
+../tar_texi/dumpdir.texi(,79) @item
+../tar_texi/dumpdir.texi(,80) They were renamed @emph{cyclically}, so that:
+../tar_texi/dumpdir.texi(,81)
+../tar_texi/dumpdir.texi(,82) @example
+../tar_texi/dumpdir.texi(,83) @file{a} became @file{b}
+../tar_texi/dumpdir.texi(,84) @file{b} became @file{c}
+../tar_texi/dumpdir.texi(,85) @file{c} became @file{a}
+../tar_texi/dumpdir.texi(,86) @end example
+../tar_texi/dumpdir.texi(,87)
+../tar_texi/dumpdir.texi(,88) @item
+../tar_texi/dumpdir.texi(,89) New incremental dump was made.
+../tar_texi/dumpdir.texi(,90) @end enumerate
+../tar_texi/dumpdir.texi(,91)
+../tar_texi/dumpdir.texi(,92) This case cannot be handled by three
successive renames, since
+../tar_texi/dumpdir.texi(,93) renaming @file{a} to @file{b} will destroy
existing directory.
+../tar_texi/dumpdir.texi(GNUTAR,94) To handle such case a temporary directory
is required. ../tar_texi/dumpdir.texi(GNUTAR,94) @acronym{GNU}
@command{tar}../tar_texi/dumpdir.texi(GNUTAR,94)
+../tar_texi/dumpdir.texi(,95) will create the following dumpdir (newlines have
been added for
+../tar_texi/dumpdir.texi(,96) readability):
+../tar_texi/dumpdir.texi(,97)
+../tar_texi/dumpdir.texi(,98) @smallexample
+../tar_texi/dumpdir.texi(,99) @group
+../tar_texi/dumpdir.texi(,100) Xfoo\0
+../tar_texi/dumpdir.texi(,101) Rfoo/a\0T\0
+../tar_texi/dumpdir.texi(,102) Rfoo/b\0Tfoo/c\0
+../tar_texi/dumpdir.texi(,103) Rfoo/c\0Tfoo/a\0
+../tar_texi/dumpdir.texi(,104) R\0Tfoo/a\0
+../tar_texi/dumpdir.texi(,105) @end group
+../tar_texi/dumpdir.texi(,106) @end smallexample
+../tar_texi/dumpdir.texi(,107)
+../tar_texi/dumpdir.texi(,108) The first command, @samp{Xfoo\0}, instructs
the extractor to create a
+../tar_texi/dumpdir.texi(,109) temporary directory in the directory
@file{foo}. Second command,
+../tar_texi/dumpdir.texi(,110) @samp{Rfoo/aT\0}, says ``rename file
@file{foo/a} to the temporary
+../tar_texi/dumpdir.texi(,111) directory that has just been created'' (empty
file name after a
+../tar_texi/dumpdir.texi(,112) command means use temporary directory). Third
and fourth commands
+../tar_texi/dumpdir.texi(,113) work as usual, and, finally, the last command,
@samp{R\0Tfoo/a\0}
+../tar_texi/dumpdir.texi(,114) tells tar to rename the temporary directory to
@file{foo/a}.
+../tar_texi/dumpdir.texi(,115)
+../tar_texi/dumpdir.texi(,116) The exact placement of a dumpdir in the
archive depends on the
+../tar_texi/dumpdir.texi(,117) archive format (@pxref{Formats}):
+../tar_texi/dumpdir.texi(,118)
+../tar_texi/dumpdir.texi(,119) @itemize
+../tar_texi/dumpdir.texi(,120) @item PAX archives
+../tar_texi/dumpdir.texi(,121)
+../tar_texi/dumpdir.texi(,122) In PAX archives, dumpdir is stored in the
extended header of the
+../tar_texi/dumpdir.texi(,123) corresponding directory, in variable
@code{GNU.dumpdir}.
+../tar_texi/dumpdir.texi(,124)
+../tar_texi/dumpdir.texi(,125) @item GNU and old GNU archives
+../tar_texi/dumpdir.texi(,126)
+../tar_texi/dumpdir.texi(,127) These formats implement special header type
@samp{D}, which is similar
+../tar_texi/dumpdir.texi(,128) to ustar header @samp{5} (directory), except
that it preceeds a data
+../tar_texi/dumpdir.texi(,129) block containing the dumpdir.
+../tar_texi/dumpdir.texi(,130) @end itemize
+../tar_texi/dumpdir.texi(,131)
+../tar_texi/dumpdir.texi(,132) @c End of dumpdir.texi
+../tar_texi/intern.texi(,335)
+../tar_texi/tar.texi(,10777)
+../tar_texi/tar.texi(,10778) @node Genfile
+../tar_texi/tar.texi(,10779) @appendix Genfile
+../tar_texi/genfile.texi(,1) @c This is part of the paxutils manual.
+../tar_texi/genfile.texi(,2) @c Copyright (C) 2005, 2006 Free Software
Foundation, Inc.
+../tar_texi/genfile.texi(,3) @c Written by Sergey Poznyakoff
+../tar_texi/genfile.texi(,4) @c This file is distributed under GFDL 1.1 or any
later version
+../tar_texi/genfile.texi(,5) @c published by the Free Software Foundation.
+../tar_texi/genfile.texi(,6)
+../tar_texi/genfile.texi(,7) @cindex genfile
+../tar_texi/genfile.texi(,8) This appendix describes @command{genfile}, an
auxiliary program
+../tar_texi/genfile.texi(,9) used in the GNU tar testsuite. If you are not
interested in developing
+../tar_texi/genfile.texi(,10) GNU tar, skip this appendix.
+../tar_texi/genfile.texi(,11)
+../tar_texi/genfile.texi(,12) Initially, @command{genfile} was used to
generate data files for
+../tar_texi/genfile.texi(,13) the testsuite, hence its name. However, new
operation modes were being
+../tar_texi/genfile.texi(,14) implemented as the testsuite grew more
sophisticated, and now
+../tar_texi/genfile.texi(,15) @command{genfile} is a multi-purpose instrument.
+../tar_texi/genfile.texi(,16)
+../tar_texi/genfile.texi(,17) There are three basic operation modes:
+../tar_texi/genfile.texi(,18)
+../tar_texi/genfile.texi(,19) @table @asis
+../tar_texi/genfile.texi(,20) @item File Generation
+../tar_texi/genfile.texi(,21) This is the default mode. In this mode,
@command{genfile}
+../tar_texi/genfile.texi(,22) generates data files.
+../tar_texi/genfile.texi(,23)
+../tar_texi/genfile.texi(,24) @item File Status
+../tar_texi/genfile.texi(,25) In this mode @command{genfile} displays
status of specified files.
+../tar_texi/genfile.texi(,26)
+../tar_texi/genfile.texi(,27) @item Synchronous Execution.
+../tar_texi/genfile.texi(,28) In this mode @command{genfile} executes the
given program with
+../tar_texi/genfile.texi(,29) @option{--checkpoint} option and executes a set
of actions when
+../tar_texi/genfile.texi(,30) specified checkpoints are reached.
+../tar_texi/genfile.texi(,31) @end table
+../tar_texi/genfile.texi(,32)
+../tar_texi/genfile.texi(,33) @menu
+../tar_texi/genfile.texi(,34) * Generate Mode:: File Generation Mode.
+../tar_texi/genfile.texi(,35) * Status Mode:: File Status Mode.
+../tar_texi/genfile.texi(,36) * Exec Mode:: Synchronous Execution mode.
+../tar_texi/genfile.texi(,37) @end menu
+../tar_texi/genfile.texi(,38)
+../tar_texi/genfile.texi(,39) @node Generate Mode
+../tar_texi/genfile.texi(,40) @appendixsec Generate Mode
+../tar_texi/genfile.texi(,41)
+../tar_texi/genfile.texi(,42) @cindex Generate Mode, @command{genfile}
+../tar_texi/genfile.texi(,43) @cindex @command{genfile}, generate mode
+../tar_texi/genfile.texi(,44) @cindex @command{genfile}, create file
+../tar_texi/genfile.texi(,45) In this mode @command{genfile} creates a
data file for the test
+../tar_texi/genfile.texi(,46) suite. The size of the file is given with the
@option{--length}
+../tar_texi/genfile.texi(,47) (@option{-l}) option. By default the file
contents is written to the
+../tar_texi/genfile.texi(,48) standard output, this can be changed using
@option{--file}
+../tar_texi/genfile.texi(,49) (@option{-f}) command line option. Thus, the
following two commands
+../tar_texi/genfile.texi(,50) are equivalent:
+../tar_texi/genfile.texi(,51)
+../tar_texi/genfile.texi(,52) @smallexample
+../tar_texi/genfile.texi(,53) @group
+../tar_texi/genfile.texi(,54) genfile --length 100 > outfile
+../tar_texi/genfile.texi(,55) genfile --length 100 --file outfile
+../tar_texi/genfile.texi(,56) @end group
+../tar_texi/genfile.texi(,57) @end smallexample
+../tar_texi/genfile.texi(,58)
+../tar_texi/genfile.texi(,59) If @option{--length} is not given,
@command{genfile} will
+../tar_texi/genfile.texi(,60) generate an empty (zero-length) file.
+../tar_texi/genfile.texi(,61)
+../tar_texi/genfile.texi(,62) @cindex @command{genfile}, reading a list of
file names
+../tar_texi/genfile.texi(,63) You can instruct @command{genfile} to create
several files at one
+../tar_texi/genfile.texi(,64) go, by giving it @option{--files-from}
(@option{-T}) option followed
+../tar_texi/genfile.texi(,65) by a name of file containing a list of file
names. Using dash
+../tar_texi/genfile.texi(,66) (@samp{-}) instead of the file name causes
@command{genfile} to read
+../tar_texi/genfile.texi(,67) file list from the standard input. For example:
+../tar_texi/genfile.texi(,68)
+../tar_texi/genfile.texi(,69) @smallexample
+../tar_texi/genfile.texi(,70) @group
+../tar_texi/genfile.texi(,71) # Read file names from file @file{file.list}
+../tar_texi/genfile.texi(,72) genfile --files-from file.list
+../tar_texi/genfile.texi(,73) # Read file names from standard input
+../tar_texi/genfile.texi(,74) genfile --files-from -
+../tar_texi/genfile.texi(,75) @end group
+../tar_texi/genfile.texi(,76) @end smallexample
+../tar_texi/genfile.texi(,77)
+../tar_texi/genfile.texi(,78) @cindex File lists separated by NUL characters
+../tar_texi/genfile.texi(,79) The list file is supposed to contain one
file name per line. To
+../tar_texi/genfile.texi(,80) use file lists separated by ASCII NUL character,
use @option{--null}
+../tar_texi/genfile.texi(,81) (@option{-0}) command line option:
+../tar_texi/genfile.texi(,82)
+../tar_texi/genfile.texi(,83) @smallexample
+../tar_texi/genfile.texi(,84) genfile --null --files-from file.list
+../tar_texi/genfile.texi(,85) @end smallexample
+../tar_texi/genfile.texi(,86)
+../tar_texi/genfile.texi(,87) @cindex pattern, @command{genfile}
+../tar_texi/genfile.texi(,88) The default data pattern for filling the
generated file consists
+../tar_texi/genfile.texi(,89) of first 256 letters of ASCII code, repeated
enough times to fill the
+../tar_texi/genfile.texi(,90) entire file. This behavior can be changed with
@option{--pattern}
+../tar_texi/genfile.texi(,91) option. This option takes a mandatory argument,
specifying pattern
+../tar_texi/genfile.texi(,92) name to use. Currently two patterns are
implemented:
+../tar_texi/genfile.texi(,93)
+../tar_texi/genfile.texi(,94) @table @option
+../tar_texi/genfile.texi(,95) @item --pattern=default
+../tar_texi/genfile.texi(,96) The default pattern as described above.
+../tar_texi/genfile.texi(,97)
+../tar_texi/genfile.texi(,98) @item --pattern=zero
+../tar_texi/genfile.texi(,99) Fills the file with zeroes.
+../tar_texi/genfile.texi(,100) @end table
+../tar_texi/genfile.texi(,101)
+../tar_texi/genfile.texi(,102) If no file name was given, the program
exits with the code
+../tar_texi/genfile.texi(,103) @code{0}. Otherwise, it exits with @code{0}
only if it was able to
+../tar_texi/genfile.texi(,104) create a file of the specified length.
+../tar_texi/genfile.texi(,105)
+../tar_texi/genfile.texi(,106) @cindex Sparse files, creating using
@command{genfile}
+../tar_texi/genfile.texi(,107) @cindex @command{genfile}, creating sparse files
+../tar_texi/genfile.texi(,108) Special option @option{--sparse}
(@option{-s}) instructs
+../tar_texi/genfile.texi(,109) @command{genfile} to create a sparse file.
Sparse files consist of
+../tar_texi/genfile.texi(,110) @dfn{data fragments}, separated by @dfn{holes}
or blocks of zeros. On
+../tar_texi/genfile.texi(,111) many operating systems, actual disk storage is
not allocated for
+../tar_texi/genfile.texi(,112) holes, but they are counted in the length of
the file. To create a
+../tar_texi/genfile.texi(,113) sparse file, @command{genfile} should know
where to put data fragments,
+../tar_texi/genfile.texi(,114) and what data to use to fill them. So, when
@option{--sparse} is given
+../tar_texi/genfile.texi(,115) the rest of the command line specifies a
so-called @dfn{file map}.
+../tar_texi/genfile.texi(,116)
+../tar_texi/genfile.texi(,117) The file map consists of any number of
@dfn{fragment
+../tar_texi/genfile.texi(,118) descriptors}. Each descriptor is composed of
two values: a number,
+../tar_texi/genfile.texi(,119) specifying fragment offset from the end of the
previous fragment or,
+../tar_texi/genfile.texi(,120) for the very first fragment, from the beginning
of the file, and
+../tar_texi/genfile.texi(,121) @dfn{contents string}, i.e. a string of
characters, specifying the
+../tar_texi/genfile.texi(,122) pattern to fill the fragment with. File offset
can be suffixed with
+../tar_texi/genfile.texi(,123) the following quantifiers:
+../tar_texi/genfile.texi(,124)
+../tar_texi/genfile.texi(,125) @table @samp
+../tar_texi/genfile.texi(,126) @item k
+../tar_texi/genfile.texi(,127) @itemx K
+../tar_texi/genfile.texi(,128) The number is expressed in kilobytes.
+../tar_texi/genfile.texi(,129) @item m
+../tar_texi/genfile.texi(,130) @itemx M
+../tar_texi/genfile.texi(,131) The number is expressed in megabytes.
+../tar_texi/genfile.texi(,132) @item g
+../tar_texi/genfile.texi(,133) @itemx G
+../tar_texi/genfile.texi(,134) The number is expressed in gigabytes.
+../tar_texi/genfile.texi(,135) @end table
+../tar_texi/genfile.texi(,136)
+../tar_texi/genfile.texi(,137) For each letter in contents string
@command{genfile} will generate
+../tar_texi/genfile.texi(,138) a @dfn{block} of data, filled with this letter
and will write it to
+../tar_texi/genfile.texi(,139) the fragment. The size of block is given by
@option{--block-size}
+../tar_texi/genfile.texi(,140) option. It defaults to 512. Thus, if the string
consists of @var{n}
+../tar_texi/genfile.texi(,141) characters, the resulting file fragment will
contain
+../tar_texi/genfile.texi(,142) @address@hidden@var{block-size}} of data.
+../tar_texi/genfile.texi(,143)
+../tar_texi/genfile.texi(,144) Last fragment descriptor can have only file
offset part. In this
+../tar_texi/genfile.texi(,145) case @command{genfile} will create a hole at
the end of the file up to
+../tar_texi/genfile.texi(,146) the given offset.
+../tar_texi/genfile.texi(,147)
+../tar_texi/genfile.texi(,148) For example, consider the following
invocation:
+../tar_texi/genfile.texi(,149)
+../tar_texi/genfile.texi(,150) @smallexample
+../tar_texi/genfile.texi(,151) genfile --sparse --file sparsefile 0 ABCD 1M
EFGHI 2000K
+../tar_texi/genfile.texi(,152) @end smallexample
+../tar_texi/genfile.texi(,153)
+../tar_texi/genfile.texi(,154) @noindent
+../tar_texi/genfile.texi(,155) It will create 3101184-bytes long file of the
following structure:
+../tar_texi/genfile.texi(,156)
+../tar_texi/genfile.texi(,157) @multitable @columnfractions .35 .20 .45
+../tar_texi/genfile.texi(,158) @item Offset @tab Length @tab Contents
+../tar_texi/genfile.texi(,159) @item 0 @tab 4*512=2048 @tab Four
512-byte blocks, filled with
+../tar_texi/genfile.texi(,160) letters @samp{A}, @samp{B}, @samp{C} and
@samp{D}.
+../tar_texi/genfile.texi(,161) @item 2048 @tab 1046528 @tab Zero bytes
+../tar_texi/genfile.texi(,162) @item 1050624 @tab 5*512=2560 @tab Five
blocks, filled with letters
+../tar_texi/genfile.texi(,163) @samp{E}, @samp{F}, @samp{G}, @samp{H},
@samp{I}.
+../tar_texi/genfile.texi(,164) @item 1053184 @tab 2048000 @tab Zero bytes
+../tar_texi/genfile.texi(,165) @end multitable
+../tar_texi/genfile.texi(,166)
+../tar_texi/genfile.texi(,167) The exit code of @command{genfile --status}
command is @code{0}
+../tar_texi/genfile.texi(,168) only if created file is actually sparse.
+../tar_texi/genfile.texi(,169)
+../tar_texi/genfile.texi(,170) @node Status Mode
+../tar_texi/genfile.texi(,171) @appendixsec Status Mode
+../tar_texi/genfile.texi(,172)
+../tar_texi/genfile.texi(,173) In status mode, @command{genfile} prints
file system status for
+../tar_texi/genfile.texi(,174) each file specified in the command line. This
mode is toggled by
+../tar_texi/genfile.texi(,175) @option{--stat} (@option{-S}) command line
option. An optional argument to this
+../tar_texi/genfile.texi(,176) option specifies output @dfn{format}: a
comma-separated list of
+../tar_texi/genfile.texi(,177) @code{struct stat} fields to be displayed. This
list can contain
+../tar_texi/genfile.texi(FIXME,179) following identifiers
../tar_texi/genfile.texi(FIXME,179) @allow-recursion
+../tar_texi/genfile.texi(FIXME,179) @quote-arg
+../tar_texi/genfile.texi(FIXME,179) :
+../tar_texi/genfile.texi(,180)
+../tar_texi/genfile.texi(,181) @table @asis
+../tar_texi/genfile.texi(,182) @item name
+../tar_texi/genfile.texi(,183) The file name.
+../tar_texi/genfile.texi(,184)
+../tar_texi/genfile.texi(,185) @item dev
+../tar_texi/genfile.texi(,186) @itemx st_dev
+../tar_texi/genfile.texi(,187) Device number in decimal.
+../tar_texi/genfile.texi(,188)
+../tar_texi/genfile.texi(,189) @item ino
+../tar_texi/genfile.texi(,190) @itemx st_ino
+../tar_texi/genfile.texi(,191) Inode number.
+../tar_texi/genfile.texi(,192)
+../tar_texi/genfile.texi(,193) @item address@hidden
+../tar_texi/genfile.texi(,194) @itemx address@hidden
+../tar_texi/genfile.texi(,195) File mode in octal. Optional @var{number}
specifies octal mask to
+../tar_texi/genfile.texi(,196) be applied to the mode before outputting. For
example, @code{--stat
+../tar_texi/genfile.texi(,197) mode.777} will preserve lower nine bits of it.
Notice, that you can
+../tar_texi/genfile.texi(,198) use any punctuation caracter in place of
@samp{.}.
+../tar_texi/genfile.texi(,199)
+../tar_texi/genfile.texi(,200) @item nlink
+../tar_texi/genfile.texi(,201) @itemx st_nlink
+../tar_texi/genfile.texi(,202) Number of hard links.
+../tar_texi/genfile.texi(,203)
+../tar_texi/genfile.texi(,204) @item uid
+../tar_texi/genfile.texi(,205) @itemx st_uid
+../tar_texi/genfile.texi(,206) User ID of owner.
+../tar_texi/genfile.texi(,207)
+../tar_texi/genfile.texi(,208) @item gid
+../tar_texi/genfile.texi(,209) @itemx st_gid
+../tar_texi/genfile.texi(,210) Group ID of owner.
+../tar_texi/genfile.texi(,211)
+../tar_texi/genfile.texi(,212) @item size
+../tar_texi/genfile.texi(,213) @itemx st_size
+../tar_texi/genfile.texi(,214) File size in decimal.
+../tar_texi/genfile.texi(,215)
+../tar_texi/genfile.texi(,216) @item blksize
+../tar_texi/genfile.texi(,217) @itemx st_blksize
+../tar_texi/genfile.texi(,218) The size in bytes of each file block.
+../tar_texi/genfile.texi(,219)
+../tar_texi/genfile.texi(,220) @item blocks
+../tar_texi/genfile.texi(,221) @itemx st_blocks
+../tar_texi/genfile.texi(,222) Number of blocks allocated.
+../tar_texi/genfile.texi(,223)
+../tar_texi/genfile.texi(,224) @item atime
+../tar_texi/genfile.texi(,225) @itemx st_atime
+../tar_texi/genfile.texi(,226) Time of last access.
+../tar_texi/genfile.texi(,227)
+../tar_texi/genfile.texi(,228) @item mtime
+../tar_texi/genfile.texi(,229) @itemx st_mtime
+../tar_texi/genfile.texi(,230) Time of last modification
+../tar_texi/genfile.texi(,231)
+../tar_texi/genfile.texi(,232) @item ctime
+../tar_texi/genfile.texi(,233) @itemx st_ctime
+../tar_texi/genfile.texi(,234) Time of last status change
+../tar_texi/genfile.texi(,235)
+../tar_texi/genfile.texi(,236) @item sparse
+../tar_texi/genfile.texi(,237) A boolean value indicating whether the file
is @samp{sparse}.
+../tar_texi/genfile.texi(,238) @end table
+../tar_texi/genfile.texi(,239)
+../tar_texi/genfile.texi(,240) Modification times are displayed in
@acronym{UTC} as
+../tar_texi/genfile.texi(,241) @acronym{UNIX} timestamps, unless suffixed with
@samp{H} (for
+../tar_texi/genfile.texi(,242) ``human-readable''), as in @samp{ctimeH}, in
which case usual
+../tar_texi/genfile.texi(,243) @code{tar tv} output format is used.
+../tar_texi/genfile.texi(,244)
+../tar_texi/genfile.texi(,245) The default output format is:
@samp{name,dev,ino,mode,
+../tar_texi/genfile.texi(,246)
nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}.
+../tar_texi/genfile.texi(,247)
+../tar_texi/genfile.texi(,248) For example, the following command will
display file names and
+../tar_texi/genfile.texi(,249) corresponding times of last access for each
file in the current working
+../tar_texi/genfile.texi(,250) directory:
+../tar_texi/genfile.texi(,251)
+../tar_texi/genfile.texi(,252) @smallexample
+../tar_texi/genfile.texi(,253) genfile --stat=name,atime *
+../tar_texi/genfile.texi(,254) @end smallexample
+../tar_texi/genfile.texi(,255)
+../tar_texi/genfile.texi(,256) @node Exec Mode
+../tar_texi/genfile.texi(,257) @appendixsec Exec Mode
+../tar_texi/genfile.texi(,258)
+../tar_texi/genfile.texi(,259) @cindex Exec Mode, @command{genfile}
+../tar_texi/genfile.texi(,260) This mode is designed for testing the
behavior of @code{paxutils}
+../tar_texi/genfile.texi(,261) commands when some of the files change during
archiving. It is an
+../tar_texi/genfile.texi(,262) experimental mode.
+../tar_texi/genfile.texi(,263)
+../tar_texi/genfile.texi(,264) The @samp{Exec Mode} is toggled by
@option{--run} command line
+../tar_texi/genfile.texi(,265) option (or its alias @option{-r}). The argument
to this option gives
+../tar_texi/genfile.texi(,266) the command line to be executed. The actual
command line is
+../tar_texi/genfile.texi(,267) constructed by inserting @option{--checkpoint}
option between the
+../tar_texi/genfile.texi(,268) command name and its first argument (if any).
Due to this, the
+../tar_texi/genfile.texi(,269) argument to @option{--run} may not use
traditional @command{tar}
+../tar_texi/genfile.texi(,270) option syntax, i.e. the following is wrong:
+../tar_texi/genfile.texi(,271)
+../tar_texi/genfile.texi(,272) @smallexample
+../tar_texi/genfile.texi(,273) # Wrong!
+../tar_texi/genfile.texi(,274) genfile --run 'tar cf foo bar'
+../tar_texi/genfile.texi(,275) @end smallexample
+../tar_texi/genfile.texi(,276)
+../tar_texi/genfile.texi(,277) @noindent
+../tar_texi/genfile.texi(,278)
+../tar_texi/genfile.texi(,279) Use the following syntax instead:
+../tar_texi/genfile.texi(,280)
+../tar_texi/genfile.texi(,281) @smallexample
+../tar_texi/genfile.texi(,282) genfile --run 'tar -cf foo bar'
+../tar_texi/genfile.texi(,283) @end smallexample
+../tar_texi/genfile.texi(,284)
+../tar_texi/genfile.texi(,285) The rest of command line after
@option{--run} or its equivalent
+../tar_texi/genfile.texi(,286) specifies checkpoint values and actions to be
executed upon reaching
+../tar_texi/genfile.texi(,287) them. Checkpoint values are introduced with
@option{--checkpoint}
+../tar_texi/genfile.texi(,288) command line option. Argument to this option is
the number of
+../tar_texi/genfile.texi(,289) checkpoint in decimal.
+../tar_texi/genfile.texi(,290)
+../tar_texi/genfile.texi(,291) Any number of @dfn{actions} may be
specified after a
+../tar_texi/genfile.texi(,292) checkpoint. Available actions are
+../tar_texi/genfile.texi(,293)
+../tar_texi/genfile.texi(,294) @table @option
+../tar_texi/genfile.texi(,295) @item --cut @var{file}
+../tar_texi/genfile.texi(,296) @itemx --truncate @var{file}
+../tar_texi/genfile.texi(,297) Truncate @var{file} to the size specified
by previous
+../tar_texi/genfile.texi(,298) @option{--length} option (or 0, if it is not
given).
+../tar_texi/genfile.texi(,299)
+../tar_texi/genfile.texi(,300) @item --append @var{file}
+../tar_texi/genfile.texi(,301) Append data to @var{file}. The size of data
and its pattern are
+../tar_texi/genfile.texi(,302) given by previous @option{--length} and
@option{pattern} options.
+../tar_texi/genfile.texi(,303)
+../tar_texi/genfile.texi(,304) @item --touch @var{file}
+../tar_texi/genfile.texi(,305) Update the access and modification times of
@var{file}. These
+../tar_texi/genfile.texi(,306) timestamps are changed to the current time,
unless @option{--date}
+../tar_texi/genfile.texi(,307) option was given, in which case they are
changed to the specified
+../tar_texi/genfile.texi(,308) time. Argument to @option{--date} option is a
date specification in
+../tar_texi/genfile.texi(,309) an almost arbitrary format (@pxref{Date input
formats}).
+../tar_texi/genfile.texi(,310)
+../tar_texi/genfile.texi(,311) @item --exec @var{command}
+../tar_texi/genfile.texi(,312) Execute given shell command.
+../tar_texi/genfile.texi(,313)
+../tar_texi/genfile.texi(,314) @end table
+../tar_texi/genfile.texi(,315)
+../tar_texi/genfile.texi(,316) Option @option{--verbose} instructs
@command{genfile} to print on
+../tar_texi/genfile.texi(,317) standard output notifications about checkpoints
being executed and to
+../tar_texi/genfile.texi(,318) verbosely describe exit status of the command.
+../tar_texi/genfile.texi(,319)
+../tar_texi/genfile.texi(,320) While the command is being executed its
standard output remains
+../tar_texi/genfile.texi(,321) connected to descriptor 1. All messages it
prints to file descriptor
+../tar_texi/genfile.texi(,322) 2, except checkpoint notifications, are
forwarded to standard
+../tar_texi/genfile.texi(,323) error.
+../tar_texi/genfile.texi(,324)
+../tar_texi/genfile.texi(,325) @command{Genfile} exits with the exit
status of the executed command.
+../tar_texi/tar.texi(,10781)
+../tar_texi/tar.texi(,10782) @node Free Software Needs Free Documentation
+../tar_texi/tar.texi(,10783) @appendix Free Software Needs Free Documentation
+../tar_texi/freemanuals.texi(,1) @cindex free documentation
+../tar_texi/freemanuals.texi(,2)
+../tar_texi/freemanuals.texi(,3) The biggest deficiency in the free software
community today is not in
+../tar_texi/freemanuals.texi(,4) the software---it is the lack of good free
documentation that we can
+../tar_texi/freemanuals.texi(,5) include with the free software. Many of our
most important
+../tar_texi/freemanuals.texi(,6) programs do not come with free reference
manuals and free introductory
+../tar_texi/freemanuals.texi(,7) texts. Documentation is an essential part of
any software package;
+../tar_texi/freemanuals.texi(,8) when an important free software package does
not come with a free
+../tar_texi/freemanuals.texi(,9) manual and a free tutorial, that is a major
gap. We have many such
+../tar_texi/freemanuals.texi(,10) gaps today.
+../tar_texi/freemanuals.texi(,11)
+../tar_texi/freemanuals.texi(,12) Consider Perl, for instance. The tutorial
manuals that people
+../tar_texi/freemanuals.texi(,13) normally use are non-free. How did this
come about? Because the
+../tar_texi/freemanuals.texi(,14) authors of those manuals published them with
restrictive terms---no
+../tar_texi/freemanuals.texi(,15) copying, no modification, source files not
available---which exclude
+../tar_texi/freemanuals.texi(,16) them from the free software world.
+../tar_texi/freemanuals.texi(,17)
+../tar_texi/freemanuals.texi(,18) That wasn't the first time this sort of
thing happened, and it was far
+../tar_texi/freemanuals.texi(,19) from the last. Many times we have heard a
GNU user eagerly describe a
+../tar_texi/freemanuals.texi(,20) manual that he is writing, his intended
contribution to the community,
+../tar_texi/freemanuals.texi(,21) only to learn that he had ruined everything
by signing a publication
+../tar_texi/freemanuals.texi(,22) contract to make it non-free.
+../tar_texi/freemanuals.texi(,23)
+../tar_texi/freemanuals.texi(,24) Free documentation, like free software, is a
matter of freedom, not
+../tar_texi/freemanuals.texi(,25) price. The problem with the non-free manual
is not that publishers
+../tar_texi/freemanuals.texi(,26) charge a price for printed copies---that in
itself is fine. (The Free
+../tar_texi/freemanuals.texi(,27) Software Foundation sells printed copies of
manuals, too.) The
+../tar_texi/freemanuals.texi(,28) problem is the restrictions on the use of
the manual. Free manuals
+../tar_texi/freemanuals.texi(,29) are available in source code form, and give
you permission to copy and
+../tar_texi/freemanuals.texi(,30) modify. Non-free manuals do not allow this.
+../tar_texi/freemanuals.texi(,31)
+../tar_texi/freemanuals.texi(,32) The criteria of freedom for a free manual
are roughly the same as for
+../tar_texi/freemanuals.texi(,33) free software. Redistribution (including
the normal kinds of
+../tar_texi/freemanuals.texi(,34) commercial redistribution) must be
permitted, so that the manual can
+../tar_texi/freemanuals.texi(,35) accompany every copy of the program, both
on-line and on paper.
+../tar_texi/freemanuals.texi(,36)
+../tar_texi/freemanuals.texi(,37) Permission for modification of the technical
content is crucial too.
+../tar_texi/freemanuals.texi(,38) When people modify the software, adding or
changing features, if they
+../tar_texi/freemanuals.texi(,39) are conscientious they will change the
manual too---so they can
+../tar_texi/freemanuals.texi(,40) provide accurate and clear documentation for
the modified program. A
+../tar_texi/freemanuals.texi(,41) manual that leaves you no choice but to
write a new manual to document
+../tar_texi/freemanuals.texi(,42) a changed version of the program is not
really available to our
+../tar_texi/freemanuals.texi(,43) community.
+../tar_texi/freemanuals.texi(,44)
+../tar_texi/freemanuals.texi(,45) Some kinds of limits on the way modification
is handled are
+../tar_texi/freemanuals.texi(,46) acceptable. For example, requirements to
preserve the original
+../tar_texi/freemanuals.texi(,47) author's copyright notice, the distribution
terms, or the list of
+../tar_texi/freemanuals.texi(,48) authors, are ok. It is also no problem to
require modified versions
+../tar_texi/freemanuals.texi(,49) to include notice that they were modified.
Even entire sections that
+../tar_texi/freemanuals.texi(,50) may not be deleted or changed are
acceptable, as long as they deal
+../tar_texi/freemanuals.texi(,51) with nontechnical topics (like this one).
These kinds of restrictions
+../tar_texi/freemanuals.texi(,52) are acceptable because they don't obstruct
the community's normal use
+../tar_texi/freemanuals.texi(,53) of the manual.
+../tar_texi/freemanuals.texi(,54)
+../tar_texi/freemanuals.texi(,55) However, it must be possible to modify all
the @emph{technical}
+../tar_texi/freemanuals.texi(,56) content of the manual, and then distribute
the result in all the usual
+../tar_texi/freemanuals.texi(,57) media, through all the usual channels.
Otherwise, the restrictions
+../tar_texi/freemanuals.texi(,58) obstruct the use of the manual, it is not
free, and we need another
+../tar_texi/freemanuals.texi(,59) manual to replace it.
+../tar_texi/freemanuals.texi(,60)
+../tar_texi/freemanuals.texi(,61) Please spread the word about this issue.
Our community continues to
+../tar_texi/freemanuals.texi(,62) lose manuals to proprietary publishing. If
we spread the word that
+../tar_texi/freemanuals.texi(,63) free software needs free reference manuals
and free tutorials, perhaps
+../tar_texi/freemanuals.texi(,64) the next person who wants to contribute by
writing documentation will
+../tar_texi/freemanuals.texi(,65) realize, before it is too late, that only
free manuals contribute to
+../tar_texi/freemanuals.texi(,66) the free software community.
+../tar_texi/freemanuals.texi(,67)
+../tar_texi/freemanuals.texi(,68) If you are writing documentation, please
insist on publishing it under
+../tar_texi/freemanuals.texi(,69) the GNU Free Documentation License or
another free documentation
+../tar_texi/freemanuals.texi(,70) license. Remember that this decision
requires your approval---you
+../tar_texi/freemanuals.texi(,71) don't have to let the publisher decide.
Some commercial publishers
+../tar_texi/freemanuals.texi(,72) will use a free license if you insist, but
they will not propose the
+../tar_texi/freemanuals.texi(,73) option; it is up to you to raise the issue
and say firmly that this is
+../tar_texi/freemanuals.texi(,74) what you want. If the publisher you are
dealing with refuses, please
+../tar_texi/freemanuals.texi(,75) try other publishers. If you're not sure
whether a proposed license
+../tar_texi/freemanuals.texi(,76) is free, write to @email{licensing@@gnu.org}.
+../tar_texi/freemanuals.texi(,77)
+../tar_texi/freemanuals.texi(,78) You can encourage commercial publishers to
sell more free, copylefted
+../tar_texi/freemanuals.texi(,79) manuals and tutorials by buying them, and
particularly by buying
+../tar_texi/freemanuals.texi(,80) copies from the publishers that paid for
their writing or for major
+../tar_texi/freemanuals.texi(,81) improvements. Meanwhile, try to avoid
buying non-free documentation
+../tar_texi/freemanuals.texi(,82) at all. Check the distribution terms of a
manual before you buy it,
+../tar_texi/freemanuals.texi(,83) and insist that whoever seeks your business
must respect your freedom.
+../tar_texi/freemanuals.texi(,84) Check the history of the book, and try
reward the publishers that have
+../tar_texi/freemanuals.texi(,85) paid or pay the authors to work on it.
+../tar_texi/freemanuals.texi(,86)
+../tar_texi/freemanuals.texi(,87) The Free Software Foundation maintains a
list of free documentation
+../tar_texi/freemanuals.texi(,88) published by other publishers, at
+../tar_texi/freemanuals.texi(,89)
@url{http://www.fsf.org/doc/other-free-books.html}.
+../tar_texi/tar.texi(,10785)
+../tar_texi/tar.texi(,10786) @node Copying This Manual
+../tar_texi/tar.texi(,10787) @appendix Copying This Manual
+../tar_texi/tar.texi(,10788)
+../tar_texi/tar.texi(,10789) @menu
+../tar_texi/tar.texi(,10790) * GNU Free Documentation License:: License for
copying this manual
+../tar_texi/tar.texi(,10791) @end menu
+../tar_texi/tar.texi(,10792)
+../tar_texi/fdl.texi(,1)
+../tar_texi/fdl.texi(,2) @node GNU Free Documentation License
+../tar_texi/fdl.texi(,3) @appendixsec GNU Free Documentation License
+../tar_texi/fdl.texi(,4)
+../tar_texi/fdl.texi(,5) @cindex FDL, GNU Free Documentation License
+../tar_texi/fdl.texi(,6) @center Version 1.2, November 2002
+../tar_texi/fdl.texi(,7)
+../tar_texi/fdl.texi(,8) @display
+../tar_texi/fdl.texi(,9) Copyright @copyright{} 2000,2001,2002 Free Software
Foundation, Inc.
+../tar_texi/fdl.texi(,10) 51 Franklin St, Fifth Floor, Boston, MA 02110-1301,
USA
+../tar_texi/fdl.texi(,11)
+../tar_texi/fdl.texi(,12) Everyone is permitted to copy and distribute
verbatim copies
+../tar_texi/fdl.texi(,13) of this license document, but changing it is not
allowed.
+../tar_texi/fdl.texi(,14) @end display
+../tar_texi/fdl.texi(,15)
+../tar_texi/fdl.texi(,16) @enumerate 0
+../tar_texi/fdl.texi(,17) @item
+../tar_texi/fdl.texi(,18) PREAMBLE
+../tar_texi/fdl.texi(,19)
+../tar_texi/fdl.texi(,20) The purpose of this License is to make a manual,
textbook, or other
+../tar_texi/fdl.texi(,21) functional and useful document @dfn{free} in the
sense of freedom: to
+../tar_texi/fdl.texi(,22) assure everyone the effective freedom to copy and
redistribute it,
+../tar_texi/fdl.texi(,23) with or without modifying it, either commercially or
noncommercially.
+../tar_texi/fdl.texi(,24) Secondarily, this License preserves for the author
and publisher a way
+../tar_texi/fdl.texi(,25) to get credit for their work, while not being
considered responsible
+../tar_texi/fdl.texi(,26) for modifications made by others.
+../tar_texi/fdl.texi(,27)
+../tar_texi/fdl.texi(,28) This License is a kind of ``copyleft'', which means
that derivative
+../tar_texi/fdl.texi(,29) works of the document must themselves be free in the
same sense. It
+../tar_texi/fdl.texi(,30) complements the GNU General Public License, which is
a copyleft
+../tar_texi/fdl.texi(,31) license designed for free software.
+../tar_texi/fdl.texi(,32)
+../tar_texi/fdl.texi(,33) We have designed this License in order to use it for
manuals for free
+../tar_texi/fdl.texi(,34) software, because free software needs free
documentation: a free
+../tar_texi/fdl.texi(,35) program should come with manuals providing the same
freedoms that the
+../tar_texi/fdl.texi(,36) software does. But this License is not limited to
software manuals;
+../tar_texi/fdl.texi(,37) it can be used for any textual work, regardless of
subject matter or
+../tar_texi/fdl.texi(,38) whether it is published as a printed book. We
recommend this License
+../tar_texi/fdl.texi(,39) principally for works whose purpose is instruction
or reference.
+../tar_texi/fdl.texi(,40)
+../tar_texi/fdl.texi(,41) @item
+../tar_texi/fdl.texi(,42) APPLICABILITY AND DEFINITIONS
+../tar_texi/fdl.texi(,43)
+../tar_texi/fdl.texi(,44) This License applies to any manual or other work, in
any medium, that
+../tar_texi/fdl.texi(,45) contains a notice placed by the copyright holder
saying it can be
+../tar_texi/fdl.texi(,46) distributed under the terms of this License. Such a
notice grants a
+../tar_texi/fdl.texi(,47) world-wide, royalty-free license, unlimited in
duration, to use that
+../tar_texi/fdl.texi(,48) work under the conditions stated herein. The
``Document'', below,
+../tar_texi/fdl.texi(,49) refers to any such manual or work. Any member of
the public is a
+../tar_texi/fdl.texi(,50) licensee, and is addressed as ``you''. You accept
the license if you
+../tar_texi/fdl.texi(,51) copy, modify or distribute the work in a way
requiring permission
+../tar_texi/fdl.texi(,52) under copyright law.
+../tar_texi/fdl.texi(,53)
+../tar_texi/fdl.texi(,54) A ``Modified Version'' of the Document means any
work containing the
+../tar_texi/fdl.texi(,55) Document or a portion of it, either copied verbatim,
or with
+../tar_texi/fdl.texi(,56) modifications and/or translated into another
language.
+../tar_texi/fdl.texi(,57)
+../tar_texi/fdl.texi(,58) A ``Secondary Section'' is a named appendix or a
front-matter section
+../tar_texi/fdl.texi(,59) of the Document that deals exclusively with the
relationship of the
+../tar_texi/fdl.texi(,60) publishers or authors of the Document to the
Document's overall
+../tar_texi/fdl.texi(,61) subject (or to related matters) and contains nothing
that could fall
+../tar_texi/fdl.texi(,62) directly within that overall subject. (Thus, if the
Document is in
+../tar_texi/fdl.texi(,63) part a textbook of mathematics, a Secondary Section
may not explain
+../tar_texi/fdl.texi(,64) any mathematics.) The relationship could be a
matter of historical
+../tar_texi/fdl.texi(,65) connection with the subject or with related matters,
or of legal,
+../tar_texi/fdl.texi(,66) commercial, philosophical, ethical or political
position regarding
+../tar_texi/fdl.texi(,67) them.
+../tar_texi/fdl.texi(,68)
+../tar_texi/fdl.texi(,69) The ``Invariant Sections'' are certain Secondary
Sections whose titles
+../tar_texi/fdl.texi(,70) are designated, as being those of Invariant
Sections, in the notice
+../tar_texi/fdl.texi(,71) that says that the Document is released under this
License. If a
+../tar_texi/fdl.texi(,72) section does not fit the above definition of
Secondary then it is not
+../tar_texi/fdl.texi(,73) allowed to be designated as Invariant. The Document
may contain zero
+../tar_texi/fdl.texi(,74) Invariant Sections. If the Document does not
identify any Invariant
+../tar_texi/fdl.texi(,75) Sections then there are none.
+../tar_texi/fdl.texi(,76)
+../tar_texi/fdl.texi(,77) The ``Cover Texts'' are certain short passages of
text that are listed,
+../tar_texi/fdl.texi(,78) as Front-Cover Texts or Back-Cover Texts, in the
notice that says that
+../tar_texi/fdl.texi(,79) the Document is released under this License. A
Front-Cover Text may
+../tar_texi/fdl.texi(,80) be at most 5 words, and a Back-Cover Text may be at
most 25 words.
+../tar_texi/fdl.texi(,81)
+../tar_texi/fdl.texi(,82) A ``Transparent'' copy of the Document means a
machine-readable copy,
+../tar_texi/fdl.texi(,83) represented in a format whose specification is
available to the
+../tar_texi/fdl.texi(,84) general public, that is suitable for revising the
document
+../tar_texi/fdl.texi(,85) straightforwardly with generic text editors or (for
images composed of
+../tar_texi/fdl.texi(,86) pixels) generic paint programs or (for drawings)
some widely available
+../tar_texi/fdl.texi(,87) drawing editor, and that is suitable for input to
text formatters or
+../tar_texi/fdl.texi(,88) for automatic translation to a variety of formats
suitable for input
+../tar_texi/fdl.texi(,89) to text formatters. A copy made in an otherwise
Transparent file
+../tar_texi/fdl.texi(,90) format whose markup, or absence of markup, has been
arranged to thwart
+../tar_texi/fdl.texi(,91) or discourage subsequent modification by readers is
not Transparent.
+../tar_texi/fdl.texi(,92) An image format is not Transparent if used for any
substantial amount
+../tar_texi/fdl.texi(,93) of text. A copy that is not ``Transparent'' is
called ``Opaque''.
+../tar_texi/fdl.texi(,94)
+../tar_texi/fdl.texi(,95) Examples of suitable formats for Transparent copies
include plain
+../tar_texi/fdl.texi(,96) @sc{ascii} without markup, Texinfo input format,
address@hidden input
+../tar_texi/fdl.texi(,97) format, @acronym{SGML} or @acronym{XML} using a
publicly available
+../tar_texi/fdl.texi(,98) @acronym{DTD}, and standard-conforming simple
@acronym{HTML},
+../tar_texi/fdl.texi(,99) PostScript or @acronym{PDF} designed for human
modification. Examples
+../tar_texi/fdl.texi(,100) of transparent image formats include @acronym{PNG},
@acronym{XCF} and
+../tar_texi/fdl.texi(,101) @acronym{JPG}. Opaque formats include proprietary
formats that can be
+../tar_texi/fdl.texi(,102) read and edited only by proprietary word
processors, @acronym{SGML} or
+../tar_texi/fdl.texi(,103) @acronym{XML} for which the @acronym{DTD} and/or
processing tools are
+../tar_texi/fdl.texi(,104) not generally available, and the machine-generated
@acronym{HTML},
+../tar_texi/fdl.texi(,105) PostScript or @acronym{PDF} produced by some word
processors for
+../tar_texi/fdl.texi(,106) output purposes only.
+../tar_texi/fdl.texi(,107)
+../tar_texi/fdl.texi(,108) The ``Title Page'' means, for a printed book, the
title page itself,
+../tar_texi/fdl.texi(,109) plus such following pages as are needed to hold,
legibly, the material
+../tar_texi/fdl.texi(,110) this License requires to appear in the title page.
For works in
+../tar_texi/fdl.texi(,111) formats which do not have any title page as such,
``Title Page'' means
+../tar_texi/fdl.texi(,112) the text near the most prominent appearance of the
work's title,
+../tar_texi/fdl.texi(,113) preceding the beginning of the body of the text.
+../tar_texi/fdl.texi(,114)
+../tar_texi/fdl.texi(,115) A section ``Entitled XYZ'' means a named subunit of
the Document whose
+../tar_texi/fdl.texi(,116) title either is precisely XYZ or contains XYZ in
parentheses following
+../tar_texi/fdl.texi(,117) text that translates XYZ in another language.
(Here XYZ stands for a
+../tar_texi/fdl.texi(,118) specific section name mentioned below, such as
``Acknowledgements'',
+../tar_texi/fdl.texi(,119) ``Dedications'', ``Endorsements'', or ``History''.)
To ``Preserve the Title''
+../tar_texi/fdl.texi(,120) of such a section when you modify the Document
means that it remains a
+../tar_texi/fdl.texi(,121) section ``Entitled XYZ'' according to this
definition.
+../tar_texi/fdl.texi(,122)
+../tar_texi/fdl.texi(,123) The Document may include Warranty Disclaimers next
to the notice which
+../tar_texi/fdl.texi(,124) states that this License applies to the Document.
These Warranty
+../tar_texi/fdl.texi(,125) Disclaimers are considered to be included by
reference in this
+../tar_texi/fdl.texi(,126) License, but only as regards disclaiming
warranties: any other
+../tar_texi/fdl.texi(,127) implication that these Warranty Disclaimers may
have is void and has
+../tar_texi/fdl.texi(,128) no effect on the meaning of this License.
+../tar_texi/fdl.texi(,129)
+../tar_texi/fdl.texi(,130) @item
+../tar_texi/fdl.texi(,131) VERBATIM COPYING
+../tar_texi/fdl.texi(,132)
+../tar_texi/fdl.texi(,133) You may copy and distribute the Document in any
medium, either
+../tar_texi/fdl.texi(,134) commercially or noncommercially, provided that this
License, the
+../tar_texi/fdl.texi(,135) copyright notices, and the license notice saying
this License applies
+../tar_texi/fdl.texi(,136) to the Document are reproduced in all copies, and
that you add no other
+../tar_texi/fdl.texi(,137) conditions whatsoever to those of this License.
You may not use
+../tar_texi/fdl.texi(,138) technical measures to obstruct or control the
reading or further
+../tar_texi/fdl.texi(,139) copying of the copies you make or distribute.
However, you may accept
+../tar_texi/fdl.texi(,140) compensation in exchange for copies. If you
distribute a large enough
+../tar_texi/fdl.texi(,141) number of copies you must also follow the
conditions in section 3.
+../tar_texi/fdl.texi(,142)
+../tar_texi/fdl.texi(,143) You may also lend copies, under the same conditions
stated above, and
+../tar_texi/fdl.texi(,144) you may publicly display copies.
+../tar_texi/fdl.texi(,145)
+../tar_texi/fdl.texi(,146) @item
+../tar_texi/fdl.texi(,147) COPYING IN QUANTITY
+../tar_texi/fdl.texi(,148)
+../tar_texi/fdl.texi(,149) If you publish printed copies (or copies in media
that commonly have
+../tar_texi/fdl.texi(,150) printed covers) of the Document, numbering more
than 100, and the
+../tar_texi/fdl.texi(,151) Document's license notice requires Cover Texts, you
must enclose the
+../tar_texi/fdl.texi(,152) copies in covers that carry, clearly and legibly,
all these Cover
+../tar_texi/fdl.texi(,153) Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on
+../tar_texi/fdl.texi(,154) the back cover. Both covers must also clearly and
legibly identify
+../tar_texi/fdl.texi(,155) you as the publisher of these copies. The front
cover must present
+../tar_texi/fdl.texi(,156) the full title with all words of the title equally
prominent and
+../tar_texi/fdl.texi(,157) visible. You may add other material on the covers
in addition.
+../tar_texi/fdl.texi(,158) Copying with changes limited to the covers, as long
as they preserve
+../tar_texi/fdl.texi(,159) the title of the Document and satisfy these
conditions, can be treated
+../tar_texi/fdl.texi(,160) as verbatim copying in other respects.
+../tar_texi/fdl.texi(,161)
+../tar_texi/fdl.texi(,162) If the required texts for either cover are too
voluminous to fit
+../tar_texi/fdl.texi(,163) legibly, you should put the first ones listed (as
many as fit
+../tar_texi/fdl.texi(,164) reasonably) on the actual cover, and continue the
rest onto adjacent
+../tar_texi/fdl.texi(,165) pages.
+../tar_texi/fdl.texi(,166)
+../tar_texi/fdl.texi(,167) If you publish or distribute Opaque copies of the
Document numbering
+../tar_texi/fdl.texi(,168) more than 100, you must either include a
machine-readable Transparent
+../tar_texi/fdl.texi(,169) copy along with each Opaque copy, or state in or
with each Opaque copy
+../tar_texi/fdl.texi(,170) a computer-network location from which the general
network-using
+../tar_texi/fdl.texi(,171) public has access to download using public-standard
network protocols
+../tar_texi/fdl.texi(,172) a complete Transparent copy of the Document, free
of added material.
+../tar_texi/fdl.texi(,173) If you use the latter option, you must take
reasonably prudent steps,
+../tar_texi/fdl.texi(,174) when you begin distribution of Opaque copies in
quantity, to ensure
+../tar_texi/fdl.texi(,175) that this Transparent copy will remain thus
accessible at the stated
+../tar_texi/fdl.texi(,176) location until at least one year after the last
time you distribute an
+../tar_texi/fdl.texi(,177) Opaque copy (directly or through your agents or
retailers) of that
+../tar_texi/fdl.texi(,178) edition to the public.
+../tar_texi/fdl.texi(,179)
+../tar_texi/fdl.texi(,180) It is requested, but not required, that you contact
the authors of the
+../tar_texi/fdl.texi(,181) Document well before redistributing any large
number of copies, to give
+../tar_texi/fdl.texi(,182) them a chance to provide you with an updated
version of the Document.
+../tar_texi/fdl.texi(,183)
+../tar_texi/fdl.texi(,184) @item
+../tar_texi/fdl.texi(,185) MODIFICATIONS
+../tar_texi/fdl.texi(,186)
+../tar_texi/fdl.texi(,187) You may copy and distribute a Modified Version of
the Document under
+../tar_texi/fdl.texi(,188) the conditions of sections 2 and 3 above, provided
that you release
+../tar_texi/fdl.texi(,189) the Modified Version under precisely this License,
with the Modified
+../tar_texi/fdl.texi(,190) Version filling the role of the Document, thus
licensing distribution
+../tar_texi/fdl.texi(,191) and modification of the Modified Version to whoever
possesses a copy
+../tar_texi/fdl.texi(,192) of it. In addition, you must do these things in
the Modified Version:
+../tar_texi/fdl.texi(,193)
+../tar_texi/fdl.texi(,194) @enumerate A
+../tar_texi/fdl.texi(,195) @item
+../tar_texi/fdl.texi(,196) Use in the Title Page (and on the covers, if any) a
title distinct
+../tar_texi/fdl.texi(,197) from that of the Document, and from those of
previous versions
+../tar_texi/fdl.texi(,198) (which should, if there were any, be listed in the
History section
+../tar_texi/fdl.texi(,199) of the Document). You may use the same title as a
previous version
+../tar_texi/fdl.texi(,200) if the original publisher of that version gives
permission.
+../tar_texi/fdl.texi(,201)
+../tar_texi/fdl.texi(,202) @item
+../tar_texi/fdl.texi(,203) List on the Title Page, as authors, one or more
persons or entities
+../tar_texi/fdl.texi(,204) responsible for authorship of the modifications in
the Modified
+../tar_texi/fdl.texi(,205) Version, together with at least five of the
principal authors of the
+../tar_texi/fdl.texi(,206) Document (all of its principal authors, if it has
fewer than five),
+../tar_texi/fdl.texi(,207) unless they release you from this requirement.
+../tar_texi/fdl.texi(,208)
+../tar_texi/fdl.texi(,209) @item
+../tar_texi/fdl.texi(,210) State on the Title page the name of the publisher
of the
+../tar_texi/fdl.texi(,211) Modified Version, as the publisher.
+../tar_texi/fdl.texi(,212)
+../tar_texi/fdl.texi(,213) @item
+../tar_texi/fdl.texi(,214) Preserve all the copyright notices of the Document.
+../tar_texi/fdl.texi(,215)
+../tar_texi/fdl.texi(,216) @item
+../tar_texi/fdl.texi(,217) Add an appropriate copyright notice for your
modifications
+../tar_texi/fdl.texi(,218) adjacent to the other copyright notices.
+../tar_texi/fdl.texi(,219)
+../tar_texi/fdl.texi(,220) @item
+../tar_texi/fdl.texi(,221) Include, immediately after the copyright notices, a
license notice
+../tar_texi/fdl.texi(,222) giving the public permission to use the Modified
Version under the
+../tar_texi/fdl.texi(,223) terms of this License, in the form shown in the
Addendum below.
+../tar_texi/fdl.texi(,224)
+../tar_texi/fdl.texi(,225) @item
+../tar_texi/fdl.texi(,226) Preserve in that license notice the full lists of
Invariant Sections
+../tar_texi/fdl.texi(,227) and required Cover Texts given in the Document's
license notice.
+../tar_texi/fdl.texi(,228)
+../tar_texi/fdl.texi(,229) @item
+../tar_texi/fdl.texi(,230) Include an unaltered copy of this License.
+../tar_texi/fdl.texi(,231)
+../tar_texi/fdl.texi(,232) @item
+../tar_texi/fdl.texi(,233) Preserve the section Entitled ``History'', Preserve
its Title, and add
+../tar_texi/fdl.texi(,234) to it an item stating at least the title, year, new
authors, and
+../tar_texi/fdl.texi(,235) publisher of the Modified Version as given on the
Title Page. If
+../tar_texi/fdl.texi(,236) there is no section Entitled ``History'' in the
Document, create one
+../tar_texi/fdl.texi(,237) stating the title, year, authors, and publisher of
the Document as
+../tar_texi/fdl.texi(,238) given on its Title Page, then add an item
describing the Modified
+../tar_texi/fdl.texi(,239) Version as stated in the previous sentence.
+../tar_texi/fdl.texi(,240)
+../tar_texi/fdl.texi(,241) @item
+../tar_texi/fdl.texi(,242) Preserve the network location, if any, given in the
Document for
+../tar_texi/fdl.texi(,243) public access to a Transparent copy of the
Document, and likewise
+../tar_texi/fdl.texi(,244) the network locations given in the Document for
previous versions
+../tar_texi/fdl.texi(,245) it was based on. These may be placed in the
``History'' section.
+../tar_texi/fdl.texi(,246) You may omit a network location for a work that was
published at
+../tar_texi/fdl.texi(,247) least four years before the Document itself, or if
the original
+../tar_texi/fdl.texi(,248) publisher of the version it refers to gives
permission.
+../tar_texi/fdl.texi(,249)
+../tar_texi/fdl.texi(,250) @item
+../tar_texi/fdl.texi(,251) For any section Entitled ``Acknowledgements'' or
``Dedications'', Preserve
+../tar_texi/fdl.texi(,252) the Title of the section, and preserve in the
section all the
+../tar_texi/fdl.texi(,253) substance and tone of each of the contributor
acknowledgements and/or
+../tar_texi/fdl.texi(,254) dedications given therein.
+../tar_texi/fdl.texi(,255)
+../tar_texi/fdl.texi(,256) @item
+../tar_texi/fdl.texi(,257) Preserve all the Invariant Sections of the Document,
+../tar_texi/fdl.texi(,258) unaltered in their text and in their titles.
Section numbers
+../tar_texi/fdl.texi(,259) or the equivalent are not considered part of the
section titles.
+../tar_texi/fdl.texi(,260)
+../tar_texi/fdl.texi(,261) @item
+../tar_texi/fdl.texi(,262) Delete any section Entitled ``Endorsements''. Such
a section
+../tar_texi/fdl.texi(,263) may not be included in the Modified Version.
+../tar_texi/fdl.texi(,264)
+../tar_texi/fdl.texi(,265) @item
+../tar_texi/fdl.texi(,266) Do not retitle any existing section to be Entitled
``Endorsements'' or
+../tar_texi/fdl.texi(,267) to conflict in title with any Invariant Section.
+../tar_texi/fdl.texi(,268)
+../tar_texi/fdl.texi(,269) @item
+../tar_texi/fdl.texi(,270) Preserve any Warranty Disclaimers.
+../tar_texi/fdl.texi(,271) @end enumerate
+../tar_texi/fdl.texi(,272)
+../tar_texi/fdl.texi(,273) If the Modified Version includes new front-matter
sections or
+../tar_texi/fdl.texi(,274) appendices that qualify as Secondary Sections and
contain no material
+../tar_texi/fdl.texi(,275) copied from the Document, you may at your option
designate some or all
+../tar_texi/fdl.texi(,276) of these sections as invariant. To do this, add
their titles to the
+../tar_texi/fdl.texi(,277) list of Invariant Sections in the Modified
Version's license notice.
+../tar_texi/fdl.texi(,278) These titles must be distinct from any other
section titles.
+../tar_texi/fdl.texi(,279)
+../tar_texi/fdl.texi(,280) You may add a section Entitled ``Endorsements'',
provided it contains
+../tar_texi/fdl.texi(,281) nothing but endorsements of your Modified Version
by various
+../tar_texi/fdl.texi(,282) parties---for example, statements of peer review or
that the text has
+../tar_texi/fdl.texi(,283) been approved by an organization as the
authoritative definition of a
+../tar_texi/fdl.texi(,284) standard.
+../tar_texi/fdl.texi(,285)
+../tar_texi/fdl.texi(,286) You may add a passage of up to five words as a
Front-Cover Text, and a
+../tar_texi/fdl.texi(,287) passage of up to 25 words as a Back-Cover Text, to
the end of the list
+../tar_texi/fdl.texi(,288) of Cover Texts in the Modified Version. Only one
passage of
+../tar_texi/fdl.texi(,289) Front-Cover Text and one of Back-Cover Text may be
added by (or
+../tar_texi/fdl.texi(,290) through arrangements made by) any one entity. If
the Document already
+../tar_texi/fdl.texi(,291) includes a cover text for the same cover,
previously added by you or
+../tar_texi/fdl.texi(,292) by arrangement made by the same entity you are
acting on behalf of,
+../tar_texi/fdl.texi(,293) you may not add another; but you may replace the
old one, on explicit
+../tar_texi/fdl.texi(,294) permission from the previous publisher that added
the old one.
+../tar_texi/fdl.texi(,295)
+../tar_texi/fdl.texi(,296) The author(s) and publisher(s) of the Document do
not by this License
+../tar_texi/fdl.texi(,297) give permission to use their names for publicity
for or to assert or
+../tar_texi/fdl.texi(,298) imply endorsement of any Modified Version.
+../tar_texi/fdl.texi(,299)
+../tar_texi/fdl.texi(,300) @item
+../tar_texi/fdl.texi(,301) COMBINING DOCUMENTS
+../tar_texi/fdl.texi(,302)
+../tar_texi/fdl.texi(,303) You may combine the Document with other documents
released under this
+../tar_texi/fdl.texi(,304) License, under the terms defined in section 4 above
for modified
+../tar_texi/fdl.texi(,305) versions, provided that you include in the
combination all of the
+../tar_texi/fdl.texi(,306) Invariant Sections of all of the original
documents, unmodified, and
+../tar_texi/fdl.texi(,307) list them all as Invariant Sections of your
combined work in its
+../tar_texi/fdl.texi(,308) license notice, and that you preserve all their
Warranty Disclaimers.
+../tar_texi/fdl.texi(,309)
+../tar_texi/fdl.texi(,310) The combined work need only contain one copy of
this License, and
+../tar_texi/fdl.texi(,311) multiple identical Invariant Sections may be
replaced with a single
+../tar_texi/fdl.texi(,312) copy. If there are multiple Invariant Sections
with the same name but
+../tar_texi/fdl.texi(,313) different contents, make the title of each such
section unique by
+../tar_texi/fdl.texi(,314) adding at the end of it, in parentheses, the name
of the original
+../tar_texi/fdl.texi(,315) author or publisher of that section if known, or
else a unique number.
+../tar_texi/fdl.texi(,316) Make the same adjustment to the section titles in
the list of
+../tar_texi/fdl.texi(,317) Invariant Sections in the license notice of the
combined work.
+../tar_texi/fdl.texi(,318)
+../tar_texi/fdl.texi(,319) In the combination, you must combine any sections
Entitled ``History''
+../tar_texi/fdl.texi(,320) in the various original documents, forming one
section Entitled
+../tar_texi/fdl.texi(,321) ``History''; likewise combine any sections Entitled
``Acknowledgements'',
+../tar_texi/fdl.texi(,322) and any sections Entitled ``Dedications''. You
must delete all
+../tar_texi/fdl.texi(,323) sections Entitled ``Endorsements.''
+../tar_texi/fdl.texi(,324)
+../tar_texi/fdl.texi(,325) @item
+../tar_texi/fdl.texi(,326) COLLECTIONS OF DOCUMENTS
+../tar_texi/fdl.texi(,327)
+../tar_texi/fdl.texi(,328) You may make a collection consisting of the
Document and other documents
+../tar_texi/fdl.texi(,329) released under this License, and replace the
individual copies of this
+../tar_texi/fdl.texi(,330) License in the various documents with a single copy
that is included in
+../tar_texi/fdl.texi(,331) the collection, provided that you follow the rules
of this License for
+../tar_texi/fdl.texi(,332) verbatim copying of each of the documents in all
other respects.
+../tar_texi/fdl.texi(,333)
+../tar_texi/fdl.texi(,334) You may extract a single document from such a
collection, and distribute
+../tar_texi/fdl.texi(,335) it individually under this License, provided you
insert a copy of this
+../tar_texi/fdl.texi(,336) License into the extracted document, and follow
this License in all
+../tar_texi/fdl.texi(,337) other respects regarding verbatim copying of that
document.
+../tar_texi/fdl.texi(,338)
+../tar_texi/fdl.texi(,339) @item
+../tar_texi/fdl.texi(,340) AGGREGATION WITH INDEPENDENT WORKS
+../tar_texi/fdl.texi(,341)
+../tar_texi/fdl.texi(,342) A compilation of the Document or its derivatives
with other separate
+../tar_texi/fdl.texi(,343) and independent documents or works, in or on a
volume of a storage or
+../tar_texi/fdl.texi(,344) distribution medium, is called an ``aggregate'' if
the copyright
+../tar_texi/fdl.texi(,345) resulting from the compilation is not used to limit
the legal rights
+../tar_texi/fdl.texi(,346) of the compilation's users beyond what the
individual works permit.
+../tar_texi/fdl.texi(,347) When the Document is included in an aggregate, this
License does not
+../tar_texi/fdl.texi(,348) apply to the other works in the aggregate which are
not themselves
+../tar_texi/fdl.texi(,349) derivative works of the Document.
+../tar_texi/fdl.texi(,350)
+../tar_texi/fdl.texi(,351) If the Cover Text requirement of section 3 is
applicable to these
+../tar_texi/fdl.texi(,352) copies of the Document, then if the Document is
less than one half of
+../tar_texi/fdl.texi(,353) the entire aggregate, the Document's Cover Texts
may be placed on
+../tar_texi/fdl.texi(,354) covers that bracket the Document within the
aggregate, or the
+../tar_texi/fdl.texi(,355) electronic equivalent of covers if the Document is
in electronic form.
+../tar_texi/fdl.texi(,356) Otherwise they must appear on printed covers that
bracket the whole
+../tar_texi/fdl.texi(,357) aggregate.
+../tar_texi/fdl.texi(,358)
+../tar_texi/fdl.texi(,359) @item
+../tar_texi/fdl.texi(,360) TRANSLATION
+../tar_texi/fdl.texi(,361)
+../tar_texi/fdl.texi(,362) Translation is considered a kind of modification,
so you may
+../tar_texi/fdl.texi(,363) distribute translations of the Document under the
terms of section 4.
+../tar_texi/fdl.texi(,364) Replacing Invariant Sections with translations
requires special
+../tar_texi/fdl.texi(,365) permission from their copyright holders, but you
may include
+../tar_texi/fdl.texi(,366) translations of some or all Invariant Sections in
addition to the
+../tar_texi/fdl.texi(,367) original versions of these Invariant Sections. You
may include a
+../tar_texi/fdl.texi(,368) translation of this License, and all the license
notices in the
+../tar_texi/fdl.texi(,369) Document, and any Warranty Disclaimers, provided
that you also include
+../tar_texi/fdl.texi(,370) the original English version of this License and
the original versions
+../tar_texi/fdl.texi(,371) of those notices and disclaimers. In case of a
disagreement between
+../tar_texi/fdl.texi(,372) the translation and the original version of this
License or a notice
+../tar_texi/fdl.texi(,373) or disclaimer, the original version will prevail.
+../tar_texi/fdl.texi(,374)
+../tar_texi/fdl.texi(,375) If a section in the Document is Entitled
``Acknowledgements'',
+../tar_texi/fdl.texi(,376) ``Dedications'', or ``History'', the requirement
(section 4) to Preserve
+../tar_texi/fdl.texi(,377) its Title (section 1) will typically require
changing the actual
+../tar_texi/fdl.texi(,378) title.
+../tar_texi/fdl.texi(,379)
+../tar_texi/fdl.texi(,380) @item
+../tar_texi/fdl.texi(,381) TERMINATION
+../tar_texi/fdl.texi(,382)
+../tar_texi/fdl.texi(,383) You may not copy, modify, sublicense, or distribute
the Document except
+../tar_texi/fdl.texi(,384) as expressly provided for under this License. Any
other attempt to
+../tar_texi/fdl.texi(,385) copy, modify, sublicense or distribute the Document
is void, and will
+../tar_texi/fdl.texi(,386) automatically terminate your rights under this
License. However,
+../tar_texi/fdl.texi(,387) parties who have received copies, or rights, from
you under this
+../tar_texi/fdl.texi(,388) License will not have their licenses terminated so
long as such
+../tar_texi/fdl.texi(,389) parties remain in full compliance.
+../tar_texi/fdl.texi(,390)
+../tar_texi/fdl.texi(,391) @item
+../tar_texi/fdl.texi(,392) FUTURE REVISIONS OF THIS LICENSE
+../tar_texi/fdl.texi(,393)
+../tar_texi/fdl.texi(,394) The Free Software Foundation may publish new,
revised versions
+../tar_texi/fdl.texi(,395) of the GNU Free Documentation License from time to
time. Such new
+../tar_texi/fdl.texi(,396) versions will be similar in spirit to the present
version, but may
+../tar_texi/fdl.texi(,397) differ in detail to address new problems or
concerns. See
+../tar_texi/fdl.texi(,398) @uref{http://www.gnu.org/copyleft/}.
+../tar_texi/fdl.texi(,399)
+../tar_texi/fdl.texi(,400) Each version of the License is given a
distinguishing version number.
+../tar_texi/fdl.texi(,401) If the Document specifies that a particular
numbered version of this
+../tar_texi/fdl.texi(,402) License ``or any later version'' applies to it, you
have the option of
+../tar_texi/fdl.texi(,403) following the terms and conditions either of that
specified version or
+../tar_texi/fdl.texi(,404) of any later version that has been published (not
as a draft) by the
+../tar_texi/fdl.texi(,405) Free Software Foundation. If the Document does not
specify a version
+../tar_texi/fdl.texi(,406) number of this License, you may choose any version
ever published (not
+../tar_texi/fdl.texi(,407) as a draft) by the Free Software Foundation.
+../tar_texi/fdl.texi(,408) @end enumerate
+../tar_texi/fdl.texi(,409)
+../tar_texi/fdl.texi(,410) @page
+../tar_texi/fdl.texi(,411) @appendixsubsec ADDENDUM: How to use this License
for your documents
+../tar_texi/fdl.texi(,412)
+../tar_texi/fdl.texi(,413) To use this License in a document you have written,
include a copy of
+../tar_texi/fdl.texi(,414) the License in the document and put the following
copyright and
+../tar_texi/fdl.texi(,415) license notices just after the title page:
+../tar_texi/fdl.texi(,416)
+../tar_texi/fdl.texi(,417) @smallexample
+../tar_texi/fdl.texi(,418) @group
+../tar_texi/fdl.texi(,419) Copyright (C) @var{year} @var{your name}.
+../tar_texi/fdl.texi(,420) Permission is granted to copy, distribute and/or
modify this document
+../tar_texi/fdl.texi(,421) under the terms of the GNU Free Documentation
License, Version 1.2
+../tar_texi/fdl.texi(,422) or any later version published by the Free
Software Foundation;
+../tar_texi/fdl.texi(,423) with no Invariant Sections, no Front-Cover Texts,
and no Back-Cover
+../tar_texi/fdl.texi(,424) Texts. A copy of the license is included in the
section entitled ``GNU
+../tar_texi/fdl.texi(,425) Free Documentation License''.
+../tar_texi/fdl.texi(,426) @end group
+../tar_texi/fdl.texi(,427) @end smallexample
+../tar_texi/fdl.texi(,428)
+../tar_texi/fdl.texi(,429) If you have Invariant Sections, Front-Cover Texts
and Back-Cover Texts,
+../tar_texi/fdl.texi(,430) replace the ``with...Texts.'' line with this:
+../tar_texi/fdl.texi(,431)
+../tar_texi/fdl.texi(,432) @smallexample
+../tar_texi/fdl.texi(,433) @group
+../tar_texi/fdl.texi(,434) with the Invariant Sections being @var{list
their titles}, with
+../tar_texi/fdl.texi(,435) the Front-Cover Texts being @var{list}, and
with the Back-Cover Texts
+../tar_texi/fdl.texi(,436) being @var{list}.
+../tar_texi/fdl.texi(,437) @end group
+../tar_texi/fdl.texi(,438) @end smallexample
+../tar_texi/fdl.texi(,439)
+../tar_texi/fdl.texi(,440) If you have Invariant Sections without Cover Texts,
or some other
+../tar_texi/fdl.texi(,441) combination of the three, merge those two
alternatives to suit the
+../tar_texi/fdl.texi(,442) situation.
+../tar_texi/fdl.texi(,443)
+../tar_texi/fdl.texi(,444) If your document contains nontrivial examples of
program code, we
+../tar_texi/fdl.texi(,445) recommend releasing these examples in parallel
under your choice of
+../tar_texi/fdl.texi(,446) free software license, such as the GNU General
Public License,
+../tar_texi/fdl.texi(,447) to permit their use in free software.
+../tar_texi/fdl.texi(,448)
+../tar_texi/fdl.texi(,449) @c Local Variables:
+../tar_texi/fdl.texi(,450) @c ispell-local-pdict: "ispell-dict"
+../tar_texi/fdl.texi(,451) @c End:
+../tar_texi/fdl.texi(,452)
+../tar_texi/tar.texi(,10794)
+../tar_texi/tar.texi(,10795) @node Index of Command Line Options
+../tar_texi/tar.texi(,10796) @appendix Index of Command Line Options
+../tar_texi/tar.texi(,10797)
+../tar_texi/tar.texi(GNUTAR,10798) This appendix contains an index of all
../tar_texi/tar.texi(GNUTAR,10798) @acronym{GNU}
@command{tar}../tar_texi/tar.texi(GNUTAR,10798) long command line
+../tar_texi/tar.texi(,10799) options. The options are listed without the
preceeding double-dash.
+../tar_texi/tar.texi(,10800) For a cross-reference of short command line
options, @ref{Short Option Summary}.
+../tar_texi/tar.texi(,10801)
+../tar_texi/tar.texi(,10802) @printindex op
+../tar_texi/tar.texi(,10803)
+../tar_texi/tar.texi(,10804) @node Index
+../tar_texi/tar.texi(,10805) @appendix Index
+../tar_texi/tar.texi(,10806)
+../tar_texi/tar.texi(,10807) @printindex cp
+../tar_texi/tar.texi(,10808)
+../tar_texi/tar.texi(,10809) @summarycontents
+../tar_texi/tar.texi(,10810) @contents
+../tar_texi/tar.texi(,10811) @bye
Index: Tests/tar_texi/config.texi
===================================================================
RCS file: Tests/tar_texi/config.texi
diff -N Tests/tar_texi/config.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/config.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1 @@
address@hidden top_srcdir /home/gray/gnu/tar
Index: Tests/tar_texi/dumpdir.texi
===================================================================
RCS file: Tests/tar_texi/dumpdir.texi
diff -N Tests/tar_texi/dumpdir.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/dumpdir.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,132 @@
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. @GNUTAR{}
+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
Index: Tests/tar_texi/fdl.texi
===================================================================
RCS file: Tests/tar_texi/fdl.texi
diff -N Tests/tar_texi/fdl.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/fdl.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,452 @@
+
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:
+
Index: Tests/tar_texi/freemanuals.texi
===================================================================
RCS file: Tests/tar_texi/freemanuals.texi
diff -N Tests/tar_texi/freemanuals.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/freemanuals.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,89 @@
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}.
Index: Tests/tar_texi/genfile.texi
===================================================================
RCS file: Tests/tar_texi/genfile.texi
diff -N Tests/tar_texi/genfile.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/genfile.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,325 @@
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 @FIXME{should we also support @samp{%} notations
+as in stat(1)??}:
+
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.
Index: Tests/tar_texi/getdate.texi
===================================================================
RCS file: Tests/tar_texi/getdate.texi
diff -N Tests/tar_texi/getdate.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/getdate.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,553 @@
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}).
Index: Tests/tar_texi/header.texi
===================================================================
RCS file: Tests/tar_texi/header.texi
diff -N Tests/tar_texi/header.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/header.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,244 @@
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;
+
Index: Tests/tar_texi/intern.texi
===================================================================
RCS file: Tests/tar_texi/intern.texi
diff -N Tests/tar_texi/intern.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/intern.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,335 @@
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
+
+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 learn more about having more than one archive member with the
+same name, see -backup node, when it's written.}
+
+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 @GNUTAR{} 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 @GNUTAR{}
+distribution, this is part of file @file{src/tar.h}:
+
address@hidden
address@hidden header.texi
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 big a name before field overflows?}
+
+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. @FIXME-xref{Modifiers, in
+particular the @option{--incremental} (@option{-G}) option.}
+
+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
+
+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 sparse.texi
+
address@hidden Snapshot Files
address@hidden Format of the Incremental Snapshot Files
address@hidden snapshot.texi
+
address@hidden Dumpdir
address@hidden Dumpdir
address@hidden dumpdir.texi
+
Index: Tests/tar_texi/rendition.texi
===================================================================
RCS file: Tests/tar_texi/rendition.texi
diff -N Tests/tar_texi/rendition.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/rendition.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,95 @@
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 PUBLISH
address@hidden DISTRIB
address@hidden PROOF
address@hidden DISTRIB
address@hidden ifclear
address@hidden ifclear
address@hidden ifclear
+
address@hidden PUBLISH
address@hidden RENDITION The book, version
address@hidden ifset
+
address@hidden DISTRIB
address@hidden RENDITION FTP release, version
address@hidden ifset
+
address@hidden PROOF
address@hidden RENDITION Proof reading version
address@hidden ifset
+
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
Index: Tests/tar_texi/snapshot.texi
===================================================================
RCS file: Tests/tar_texi/snapshot.texi
diff -N Tests/tar_texi/snapshot.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/snapshot.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,66 @@
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.
+
+ @GNUTAR{} version @value{VERSION} supports two snapshot file
+formats. The first format, called @dfn{format 0}, is the one used by
address@hidden 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 @GNUTAR{} 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
+
+
Index: Tests/tar_texi/sparse.texi
===================================================================
RCS file: Tests/tar_texi/sparse.texi
diff -N Tests/tar_texi/sparse.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/sparse.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,235 @@
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 @GNUTAR{} user have been described in detail in
address@hidden This chapter describes the internal format @GNUTAR{}
+uses to store such files.
+
+The support for sparse files in @GNUTAR{} 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 @GNUTAR{} 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, @GNUTAR{} 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 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 @GNUTAR{}
+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 @GNUTAR{}.
address@hidden Recovery}, for the detailed information on how to extract
+sparse members without @GNUTAR{}.
+
Index: Tests/tar_texi/tar.texi
===================================================================
RCS file: Tests/tar_texi/tar.texi
diff -N Tests/tar_texi/tar.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/tar.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,10815 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden tar.info
address@hidden version.texi
address@hidden GNU tar @value{VERSION}
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 rendition.texi
address@hidden value.texi
+
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
+
+This manual is for @acronym{GNU} @command{tar} (version
address@hidden, @value{UPDATED}), 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 copying
+
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 @GNUTAR{}.
address@hidden direntry
+
address@hidden @acronym{GNU} @command{tar}
+
address@hidden
address@hidden @acronym{GNU} tar: an archiver tool
address@hidden @value{RENDITION} @value{VERSION}, @value{UPDATED}
address@hidden John Gilmore, Jay Fenlason et al.
+
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
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 ifnottex
+
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:: @GNUTAR{} 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 @GNUTAR{}
+
+* 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 Operations
+
+* Basic tar::
+* Advanced tar::
+* create options::
+* extract options::
+* backup::
+* Applications::
+* looking ahead::
+
+Advanced @GNUTAR{} 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 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 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:: @GNUTAR{} 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 @GNUTAR{}
+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 sounds more like a @acronym{GNU} Project Manuals Concept [tm]
more
+than the reality. should think about whether this makes sense to say
+here, or not.} The other chapters are meant to be used as a
+reference. Each chapter presents everything that needs to be said
+about a specific topic.
+
+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 following table entries need a bit of work.}
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 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 @GNUTAR{} Authors
+
address@hidden 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 @GNUTAR{} distribution.
+
address@hidden want all of these names mentioned, Absolutely. BUT, i'm not
+sure i want to spell out the history in this detail, at least not for
+the printed book. i'm just not sure it needs to be said this way.
+i'll think about it.}
+
address@hidden is more important, and surely more interesting, than
+actual names. Quoting names without history would be meaningless. FP}
+
+Jay Fenlason put together a draft of a @GNUTAR{}
+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 @GNUTAR{}.
+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 @value{VERSION} 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 @GNUTAR{} 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 @GNUTAR{} 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. @FIXME{Be more specific, I'd
+like to make this node as detailed as 'Bug reporting' node in Emacs
+manual}.
+
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. @FIXME{and what
+else?}
+
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 is a cop out. need to add some simple tape drive info.}
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. @FIXME{make sure this is still the case,
+at the end}We will indicate those abbreviations appropriately to get
+you used to seeing them. (Note that the ``old style'' option forms
+exist in @GNUTAR{} for compatibility with Unix
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, 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, 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 @GNUTAR{}.
+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 @GNUTAR{} 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 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, 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, @GNUTAR{} 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, using with @option{--verbose}}
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
address@hidden
+(note the different font styles).
address@hidden iftex
address@hidden
+.
address@hidden ifinfo
+
+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 don't like how this is worded:} 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.) @GNUTAR{}
+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 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, using with @option{--verbose}}
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, 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 @GNUTAR{} 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 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, 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 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 sure the above works when going through the examples in
+order...}
+
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 examples, here? hag thinks it's a good idea.}
+
address@hidden going further
address@hidden Going Further Ahead in this Manual
+
address@hidden to write up a node here about the things that are going to
+be in the rest of the manual.}
+
address@hidden tar invocation
address@hidden Invoking @GNUTAR{}
address@hidden
+
+This chapter is about how one invokes the @GNUTAR{}
+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 @GNUTAR{} 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, @GNUTAR{} 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 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 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 at end of this node. need to think of an actual outline
+for this chapter; probably do that after stuff from chapter 4 is
+incorporated.}
+
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
+
+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. @GNUTAR{}
+supports them not only for historical reasons, but also because many
+people are used to them. For compatibility with Unix @command{tar},
+the first argument is always treated as containing command and option
+letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is
+equivalent to @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 @GNUTAR{} 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. @FIXME{not sure i liked
+the first sentence of this paragraph..}
+
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
address@hidden --append
address@hidden -r
+
+Appends files to the end of the archive. @xref{append}.
+
address@hidden
address@hidden --catenate
address@hidden -A
+
+Same as @option{--concatenate}. @xref{concatenate}.
+
address@hidden
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
address@hidden --concatenate
address@hidden -A
+
+Appends other @command{tar} archives to the end of the archive.
address@hidden
+
address@hidden
address@hidden --create
address@hidden -c
+
+Creates a new @command{tar} archive. @xref{create}.
+
address@hidden
address@hidden --delete
+
+Deletes members from the archive. Don't try this on a archive on a
+tape! @xref{delete}.
+
address@hidden
address@hidden --diff
address@hidden -d
+
+Same @option{--compare}. @xref{compare}.
+
address@hidden
address@hidden --extract
address@hidden -x
+
+Extracts members from the archive into the file system. @xref{extract}.
+
address@hidden
address@hidden --get
address@hidden -x
+
+Same as @option{--extract}. @xref{extract}.
+
address@hidden
address@hidden --list
address@hidden -t
+
+Lists the members in an archive. @xref{list}.
+
address@hidden
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
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
address@hidden --after-date
+
+(See @option{--newer}, @pxref{after})
+
address@hidden
address@hidden --anchored
+A pattern must match an initial subsequence of the name's components.
address@hidden pattern-matching}.
+
address@hidden
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
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
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
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
address@hidden --bzip2
address@hidden -j
+
+This option tells @command{tar} to read or write archives through
address@hidden @xref{gzip}.
+
address@hidden
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
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 @GNUTAR{} 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
address@hidden
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
address@hidden --confirmation
+
+(See @option{--interactive}.) @xref{interactive}.
+
address@hidden
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
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
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
address@hidden address@hidden
+
+When performing operations, @command{tar} will skip files that match
address@hidden @xref{exclude}.
+
address@hidden
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
address@hidden --exclude-caches
+
+Automatically excludes all directories
+containing a cache directory tag. @xref{exclude}.
+
address@hidden
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
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
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
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
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
address@hidden
address@hidden
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
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
address@hidden --ignore-case
+Ignore case when matching member or file names with
+patterns. @xref{controlling pattern-matching}.
+
address@hidden
address@hidden --ignore-command-error
+Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
+
address@hidden
address@hidden --ignore-failed-read
+
+Do not exit unsuccessfully merely because an unreadable file was encountered.
address@hidden
+
address@hidden
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
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
address@hidden address@hidden
+
+Send verbose output to @var{file} instead of to standard output.
+
address@hidden
address@hidden
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
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
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
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
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
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
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
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
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 --new-volume-script
+
+(see --info-script)
+
address@hidden
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
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
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
address@hidden --no-anchored
+An exclude pattern can match any subsequence of the name's components.
address@hidden pattern-matching}.
+
address@hidden
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
address@hidden --no-ignore-case
+Use case-sensitive matching.
address@hidden pattern-matching}.
+
address@hidden
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
address@hidden --no-overwrite-dir
+
+Preserve metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden
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
address@hidden --no-recursion
+
+With this option, @command{tar} will not recurse into directories.
address@hidden
+
address@hidden
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
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
address@hidden --no-unquote
+Treat all input file or member names literally, do not interpret
+escape sequences. @xref{input name quoting}.
+
address@hidden
address@hidden --no-wildcards
+Do not use wildcards.
address@hidden pattern-matching}.
+
address@hidden
address@hidden --no-wildcards-match-slash
+Wildcards do not match @samp{/}.
address@hidden pattern-matching}.
+
address@hidden
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
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 @GNUTAR{}, and will be
+removed in the future releases.
+
address@hidden, for more information.
+
address@hidden
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
address@hidden --old-archive
+Synonym for @option{--format=v7}.
+
address@hidden
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 @GNUTAR{} understood @option{-l} as a
+synonym for @option{--one-file-system}. This has changed in version
+1.15.91. @xref{Changes}, for more information.}.
+
address@hidden
address@hidden --overwrite
+
+Overwrite existing files and directory metadata when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden
address@hidden --overwrite-dir
+
+Overwrite the metadata of existing directories when extracting files
+from an archive. @xref{Overwrite Old Files}.
+
address@hidden
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
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
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
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
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
address@hidden --portability
address@hidden --old-archive
+Synonym for @option{--format=v7}.
+
address@hidden
address@hidden --posix
+Same as @option{--format=posix}.
+
address@hidden
address@hidden --preserve
+
+Synonymous with specifying both @option{--preserve-permissions} and
address@hidden @xref{Setting Access Permissions}.
+
address@hidden
address@hidden --preserve-order
+
+(See @option{--same-order}; @pxref{Reading}.)
+
address@hidden
address@hidden
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
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
address@hidden address@hidden
+
+Instructs @command{tar} to use @var{size} bytes per record when accessing the
+archive. @xref{Blocking Factor}.
+
address@hidden
address@hidden --recursion
+
+With this option, @command{tar} recurses into directories.
address@hidden
+
address@hidden
address@hidden --recursive-unlink
+
+Remove existing
+directory hierarchies before extracting directories of the same name
+from the archive. @xref{Recursive Unlink}.
+
address@hidden
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
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
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
address@hidden address@hidden
+
+Notifies @command{tar} that is should use @var{cmd} to communicate with remote
+devices. @xref{Device}.
+
address@hidden
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
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 --same-permissions
+
+(See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
+
address@hidden
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
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
address@hidden
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
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
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
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
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, summary
address@hidden address@hidden
+
+Alters the suffix @command{tar} uses when backing up files from the default
address@hidden @xref{backup}.
+
address@hidden
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
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
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
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
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
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 --uncompress
+
+(See @option{--compress}. @pxref{gzip})
+
address@hidden
address@hidden --ungzip
+
+(See @option{--gzip}. @pxref{gzip})
+
address@hidden
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
address@hidden --unquote
+Enable unquoting input file or member names (default). @xref{input
+name quoting}.
+
address@hidden
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
address@hidden --utc
+
+Display file modification dates in @acronym{UTC}. This option implies
address@hidden
+
address@hidden
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
address@hidden --verify
address@hidden -W
+
+Verifies that the archive was correctly written when creating an
+archive. @xref{verify}.
+
address@hidden
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
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
address@hidden --wildcards
+Use wildcards when matching member names with patterns.
address@hidden pattern-matching}.
+
address@hidden
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 @GNUTAR{}. 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 @GNUTAR{} 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, 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) @value{VERSION}
+Copyright (C) 2006 Free Software Foundation, Inc.
+This is free software. You may redistribute copies of it under the terms
+of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+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, 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. @GNUTAR{}
+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 @GNUTAR{}
+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 @GNUTAR{}
+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 @GNUTAR{}.
+If you observe such a @code{man} page on the system you are running,
+either it does not belong to @GNUTAR{}, 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 @GNUTAR{} is this Texinfo documentation.
+
address@hidden defaults
address@hidden Obtaining @GNUTAR{} default values
+
address@hidden show-defaults
address@hidden 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 @GNUTAR{} 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 @GNUTAR{}
+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 @GNUTAR{} 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 @GNUTAR{} 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, 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, @GNUTAR{} 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 @GNUTAR{} 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, complementary notes}
address@hidden --extract
address@hidden --get
address@hidden -x
+
+A socket is stored, within a @GNUTAR{} archive, as a pipe.
+
address@hidden @option{--list} (@option{-t})
+
address@hidden 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 @GNUTAR{} Operations
+
+Now that you have learned the basics of using @GNUTAR{}, 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 this after the chapter is actually revised to make sure
+it still introduces the info in the chapter correctly : ).}
+
address@hidden
+* Operations::
+* append::
+* update::
+* concatenate::
+* delete::
+* compare::
address@hidden menu
+
address@hidden Operations
address@hidden The Five Advanced @command{tar} Operations
address@hidden
+
+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 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 hag -- you might want to incorporate some of the above into the
+MMwtSN node; not sure. i didn't know how to make it simpler...
+
+There are a few ways to get around this. (maybe xref Multiple Members
+with the Same Name.}
+
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 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 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 examples of media on which --update will fail? need to ask
+charles and/or mib/thomas/dave shevett..}
+
+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 @GNUTAR{}
+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 is no way to specify a new name...}
+
+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 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 if the above listing is actually produced after running
+all the examples on collection.tar.}
+
+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 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, 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. @GNUTAR{} 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}) @GNUTAR{}
+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, 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 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 sentence or so of intro here}
+
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. @GNUTAR{}
+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 paragraph}
+
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, 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, 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, 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 @GNUTAR{} 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 @GNUTAR{} 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!) @GNUTAR{} 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, 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, @GNUTAR{} 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. @GNUTAR{}
+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, @GNUTAR{} 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, @GNUTAR{} 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 @GNUTAR{}
+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 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 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 section is too terse. Something more to add? An example,
+maybe?}
+
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 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 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 Unix file linking capability to recreate directory
+structures---linking files into one subdirectory and then
address@hidden that directory.}
+
address@hidden hairy example using absolute-names, newer, etc.}
+
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 case it's not obvious, i'm making this up in some sense
+based on my limited memory of what the next chapter *really* does. i
+just wanted to flesh out this final section a little bit so i'd
+remember to stick it in here. :-)}
+
+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 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
+
+Here is a possible plan for a future documentation about the backuping
+scripts which are provided within the @GNUTAR{}
+distribution.
+
address@hidden @bullet
address@hidden dumps
+ @itemize @minus
+ @item what are dumps
+ @item different levels of dumps
+ @itemize +
+ @item full dump = dump everything
+ @item level 1, level 2 dumps etc
+ A level @var{n} dump dumps everything changed since the last level
+ @var{n}-1 dump (?)
+ @end itemize
+ @item how to use scripts for dumps (ie, the concept)
+ @itemize +
+ @item scripts to run after editing backup specs (details)
+ @end itemize
+ @item Backup Specs, what is it.
+ @itemize +
+ @item how to customize
+ @item actual text of script [/sp/dump/backup-specs]
+ @end itemize
+ @item Problems
+ @itemize +
+ @item rsh doesn't work
+ @item rtape isn't installed
+ @item (others?)
+ @end itemize
+ @item the @option{--incremental} option of tar
+ @item tapes
+ @itemize +
+ @item write protection
+ @item types of media, different sizes and types, useful for different things
+ @item files and tape marks
+ one tape mark between files, two at end.
+ @item positioning the tape
+ MT writes two at end of write,
+ backspaces over one when writing again.
+ @end itemize
+ @end itemize
address@hidden itemize
+}
+
+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 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 @GNUTAR{} archive that
+stores additional metadata so that exact state of the file system
+can be restored when extracting the archive.
+
address@hidden 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, using with @option{--extract}}
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 @GNUTAR{} 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, using with @option{--list}}
address@hidden, using with @option{--list}}
address@hidden, using with @option{--incremental}}
address@hidden, using with @option{--listed-incremental}}
+Versions of @GNUTAR{} 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 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 @GNUTAR{} 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 @GNUTAR{}.
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, @GNUTAR{} 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 @GNUTAR{} 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
+
+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 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, 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 @GNUTAR{} 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}, @GNUTAR{}
+tries to minimize input and output operations. The Amanda backup
+system, when used with @GNUTAR{}, 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 @GNUTAR{} 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 @GNUTAR{} up to 1.15.1
+recognized only @option{-C} option in file lists, and only if the
+option and its argument occupied two consecutive lines.} For example,
+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, 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 anything else here to conclude the section?}
+
address@hidden exclude
address@hidden Excluding Some Files
address@hidden
+
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, 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 @GNUTAR{} 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 change in semantics must have occurred before 1.11,
+so I doubt if it is worth mentioning at all. Anyway, should at
+least specify in which version the semantics changed.}
+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. @GNUTAR{} 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 next few paragraphs need work.}
+
+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 to add a sentence or so here to make this clear for those
+who don't have dan around.}
+
+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 @GNUTAR{} 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 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{../}. @GNUTAR{}
+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 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 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. @GNUTAR{}
+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 @GNUTAR{} 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 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}) @GNUTAR{} 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 Avoiding recursion in directories
address@hidden Descending directories, avoiding
address@hidden Directories, avoiding recursion
address@hidden Recursion in directories, avoiding
+
address@hidden this is still somewhat confusing to me. :-< }
+
+Usually, @command{tar} will recursively explore all directories (either
+those given on the command line or through the @option{--files-from}
+option) for the various files they contain. However, you may not always
+want @command{tar} to act this way.
+
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}, @GNUTAR{} 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 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 to read over this node now for continuity; i've switched
+things around some.}
+
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 @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, @GNUTAR{} drops a leading @samp{/} on
+input or output, and complains about file names containing a @file{..}
+component. This option turns off this behavior.
+
+When @command{tar} extracts archive members from an archive, it strips any
+leading slashes (@samp{/}) from the member name. This causes absolute
+member names in the archive to be treated as relative file names. This
+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
+program to use. Therefore, @GNUTAR{} 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 be an example in the tutorial/wizardry section using this
+to transfer files between systems.}
+
address@hidden write access an issue?}
+
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 is still horrible; need to talk with dan on monday.}
+
address@hidden prints out a message about removing the @samp{/} from
+file names. This message appears once per @GNUTAR{}
+invocation. It represents something which ought to be told; ignoring
+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 getdate.texi
+
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 @GNUTAR{} 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 @GNUTAR{} 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 @GNUTAR{} @value{VERSION} 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. @GNUTAR{} 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 @GNUTAR{}.
+
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 @GNUTAR{} is defined at compilation
+time. You may check it by running @command{tar --help}, and examining
+the last lines of its output. Usually, @GNUTAR{} 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 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 @GNUTAR{} 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 @GNUTAR{}
+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 @GNUTAR{}:
+
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 @GNUTAR{}.
+
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 @GNUTAR{}. This would allow for viewing the
+contents without decompression, and for resynchronizing decompression at
+every volume or file, in case of corrupted archives. Doing so, we might
+lose some compressibility. But this would have make recovering easier.
+So, there are pros and cons. We'll see!
+
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 @GNUTAR{} does not support. There
+are two requirements to which @var{prog} should comply:
+
+First, when called without options, it should read data from standard
+input, compress it and output it on standard output.
+
+Secondly, if called with @option{-d} argument, it should do exactly
+the opposite, i.e., read the compressed data from the standard input
+and produce uncompressed data on the standard output.
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
+The above is based on the following discussion:
+
+ I have one question, or maybe it's a suggestion if there isn't a way
+ to do it now. I would like to use @option{--gzip}, but I'd also like
+ the output to be fed through a program like @acronym{GNU}
+ @command{ecc} (actually, right now that's @samp{exactly} what I'd like
+ to use :-)), basically adding ECC protection on top of compression.
+ It seems as if this should be quite easy to do, but I can't work out
+ exactly how to go about it. Of course, I can pipe the standard output
+ of @command{tar} through @command{ecc}, but then I lose (though I
+ haven't started using it yet, I confess) the ability to have
+ @command{tar} use @command{rmt} for it's I/O (I think).
+
+ I think the most straightforward thing would be to let me specify a
+ general set of filters outboard of compression (preferably ordered,
+ so the order can be automatically reversed on input operations, and
+ with the options they require specifiable), but beggars shouldn't be
+ choosers and anything you decide on would be fine with me.
+
+ By the way, I like @command{ecc} but if (as the comments say) it can't
+ deal with loss of block sync, I'm tempted to throw some time at adding
+ that capability. Supposing I were to actually do such a thing and
+ get it (apparently) working, do you accept contributed changes to
+ utilities like that? (Leigh Clayton @file{loc@@soliton.com}, May 1995).
+
+ Isn't that exactly the role of the
+ @address@hidden option?
+ I never tried it myself, but I suspect you may want to write a
+ @var{prog} script or program able to filter stdin to stdout to
+ way you want. It should recognize the @option{-d} option, for when
+ extraction is needed rather than creation.
+
+ It has been reported that if one writes compressed data (through the
+ @option{--gzip} or @option{--compress} options) to a DLT and tries to use
+ the DLT compression mode, the data will actually get bigger and one will
+ end up with less space on the tape.
address@hidden ignore
+
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 technical note:
+
+Programs like @command{dump} do not have to read the entire file; by
+examining the file system directly, they can determine in advance
+exactly where the holes are and thus avoid reading through them. The
+only data it need read are the actual allocated data blocks.
address@hidden uses a more portable and straightforward
+archiving approach, it would be fairly difficult that it does
+otherwise. Elizabeth Zwicky writes to @file{comp.unix.internals}, on
+1990-12-10:
+
address@hidden
+What I did say is that you cannot tell the difference between a hole and an
+equivalent number of nulls without reading raw blocks. @code{st_blocks} at
+best tells you how many holes there are; it doesn't tell you @emph{where}.
+Just as programs may, conceivably, care what @code{st_blocks} is (care
+to name one that does?), they may also care where the holes are (I have
+no examples of this one either, but it's equally imaginable).
+
+I conclude from this that good archivers are not portable. One can
+arguably conclude that if you want a portable program, you can in good
+conscience restore files with as many holes as possible, since you can't
+get it right.
address@hidden quotation
+}
+
address@hidden sparse formats, defined
+When using @samp{POSIX} archive format, @GNUTAR{} 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
+
+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 for fine tuning permissions and ownership.
+This is not the good way, I think. @GNUTAR{} is
+already crowded with options and moreover, the approach just explained
+gives you a great deal of control already.
+
address@hidden, short description}
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 do not see the purpose of such an option. (Neither I. FP.)
+Neither do I. --Sergey}
+
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 GNU extensions (incremental backups, multi-volume
+archives and archive labels) in GNU and PAX formats.}
+
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 @GNUTAR{} format
+
address@hidden GNU archive format
address@hidden Old GNU archive format
address@hidden 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, @GNUTAR{} 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 @GNUTAR{} archive, use option
address@hidden
+
address@hidden posix
address@hidden @GNUTAR{} and @acronym{POSIX} @command{tar}
+
address@hidden POSIX archive format
address@hidden PAX archive format
+Starting from version 1.14 @GNUTAR{} 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 and containing non-ASCII file names, that
+is, file names having characters with the eight bit set, because they
+use signed checksums, while @GNUTAR{} uses unsigned
+checksums while creating archives, as per @acronym{POSIX} standards. On
+reading, @GNUTAR{} computes both checksums and
+accept any. It is somewhat worrying that a lot of people may go
+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 compute checksums both ways, and accept
+any on read, so @acronym{GNU} tar can read Sun tapes even with their
+wrong checksums. @GNUTAR{} produces the standard
+checksum, however, raising incompatibilities with Sun. That is to
+say, @GNUTAR{} 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
+
+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, @GNUTAR{} 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 @GNUTAR{} implementation. Moreover, they sometimes
+cannot be correctly restored on another hosts even by @GNUTAR{}. 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 how @acronym{POSIX} archives are extracted by non
+POSIX-aware tars.}
+
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 Of course your best bet is to have @GNUTAR{} 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, @GNUTAR{}
+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, @GNUTAR{}
+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 @GNUTAR{}'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 the following material}
+
+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}, @GNUTAR{}, 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
+
+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 @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, @GNUTAR{} 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 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, 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, 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, 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, short description}
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 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, @GNUTAR{} 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 @GNUTAR{},
+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 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 PUBLISH
+
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 ifclear
+
address@hidden Blocking
address@hidden Blocking
address@hidden
+
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 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 @GNUTAR{}.
+
+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 @GNUTAR{}.
+
+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. @GNUTAR{}, 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
+
+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 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 example of using a cartridge with blocking factor=126 or more.}
+
+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 @GNUTAR{}, 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 @GNUTAR{}
+requires an explicit specification for the block size,
+which it cannot guess. This yields some people to consider
address@hidden 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 @GNUTAR{} 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, 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, 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 options should be moved here from elsewhere.}
+
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 options should be moved here from elsewhere.}
+
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
+
+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 it true that this only works on non-block devices?
+should explain the difference, (fixed or variable).}
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 isn't there an "advance 'til you find two tape marks
+together"?}
+
+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 there any use for record operations?}
+
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 there a better way to frob the spacing on the list?}
+
+If you don't specify a @var{tapename}, @command{mt} uses the environment
+variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
+the default device specified in your @file{sys/mtio.h} file
+(@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, @GNUTAR{} 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 @GNUTAR{} 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 @GNUTAR{} 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 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 @GNUTAR{} 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 @GNUTAR{} 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 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 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 @GNUTAR{} 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 @GNUTAR{}. 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
+
+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 @GNUTAR{} 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. @GNUTAR{} 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 script is not installed. Should we install it?}
+
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 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 @GNUTAR{} initially attempted to write it,
+often soon after the operator launches @command{tar} or types the
+carriage return telling that the next tape is ready. Comparing date
+labels does give an idea of tape throughput only if the delays for
+rewinding tapes and the operator switching them were negligible, which
+is usually not the case.
+
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, using with @option{--create}}
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 @GNUTAR{} @value{VERSION} 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 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 @GNUTAR{}.
+
address@hidden Use of short option @option{-o}.
+
+Earlier versions of @GNUTAR{} understood @option{-o} command line
+option as a synonym for @option{--old-archive}.
+
address@hidden 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 the first argument to tar-formats when the new Automake is
+out. The proposition to add @anchor{} to the appropriate place of its
+docs was accepted by Automake people --Sergey 2006-05-25}.
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 @GNUTAR{} will understand @option{-o} only as a
+synonym for @option{--no-same-owner}.
+
address@hidden Use of short option @option{-l}
+
+Earlier versions of @GNUTAR{} understood @option{-l} option as a
+synonym for @option{--one-file-system}. Since such usage contradicted
+to UNIX98 specification and harmed compatibility with other
+implementation, it was declared deprecated in version 1.14. However,
+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 intern.texi
+
address@hidden Genfile
address@hidden Genfile
address@hidden genfile.texi
+
address@hidden Free Software Needs Free Documentation
address@hidden Free Software Needs Free Documentation
address@hidden freemanuals.texi
+
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 fdl.texi
+
address@hidden Index of Command Line Options
address@hidden Index of Command Line Options
+
+This appendix contains an index of all @GNUTAR{} 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
+
address@hidden Local variables:
address@hidden texinfo-column-for-description: 32
address@hidden End:
Index: Tests/tar_texi/value.texi
===================================================================
RCS file: Tests/tar_texi/value.texi
diff -N Tests/tar_texi/value.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/value.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,22 @@
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
+
+
Index: Tests/tar_texi/version.texi
===================================================================
RCS file: Tests/tar_texi/version.texi
diff -N Tests/tar_texi/version.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Tests/tar_texi/version.texi 6 Aug 2006 21:12:37 -0000 1.1
@@ -0,0 +1,4 @@
address@hidden UPDATED 26 June 2006
address@hidden UPDATED-MONTH June 2006
address@hidden EDITION 1.15.92
address@hidden VERSION 1.15.92