texi2html-cvs
[Top][All Lists]
Advanced

[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 &copy; 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 &ldquo;A GNU 
Manual,&rdquo;
+and with the Back-Cover Texts as in (a) below.  A copy of the license
+is included in the section entitled &quot;GNU Free Documentation License&quot;.
+</p>
+<p>(a) The FSF's Back-Cover Text is: &ldquo;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.&rdquo;
+</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC113">7. Date input 
formats</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC161">B. Configuring Help 
Summary</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC162">C. Tar 
Internals</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC171">D. 
Genfile</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC176">F. Copying This 
Manual</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC180">H. 
Index</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" 
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC3">1.2 Some 
Definitions</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" 
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC10">2.2 Stylistic 
Conventions</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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 
&lsquo;<samp>--file</samp>&rsquo; Option</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC15">The 
&lsquo;<samp>--verbose</samp>&rsquo; Option</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC16">Getting Help: Using the 
&lsquo;<samp>--help</samp>&rsquo; Option</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC20">2.6.3 Running 
&lsquo;<samp>--create</samp>&rsquo; with 
&lsquo;<samp>--verbose</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC21">2.6.4 Short Forms with 
&lsquo;<samp>create</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC60">4.3 Options Used by 
&lsquo;<samp>--create</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC63">4.4 Options Used by 
&lsquo;<samp>--extract</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC83">4.5 Backup 
options</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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: 
&lsquo;<samp>--append</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC57">4.2.4 Combining Archives 
with &lsquo;<samp>--concatenate</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC58">4.2.5 Removing Archive 
Members Using 
&lsquo;<samp>--delete</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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: &lsquo;<samp>--append</samp>&rsquo;
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC53">4.2.2.1 
Appending Files to an Archive</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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 
&lsquo;<samp>--update</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Options Used by &lsquo;<samp>--create</samp>&rsquo;
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC61">4.3.1 
Overriding File Metadata</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
+Options Used by &lsquo;<samp>--extract</samp>&rsquo;
+
+</pre></th></tr><tr><td align="left" valign="top"><a href="#SEC64">4.4.1 
Options to Help Read Archives</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC66">Ignoring Blocks of 
Zeros</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC69">Overwrite Old 
Files</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC70">Keep Old 
Files</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC71">Keep Newer 
Files</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC72">Unlink 
First</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC73">Recursive 
Unlink</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC74">Setting Data Modification 
Times</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC75">Setting Access 
Permissions</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" 
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC77">Writing to Standard 
Output</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC79">Removing 
Files</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC82">Same 
Order</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC94">5.4.4 An Example Text of 
&lsquo;<tt>Backup-specs</tt>&rsquo;</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">     
TZ=&quot;America/New_York&quot;, TZ=&quot;UTC0&quot;.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC123">7.10 Authors of 
<code>get_date</code></a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC147">9.4 
Blocking</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC159">9.9 Write 
Protection</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" 
valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC165">Storing Sparse 
Files</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a 
href="#SEC170">Dumpdir</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC2" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[ &lt;&lt; ]</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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &ldquo;tar&rdquo; originally came from the phrase &ldquo;Tape 
ARchive&rdquo;, 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>&nbsp;&nbsp;</td><td align="left" valign="top"></td></tr>
+<tr><td align="left" valign="top"><a href="#SEC3">1.2 Some 
Definitions</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC3" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 (&lsquo;<samp>create</samp>&rsquo;, 
&lsquo;<samp>list</samp>&rsquo;, and &lsquo;<samp>extract</samp>&rsquo;) as 
well as
+two frequently used options (&lsquo;<samp>file</samp>&rsquo; and 
&lsquo;<samp>verbose</samp>&rsquo;).  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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC4" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &ldquo;printing&rdquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC5" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC6" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<samp>.tar</samp>&rsquo;.  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 &ldquo;<code>tar</code> 
files,&rdquo; and
+archive members as &ldquo;files&rdquo; or &ldquo;entries&rdquo;.  For people 
familiar with
+the operation of <code>tar</code>, this causes no difficulty.  However, in
+this manual, we consistently refer to &ldquo;archives&rdquo; and &ldquo;archive
+members&rdquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC7" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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&ccedil;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 
&lsquo;<tt>THANKS</tt>&rsquo;
+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&ccedil;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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>address@hidden</tt>&rsquo;.
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC9" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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: &lsquo;<samp>--create</samp>&rsquo;, 
&lsquo;<samp>--list</samp>&rsquo;, and &lsquo;<samp>--extract</samp>&rsquo;.  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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC10">2.2 Stylistic 
Conventions</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC10" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &ldquo;archive&rdquo; and &ldquo;archive member&rdquo; 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 &ldquo;argument&rdquo; 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 
&lsquo;<tt>/home/fsf/melissa</tt>&rsquo;.  All of
+my examples are in a subdirectory of the directory named by that path
+name; the subdirectory is called &lsquo;<tt>practice</tt>&rsquo;.
+
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC11" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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, &lsquo;<samp>$</samp>&rsquo; 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 &lsquo;<samp>like this</samp>&rsquo;.
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC12" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&ldquo;required&rdquo;.  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 &ldquo;old&rdquo; 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 &ldquo;old style&rdquo; 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 &ldquo;short&rdquo; forms produce
+the same result and can make typing long <code>tar</code> commands easier.
+For example, instead of typing
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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>&nbsp;</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, &ldquo;option&rdquo;, can be confusing at times, since 
&ldquo;operations&rdquo;
+are often lumped in with the actual, <em>optional</em> &ldquo;options&rdquo; 
in certain
+general class statements.  For example, we just talked about &ldquo;short and
+long forms of options and operations&rdquo;.  However, experienced 
<code>tar</code>
+users often refer to these by shorthand terms such as, &ldquo;short and long
+options&rdquo;.  This term assumes that the &ldquo;operations&rdquo; are 
included, also.
+Context will help you determine which definition of &ldquo;options&rdquo; to 
use.
+</p>
+<p>Similarly, the term &ldquo;command&rdquo; can be confusing, as it is often 
used in
+two different ways.  People sometimes refer to <code>tar</code> 
&ldquo;commands&rdquo;.
+A <code>tar</code> <em>command</em> is the entire command line of user input
+which tells <code>tar</code> what to do &mdash; including the operation, 
options,
+and any arguments (file names, pipes, other commands, etc).  However,
+you will also sometimes hear the term &ldquo;the <code>tar</code> 
command&rdquo;.  When
+the word &ldquo;command&rdquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC13" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--create</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-c</samp>&rsquo;</dt>
+<dd><p>Create a new <code>tar</code> archive.
+</p></dd>
+<dt> &lsquo;<samp>--list</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-t</samp>&rsquo;</dt>
+<dd><p>List the contents of an archive.
+</p></dd>
+<dt> &lsquo;<samp>--extract</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-x</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC14" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>: &lsquo;<samp>--file</samp>&rsquo; (which takes an archive 
file as an argument)
+and &lsquo;<samp>--verbose</samp>&rsquo;.  (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 
&lsquo;<samp>--file</samp>&rsquo; Option</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC15">The 
&lsquo;<samp>--verbose</samp>&rsquo; Option</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC16">Getting Help: Using the 
&lsquo;<samp>--help</samp>&rsquo; Option</a></td><td>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC15" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--file</samp>&rsquo; Option 
</h3>
+
+<dl compact="compact">
+<dd><a name="IDX12"></a>
+</dd>
+<dt> &lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-f <var>archive-name</var></samp>&rsquo;</dt>
+<dd><p>Specify the name of an archive file.
+</p></dd>
+</dl>
+
+<p>You can specify an argument for the 
&lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo; (&lsquo;<samp>-f 
<var>archive-name</var></samp>&rsquo;) 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>&nbsp;</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 &lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo; 
(&lsquo;<samp>-f <var>archive-name</var></samp>&rsquo;) when writing your 
<code>tar</code> commands.
+For more information on using the 
&lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo; (&lsquo;<samp>-f 
<var>archive-name</var></samp>&rsquo;) 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC16" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--verbose</samp>&rsquo; Option 
</h3>
+
+<dl compact="compact">
+<dd><a name="IDX14"></a>
+</dd>
+<dt> &lsquo;<samp>--verbose</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-v</samp>&rsquo;</dt>
+<dd><p>Show the files being worked on as <code>tar</code> is running.
+</p></dd>
+</dl>
+
+<p>&lsquo;<samp>--verbose</samp>&rsquo; (&lsquo;<samp>-v</samp>&rsquo;) 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 
&lsquo;<samp>--verbose</samp>&rsquo;
+option.  In the beginning, you may find it useful to use
+&lsquo;<samp>--verbose</samp>&rsquo; 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 &lsquo;<samp>--verbose</samp>&rsquo; at times to help 
make something
+clear, and we will give many examples both using and not using
+&lsquo;<samp>--verbose</samp>&rsquo; to show the differences.
+</p>
+<p>Each instance of &lsquo;<samp>--verbose</samp>&rsquo; 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 (&lsquo;<samp>--list</samp>&rsquo;, 
&lsquo;<samp>--extract</samp>&rsquo;,
+&lsquo;<samp>--diff</samp>&rsquo;), <code>tar</code> by default prints only 
the names of
+the members being extracted.  Using &lsquo;<samp>--verbose</samp>&rsquo; will 
show a full,
+<code>ls</code> style member listing.
+</p>
+<p>In contrast, when writing archives (&lsquo;<samp>--create</samp>&rsquo;, 
&lsquo;<samp>--append</samp>&rsquo;,
+&lsquo;<samp>--update</samp>&rsquo;), <code>tar</code> does not print file 
names by
+default.  So, a single &lsquo;<samp>--verbose</samp>&rsquo; option shows the 
file names
+being added to the archive, while two &lsquo;<samp>--verbose</samp>&rsquo; 
options
+enable the full listing.
+</p>   
+<p>For example, to create an archive in verbose mode:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar --create 
--verbose --verbose &hellip;</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 &lsquo;<samp>--verbose
+--verbose</samp>&rsquo;.
+</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 
&lsquo;<samp>v7</samp>&rsquo; 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> &lsquo;<samp>-&gt; <var>link-name</var></samp>&rsquo;</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> &lsquo;<samp>link to <var>link-name</var></samp>&rsquo;</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> &lsquo;<samp>--Long Link--</samp>&rsquo;</dt>
+<dd><p>The archive member is an old GNU format long link.  You will normally
+not encounter this.
+</p>
+</dd>
+<dt> &lsquo;<samp>--Long Name--</samp>&rsquo;</dt>
+<dd><p>The archive member is an old GNU format long name.  You will normally
+not encounter this.
+</p>
+</dd>
+<dt> &lsquo;<samp>--Volume Header--</samp>&rsquo;</dt>
+<dd><p>The archive member is a GNU <em>volume header</em> (see section <a 
href="#SEC155">Tape Files</a>).
+</p>
+</dd>
+<dt> &lsquo;<samp>--Continued at byte <var>n</var>--</samp>&rsquo;</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> &lsquo;<samp>--Mangled file names--</samp>&rsquo;</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>  &lsquo;<samp>unknown file type <var>c</var></samp>&rsquo;</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>&nbsp;</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 -&gt; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC17" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--help</samp>&rsquo; Option </h3>
+
+<dl compact="compact">
+<dd><a name="IDX15"></a>
+</dd>
+<dt> &lsquo;<samp>--help</samp>&rsquo;</dt>
+<dd>
+<p>The &lsquo;<samp>--help</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC18" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--create</samp>&rsquo; (&lsquo;<samp>-c</samp>&rsquo;), which
+you use to create a <code>tar</code> archive.  We will explain
+&lsquo;<samp>--create</samp>&rsquo; 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
+&lsquo;<tt>blues</tt>&rsquo;, &lsquo;<tt>folk</tt>&rsquo;, and 
&lsquo;<tt>jazz</tt>&rsquo;.  The archive is called
+&lsquo;<tt>collection.tar</tt>&rsquo;.
+</p>
+<p>This section will proceed slowly, detailing how to use 
&lsquo;<samp>--create</samp>&rsquo;
+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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC20">2.6.3 Running 
&lsquo;<samp>--create</samp>&rsquo; with 
&lsquo;<samp>--verbose</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC21">2.6.4 Short Forms with 
&lsquo;<samp>create</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC19" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>practice</tt>&rsquo; containing files called 
&lsquo;<tt>blues</tt>&rsquo;, &lsquo;<tt>folk</tt>&rsquo;
+and &lsquo;<tt>jazz</tt>&rsquo;.  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 
&lsquo;<tt>practice</tt>&rsquo;
+is a subdirectory of your home directory.
+</p>
+<p>Now <code>cd</code> to the directory named &lsquo;<tt>practice</tt>&rsquo;; 
&lsquo;<tt>practice</tt>&rsquo;
+is now your <em>working directory</em>.  (<em>Please note</em>: Although
+the full path name of this directory is
+&lsquo;<tt>/<var>homedir</var>/practice</tt>&rsquo;, in our examples we will 
refer to
+this directory as &lsquo;<tt>practice</tt>&rsquo;; 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,
+&lsquo;<samp>collection.tar</samp>&rsquo;), or that you don't care about its 
contents.
+Whenever you use &lsquo;<samp>create</samp>&rsquo;, <code>tar</code> will 
erase the current
+contents of the file named by 
&lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo; (&lsquo;<samp>-f 
<var>archive-name</var></samp>&rsquo;) 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 
&lsquo;<samp>--append</samp>&rsquo; (&lsquo;<samp>-r</samp>&rsquo;); see
+<a href="#SEC52">How to Add Files to Existing Archives: 
&lsquo;<samp>--append</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC20" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>blues</tt>&rsquo;, 
&lsquo;<tt>folk</tt>&rsquo;, and &lsquo;<tt>jazz</tt>&rsquo; into an
+archive named &lsquo;<tt>collection.tar</tt>&rsquo;, use the following command:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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
+&lsquo;<samp>--file=collection.tar</samp>&rsquo; 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 
&lsquo;<samp>create</samp>&rsquo;</a>, for more information on this.
+</p>
+<p>In this example, you type the command as shown above: 
&lsquo;<samp>--create</samp>&rsquo;
+is the operation which creates the new archive
+(&lsquo;<tt>collection.tar</tt>&rsquo;), and &lsquo;<samp>--file</samp>&rsquo; 
is the option which lets
+you give it the name you chose.  The files, &lsquo;<tt>blues</tt>&rsquo;, 
&lsquo;<tt>folk</tt>&rsquo;,
+and &lsquo;<tt>jazz</tt>&rsquo;, are now members of the archive, 
&lsquo;<tt>collection.tar</tt>&rsquo;
+(they are <em>file name arguments</em> to the 
&lsquo;<samp>--create</samp>&rsquo; 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>&nbsp;</td><td><pre class="smallexample">blues   folk   jazz   
collection.tar
+</pre></td></tr></table>
+
+<p>Creating the archive &lsquo;<samp>collection.tar</samp>&rsquo; 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 &lsquo;<samp>--create</samp>&rsquo; 
(&lsquo;<samp>-c</samp>&rsquo;) to add files to
+an existing archive; it will delete the archive and write a new one.
+Use &lsquo;<samp>--append</samp>&rsquo; (&lsquo;<samp>-r</samp>&rsquo;) 
instead.  See section <a href="#SEC52">How to Add Files to Existing Archives: 
&lsquo;<samp>--append</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC21" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--create</samp>&rsquo; with 
&lsquo;<samp>--verbose</samp>&rsquo; </h3>
+
+<p>If you include the &lsquo;<samp>--verbose</samp>&rsquo; 
(&lsquo;<samp>-v</samp>&rsquo;) 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>&nbsp;</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
+&lsquo;<samp>--verbose</samp>&rsquo;, 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC22" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>create</samp>&rsquo; </h3>
+
+<p>As we said before, the &lsquo;<samp>--create</samp>&rsquo; 
(&lsquo;<samp>-c</samp>&rsquo;) 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 &ldquo;short&rdquo;)
+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 &lsquo;<samp>--verbose</samp>&rsquo; 
(&lsquo;<samp>-v</samp>&rsquo;) option) looks like
+using short option forms:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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 
&lsquo;<tt>v</tt>&rsquo;,
+containing the files &lsquo;<tt>blues</tt>&rsquo;, 
&lsquo;<tt>folk</tt>&rsquo;, and &lsquo;<tt>jazz</tt>&rsquo;, because
+the &lsquo;<samp>v</samp>&rsquo; is the closest &ldquo;file name&rdquo; to the 
&lsquo;<samp>-f</samp>&rsquo; option, and
+is thus taken to be the chosen archive file name.  <code>tar</code> will try
+to add a file called &lsquo;<tt>collection.tar</tt>&rsquo; to the 
&lsquo;<tt>v</tt>&rsquo; archive file;
+if the file &lsquo;<tt>collection.tar</tt>&rsquo; did not already exist, 
<code>tar</code> will
+report an error indicating that this file does not exist.  If the file
+&lsquo;<tt>collection.tar</tt>&rsquo; 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 &lsquo;<samp>-v</samp>&rsquo; option did not get registered, 
<code>tar</code> will not
+run under &lsquo;<samp>verbose</samp>&rsquo; 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>&nbsp;</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>&nbsp;</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 &lsquo;<samp>-f</samp>&rsquo;, 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC23" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</td><td><pre class="smallexample">$ <kbd>cd ..</kbd>
+$
+</pre></td></tr></table>
+
+<p>This will put you into the directory which contains 
&lsquo;<tt>practice</tt>&rsquo;,
+i.e., your home directory.  Once in the superior directory, you can
+specify the subdirectory, &lsquo;<tt>practice</tt>&rsquo;, as a file name 
argument.  To
+store &lsquo;<tt>practice</tt>&rsquo; in the new archive file 
&lsquo;<tt>music.tar</tt>&rsquo;, type:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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
+&lsquo;<tt>practice</tt>&rsquo;, but rather in the current working 
directory&mdash;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 &lsquo;<tt>collection.tar</tt>&rsquo;, 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 &lsquo;<tt>music.tar</tt>&rsquo; is
+extracted, the archive file &lsquo;<tt>collection.tar</tt>&rsquo; will be 
re-written
+into the file system).
+</p>
+<p>If you give <code>tar</code> a command such as
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar --create 
--file=foo.tar .</kbd>
+</pre></td></tr></table>
+
+<p><code>tar</code> will report &lsquo;<samp>tar: ./foo.tar is the archive; not
+dumped</samp>&rsquo;.  This happens because <code>tar</code> creates the 
archive
+&lsquo;<tt>foo.tar</tt>&rsquo; in the current directory before putting any 
files into
+it.  Then, when <code>tar</code> attempts to add all the files in the
+directory &lsquo;<tt>.</tt>&rsquo; to the archive, it notices that the file
+&lsquo;<tt>./foo.tar</tt>&rsquo; is the same as the archive 
&lsquo;<tt>foo.tar</tt>&rsquo;, 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC24" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--list</samp>&rsquo;
+(&lsquo;<samp>-t</samp>&rsquo;) 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
+&lsquo;<tt>collection.tar</tt>&rsquo; that you created in the last section 
with the
+command, 
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</td><td><pre class="smallexample">blues
+folk
+jazz
+</pre></td></tr></table>
+
+<p>The archive &lsquo;<tt>bfiles.tar</tt>&rsquo; would list as follows:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">./birds
+baboon
+./box
+</pre></td></tr></table>
+
+<p>Be sure to use a &lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo; 
(&lsquo;<samp>-f
+<var>archive-name</var></samp>&rsquo;) option just as with 
&lsquo;<samp>--create</samp>&rsquo;
+(&lsquo;<samp>-c</samp>&rsquo;) to specify the name of the archive.
+</p>
+<a name="IDX18"></a>
+<a name="IDX19"></a>
+<p>If you use the &lsquo;<samp>--verbose</samp>&rsquo; 
(&lsquo;<samp>-v</samp>&rsquo;) option with
+&lsquo;<samp>--list</samp>&rsquo;, then <code>tar</code> will print out a 
listing
+reminiscent of &lsquo;<samp>ls -l</samp>&rsquo;, 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 &lsquo;<samp>--verbose</samp>&rsquo; 
(&lsquo;<samp>-v</samp>&rsquo;) mode, the example
+above would look like:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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
+&lsquo;<samp>--show-stored-names</samp>&rsquo; option.
+</p>
+<dl compact="compact">
+<dt> &lsquo;<samp>--show-stored-names</samp>&rsquo;</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 &lsquo;<samp>list</samp>&rsquo;.  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 &lsquo;<tt>apple</tt>&rsquo;.
+</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 &lsquo;<samp>tar: birds: Not found in 
archive</samp>&rsquo;,
+because there is no member named &lsquo;<tt>birds</tt>&rsquo;, only one named
+&lsquo;<tt>./birds</tt>&rsquo;.  While the names &lsquo;<tt>birds</tt>&rsquo; 
and &lsquo;<tt>./birds</tt>&rsquo; 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 &lsquo;<tt>baboon</tt>&rsquo;, because this exact member name is in the 
archive file
+&lsquo;<tt>bfiles.tar</tt>&rsquo;.  If you are not sure of the exact file name,
+use <em>globbing patterns</em>, for example:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>b</samp>&rsquo;.  
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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC25" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<samp>--list</samp>&rsquo; (&lsquo;<samp>-t</samp>&rsquo;).  To find 
out file attributes, include the
+&lsquo;<samp>--verbose</samp>&rsquo; (&lsquo;<samp>-v</samp>&rsquo;) option.
+</p>
+<p>For example, to find out about files in the directory 
&lsquo;<tt>practice</tt>&rsquo;, in
+the archive file &lsquo;<tt>music.tar</tt>&rsquo;, type:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC26" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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&mdash;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 &lsquo;<samp>--extract</samp>&rsquo; 
(&lsquo;<samp>--get</samp>&rsquo; or
+&lsquo;<samp>-x</samp>&rsquo;) operation.  As with 
&lsquo;<samp>--create</samp>&rsquo;, specify the name
+of the archive with &lsquo;<samp>--file</samp>&rsquo; 
(&lsquo;<samp>-f</samp>&rsquo;) 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 &lsquo;<samp>--extract</samp>&rsquo;, you can extract an entire 
archive, or specific
+files.  The files can be directories containing other files, or not.  As
+with &lsquo;<samp>--create</samp>&rsquo; (&lsquo;<samp>-c</samp>&rsquo;) and 
&lsquo;<samp>--list</samp>&rsquo; (&lsquo;<samp>-t</samp>&rsquo;), 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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC27" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar -xvf 
collection.tar</kbd>
+</pre></td></tr></table>
+
+<p>produces this:
+</p>
+<table><tr><td>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC28" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;).  If you had
+mistakenly deleted one of the files you had placed in the archive
+&lsquo;<tt>collection.tar</tt>&rsquo; earlier (say, 
&lsquo;<tt>blues</tt>&rsquo;), you can extract it
+from the archive without changing the archive's structure.  Its
+contents will be identical to the original file &lsquo;<tt>blues</tt>&rsquo; 
that you
+deleted. 
+</p>
+<p>First, make sure you are in the &lsquo;<tt>practice</tt>&rsquo; directory, 
and list the
+files in the directory.  Now, delete the file, 
&lsquo;<samp>blues</samp>&rsquo;, and list
+the files in the directory again.
+</p>
+<p>You can now extract the member &lsquo;<tt>blues</tt>&rsquo; from the 
archive file
+&lsquo;<tt>collection.tar</tt>&rsquo; like this:
+</p>
+<table><tr><td>&nbsp;</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
+&lsquo;<tt>blues</tt>&rsquo; 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, &lsquo;<samp>collection.tar</samp>&rsquo;, is the same as it was 
before you
+extracted &lsquo;<samp>blues</samp>&rsquo;.  You can confirm this by running 
<code>tar</code> with
+&lsquo;<samp>--list</samp>&rsquo; (&lsquo;<samp>-t</samp>&rsquo;).
+</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 &lsquo;<tt>birds</tt>&rsquo;.  To 
extract
+the member named &lsquo;<tt>./birds</tt>&rsquo;, you must specify <kbd>tar
+--extract --file=bfiles.tar ./birds</kbd>.  If you don't remember the
+exact member names, use &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;) 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
+&lsquo;<tt>bfiles.tar</tt>&rsquo; all files that begin with 
&lsquo;<samp>b</samp>&rsquo;, no matter their
+directory prefix, you could type:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar -x -f 
bfiles.tar --wildcards --no-anchored 'b*'</kbd>
+</pre></td></tr></table>
+
+<p>Here, &lsquo;<samp>--wildcards</samp>&rsquo; instructs <code>tar</code> to 
treat
+command line arguments as globbing patterns and 
&lsquo;<samp>--no-anchored</samp>&rsquo;
+informs it that the patterns apply to member names after any 
&lsquo;<samp>/</samp>&rsquo;
+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 &lsquo;<samp>--to-stdout</samp>&rsquo; 
(&lsquo;<samp>-O</samp>&rsquo;) option (see section <a href="#SEC77">Writing to 
Standard Output</a>).
+</p>
+<p>If you give the &lsquo;<samp>--verbose</samp>&rsquo; option, then 
&lsquo;<samp>--extract</samp>&rsquo;
+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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC29" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--extract</samp>&rsquo; to 
extract a directory
+file with an example.  Change to the &lsquo;<tt>practice</tt>&rsquo; directory 
if you
+weren't there, and remove the files &lsquo;<tt>folk</tt>&rsquo; and 
&lsquo;<tt>jazz</tt>&rsquo;.  Then,
+go back to the parent directory and extract the archive
+&lsquo;<tt>music.tar</tt>&rsquo;.  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
+&lsquo;<tt>music.tar</tt>&rsquo;.  To extract only the files you deleted, use 
the
+following command:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--verbose</samp>&rsquo; 
(&lsquo;<samp>-v</samp>&rsquo;) options, <code>tar</code>
+would have displayed more detail about the extracted files, as shown
+in the example below:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<tt>practice</tt>&rsquo; as 
part of the
+file names of each of the files by archiving the 
&lsquo;<tt>practice</tt>&rsquo;
+directory as &lsquo;<tt>practice</tt>&rsquo;, you must give 
&lsquo;<tt>practice</tt>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC30" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>untrusted.tar</tt>&rsquo; 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>&nbsp;</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 &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;) option, possibly combined
+with &lsquo;<samp>--verbose</samp>&rsquo; (&lsquo;<samp>-v</samp>&rsquo;).
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC31" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</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>&nbsp;</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 &lsquo;<tt>..</tt>&rsquo;, where the archive is located; they were 
in the
+&lsquo;<tt>practice</tt>&rsquo; directory, and their file names reflect this:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC33" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC8" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--help</samp>&rsquo; and
+&lsquo;<samp>--version</samp>&rsquo; (see section <a 
href="#SEC44"><acronym>GNU</acronym> <code>tar</code> documentation</a>), 
&lsquo;<samp>--verbose</samp>&rsquo; (see section <a href="#SEC46">Checking 
<code>tar</code> progress</a>)
+and &lsquo;<samp>--interactive</samp>&rsquo; 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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC34" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</td><td><pre class="smallexample"><kbd>tar 
<var>option</var>&hellip; [<var>name</var>]&hellip;</kbd>
+<kbd>tar <var>letter</var>&hellip; [<var>argument</var>]&hellip; 
[<var>option</var>]&hellip; [<var>name</var>]&hellip;</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 &lsquo;<samp>--compare</samp>&rsquo;
+(&lsquo;<samp>--diff</samp>&rsquo;, &lsquo;<samp>-d</samp>&rsquo;), 
&lsquo;<samp>--delete</samp>&rsquo;, &lsquo;<samp>--extract</samp>&rsquo;
+(&lsquo;<samp>--get</samp>&rsquo;, &lsquo;<samp>-x</samp>&rsquo;), 
&lsquo;<samp>--list</samp>&rsquo; (&lsquo;<samp>-t</samp>&rsquo;) or
+&lsquo;<samp>--update</samp>&rsquo; (&lsquo;<samp>-u</samp>&rsquo;).  When 
naming archive members, you
+must give the exact name of the member in the archive, as it is
+printed by &lsquo;<samp>--list</samp>&rsquo;.  For 
&lsquo;<samp>--append</samp>&rsquo; (&lsquo;<samp>-r</samp>&rsquo;) and
+&lsquo;<samp>--create</samp>&rsquo; (&lsquo;<samp>-c</samp>&rsquo;), 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 
&lsquo;<samp>--absolute-names</samp>&rsquo;
+option).  See section <a href="#SEC112">Absolute File Names</a>, for more 
information about
+&lsquo;<samp>--absolute-names</samp>&rsquo;.
+</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 &lsquo;<tt>/</tt>&rsquo; 
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 
&lsquo;<samp>*</samp>&rsquo;
+or &lsquo;<samp>?</samp>&rsquo;, 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
+&lsquo;<samp>--files-from=<var>file-of-names</var></samp>&rsquo; 
(&lsquo;<samp>-T <var>file-of-names</var></samp>&rsquo;) option.
+</p>
+<p>If you don't use any file name arguments, 
&lsquo;<samp>--append</samp>&rsquo; (&lsquo;<samp>-r</samp>&rsquo;),
+&lsquo;<samp>--delete</samp>&rsquo; and 
&lsquo;<samp>--concatenate</samp>&rsquo; (&lsquo;<samp>--catenate</samp>&rsquo;,
+&lsquo;<samp>-A</samp>&rsquo;) will do nothing, while 
&lsquo;<samp>--create</samp>&rsquo; (&lsquo;<samp>-c</samp>&rsquo;)
+will usually yield a diagnostic and inhibit <code>tar</code> execution.
+The other operations of <code>tar</code> (&lsquo;<samp>--list</samp>&rsquo;,
+&lsquo;<samp>--extract</samp>&rsquo;, &lsquo;<samp>--compare</samp>&rsquo;, 
and &lsquo;<samp>--update</samp>&rsquo;)
+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
+&lsquo;<samp>--compare</samp>&rsquo; &lsquo;<samp>--diff</samp>&rsquo;, 
&lsquo;<samp>-d</samp>&rsquo;) option, zero means
+that everything went well, besides maybe innocuous warnings.  Nonzero
+means that something went wrong. Right now, as of today, &ldquo;nonzero&rdquo;
+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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC35" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--verbose</samp>&rsquo;
+(&lsquo;<samp>-v</samp>&rsquo;), 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 &lsquo;<samp>-v --unlink-first</samp>&rsquo;, 
<code>tar</code> behaves as
+if the two options &lsquo;<samp>-v</samp>&rsquo; and 
&lsquo;<samp>--unlink-first</samp>&rsquo; 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 &lsquo;<samp>-T</samp>&rsquo; and &lsquo;<samp>-t</samp>&rsquo; 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 &lsquo;<samp>--list</samp>&rsquo; (&lsquo;<samp>-t</samp>&rsquo;).
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC36" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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, 
&lsquo;<samp>--file</samp>&rsquo;
+(&lsquo;<samp>-f</samp>&rsquo;)) 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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC37" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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., &lsquo;<samp>--list</samp>&rsquo;.  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 &lsquo;<samp>--compare</samp>&rsquo; and 
&lsquo;<samp>--diff</samp>&rsquo;.  In addition,
+long option names can be given unique abbreviations.  For example,
+&lsquo;<samp>--cre</samp>&rsquo; can be used in place of 
&lsquo;<samp>--create</samp>&rsquo; because there is no
+other long option which begins with &lsquo;<samp>cre</samp>&rsquo;.  (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 &lsquo;<samp>tar 
--help</samp>&rsquo;
+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>&nbsp;</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 &lsquo;<samp>--file</samp>&rsquo; 
option (which
+tells the name of the <code>tar</code> archive) is given a file such as
+&lsquo;<tt>archive.tar</tt>&rsquo; as argument by using any of the following 
notations:
+&lsquo;<samp>--file=archive.tar</samp>&rsquo; or &lsquo;<samp>--file 
archive.tar</samp>&rsquo;.
+</p>
+<p>In contrast, optional arguments must always be introduced using
+an equal sign.  For example, the &lsquo;<samp>--backup</samp>&rsquo; option 
takes
+an optional argument specifying backup type.  It must be used
+as &lsquo;<samp>--backup=<var>backup-type</var></samp>&rsquo;.
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC38" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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., 
&lsquo;<samp>-t</samp>&rsquo;
+(which is equivalent to &lsquo;<samp>--list</samp>&rsquo;).  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 &lsquo;<samp>-f
+archive.tar</samp>&rsquo; or &lsquo;<samp>-farchive.tar</samp>&rsquo; instead 
of using
+&lsquo;<samp>--file=archive.tar</samp>&rsquo;.  Both 
&lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo; and
+&lsquo;<samp>-f <var>archive-name</var></samp>&rsquo; denote the option which 
indicates a
+specific archive, here named &lsquo;<tt>archive.tar</tt>&rsquo;.
+</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., &lsquo;<samp><code>tar</code> -cvf</samp>&rsquo;.  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>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC39" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>t</samp>&rsquo; is
+the same as the short option &lsquo;<samp>-t</samp>&rsquo;, and consequently, 
the same as the
+long option &lsquo;<samp>--list</samp>&rsquo;.  So for example, the command 
&lsquo;<samp>tar
+cv</samp>&rsquo; specifies the option &lsquo;<samp>-v</samp>&rsquo; in 
addition to the operation &lsquo;<samp>-c</samp>&rsquo;.
+</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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar cvbf 20 
/dev/rmt0</kbd>
+</pre></td></tr></table>
+
+<p>Here, &lsquo;<samp>20</samp>&rsquo; is the argument of 
&lsquo;<samp>-b</samp>&rsquo; and &lsquo;<samp>/dev/rmt0</samp>&rsquo; is
+the argument of &lsquo;<samp>-f</samp>&rsquo;.
+</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 &lsquo;<samp>tar cvbf 20 /dev/rmt0</samp>&rsquo;, 
for example,
+&lsquo;<samp>20</samp>&rsquo; is the argument for 
&lsquo;<samp>-b</samp>&rsquo;, &lsquo;<samp>/dev/rmt0</samp>&rsquo; is the
+argument for &lsquo;<samp>-f</samp>&rsquo;, and &lsquo;<samp>-v</samp>&rsquo; 
does not have a corresponding
+argument.  Even using short options like in &lsquo;<samp>tar -c -v -b 20 -f
+/dev/rmt0</samp>&rsquo; 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>&nbsp;</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 
&lsquo;<tt>archive.tar.gz</tt>&rsquo; as
+the value for option &lsquo;<samp>f</samp>&rsquo; and recognizes the option 
&lsquo;<samp>z</samp>&rsquo;.  The
+second example, however, uses &lsquo;<tt>z</tt>&rsquo; as the value for option
+&lsquo;<samp>f</samp>&rsquo; &mdash; 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>&nbsp;</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 &lsquo;<samp>-</samp>&rsquo;.  Thus, 
&lsquo;<samp>tar c</samp>&rsquo; is
+equivalent to &lsquo;<samp>tar -c</samp>&rsquo;: both of them specify the
+&lsquo;<samp>--create</samp>&rsquo; (&lsquo;<samp>-c</samp>&rsquo;) 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC40" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</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>&nbsp;</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
+&lsquo;<samp>-c</samp>&rsquo;, &lsquo;<samp>c</samp>&rsquo;, 
&lsquo;<samp>carchive.tar</samp>&rsquo; or 
&lsquo;<samp>archive.tarc</samp>&rsquo;,
+respectively.  The first two examples also specify a single non-option,
+<var>name</var> argument having the value 
&lsquo;<samp>archive.tar</samp>&rsquo;.  The last
+example contains only old style option letters (repeating option
+&lsquo;<samp>c</samp>&rsquo; twice), not all of which are meaningful (eg., 
&lsquo;<samp>.</samp>&rsquo;,
+&lsquo;<samp>h</samp>&rsquo;, or &lsquo;<samp>i</samp>&rsquo;), 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC41" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC42" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--append</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-r</samp>&rsquo;</dt>
+<dd>
+<p>Appends files to the end of the archive.  See section <a href="#SEC52">How 
to Add Files to Existing Archives: &lsquo;<samp>--append</samp>&rsquo;</a>.
+</p>
+<p><a name="g_t_002d_002dcatenate"></a>
+<a name="IDX33"></a>
+</p></dd>
+<dt> &lsquo;<samp>--catenate</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-A</samp>&rsquo;</dt>
+<dd>
+<p>Same as &lsquo;<samp>--concatenate</samp>&rsquo;.  See section <a 
href="#SEC57">Combining Archives with 
&lsquo;<samp>--concatenate</samp>&rsquo;</a>.
+</p>
+<p><a name="g_t_002d_002dcompare"></a>
+<a name="IDX34"></a>
+</p></dd>
+<dt> &lsquo;<samp>--compare</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-d</samp>&rsquo;</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> &lsquo;<samp>--concatenate</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-A</samp>&rsquo;</dt>
+<dd>
+<p>Appends other <code>tar</code> archives to the end of the archive.
+See section <a href="#SEC57">Combining Archives with 
&lsquo;<samp>--concatenate</samp>&rsquo;</a>.
+</p>
+<p><a name="g_t_002d_002dcreate"></a>
+<a name="IDX36"></a>
+</p></dd>
+<dt> &lsquo;<samp>--create</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-c</samp>&rsquo;</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> &lsquo;<samp>--delete</samp>&rsquo;</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 
&lsquo;<samp>--delete</samp>&rsquo;</a>.
+</p>
+<p><a name="g_t_002d_002ddiff"></a>
+<a name="IDX38"></a>
+</p></dd>
+<dt> &lsquo;<samp>--diff</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-d</samp>&rsquo;</dt>
+<dd>
+<p>Same &lsquo;<samp>--compare</samp>&rsquo;.  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> &lsquo;<samp>--extract</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-x</samp>&rsquo;</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> &lsquo;<samp>--get</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-x</samp>&rsquo;</dt>
+<dd>
+<p>Same as &lsquo;<samp>--extract</samp>&rsquo;.  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> &lsquo;<samp>--list</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-t</samp>&rsquo;</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> &lsquo;<samp>--update</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-u</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC43" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--absolute-names</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-P</samp>&rsquo;</dt>
+<dd>
+<p>Normally when creating an archive, <code>tar</code> strips an initial
+&lsquo;<samp>/</samp>&rsquo; 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> &lsquo;<samp>--after-date</samp>&rsquo;</dt>
+<dd>
+<p>(See &lsquo;<samp>--newer</samp>&rsquo;, 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> &lsquo;<samp>--anchored</samp>&rsquo;</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> &lsquo;<samp>--atime-preserve</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--atime-preserve=replace</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--atime-preserve=system</samp>&rsquo;</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>&lsquo;<samp>--atime-preserve=replace</samp>&rsquo; 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>&lsquo;<samp>--atime-preserve=system</samp>&rsquo; 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
+&lsquo;<samp>--atime-preserve=system</samp>&rsquo; 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 &lsquo;<samp>--atime-preserve</samp>&rsquo; with no operand 
defaults to
+&lsquo;<samp>--atime-preserve=replace</samp>&rsquo;, but this may change in 
the future
+as support for &lsquo;<samp>--atime-preserve=system</samp>&rsquo; improves.
+</p>
+<p>If your operating system does not support
+&lsquo;<samp>--atime-preserve=system</samp>&rsquo;, 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 &lsquo;<samp>noatime</samp>&rsquo; 
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> &lsquo;<samp>--backup=<var>backup-type</var></samp>&rsquo;</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> &lsquo;<samp>--block-number</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-R</samp>&rsquo;</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> &lsquo;<samp>--blocking-factor=<var>blocking</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-b <var>blocking</var></samp>&rsquo;</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> &lsquo;<samp>--bzip2</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-j</samp>&rsquo;</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> &lsquo;<samp>--checkpoint[=<var>number</var>]</samp>&rsquo;</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 &lsquo;<samp>--verbose</samp>&rsquo; 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> &lsquo;<samp>--check-links</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-l</samp>&rsquo;</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> &lsquo;<samp>--compress</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--uncompress</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-Z</samp>&rsquo;</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> &lsquo;<samp>--confirmation</samp>&rsquo;</dt>
+<dd>
+<p>(See &lsquo;<samp>--interactive</samp>&rsquo;.)  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> &lsquo;<samp>--delay-directory-restore</samp>&rsquo;</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> &lsquo;<samp>--dereference</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-h</samp>&rsquo;</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> &lsquo;<samp>--directory=<var>dir</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-C <var>dir</var></samp>&rsquo;</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> &lsquo;<samp>--exclude=<var>pattern</var></samp>&rsquo;</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> &lsquo;<samp>--exclude-from=<var>file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-X <var>file</var></samp>&rsquo;</dt>
+<dd>
+<p>Similar to &lsquo;<samp>--exclude</samp>&rsquo;, 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> &lsquo;<samp>--exclude-caches</samp>&rsquo;</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> &lsquo;<samp>--file=<var>archive</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-f <var>archive</var></samp>&rsquo;</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 &lsquo;<samp>--file</samp>&rsquo; 
Option</a>.
+</p>
+<p><a name="g_t_002d_002dfiles_002dfrom"></a>
+<a name="IDX63"></a>
+</p></dd>
+<dt> &lsquo;<samp>--files-from=<var>file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-T <var>file</var></samp>&rsquo;</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> &lsquo;<samp>--force-local</samp>&rsquo;</dt>
+<dd>
+<p>Forces <code>tar</code> to interpret the filename given to 
&lsquo;<samp>--file</samp>&rsquo;
+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> &lsquo;<samp>--format=<var>format</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-H <var>format</var></samp>&rsquo;</dt>
+<dd>
+<p>Selects output archive format.  <var>Format</var> may be one of the
+following:
+</p>
+<dl compact="compact">
+<dt> &lsquo;<samp>v7</samp>&rsquo;</dt>
+<dd><p>Creates an archive that is compatible with Unix V7 <code>tar</code>.
+</p>
+</dd>
+<dt> &lsquo;<samp>oldgnu</samp>&rsquo;</dt>
+<dd><p>Creates an archive that is compatible with GNU <code>tar</code> version
+1.12 or earlier.
+</p>
+</dd>
+<dt> &lsquo;<samp>gnu</samp>&rsquo;</dt>
+<dd><p>Creates archive in GNU tar 1.13 format.  Basically it is the same as
+&lsquo;<samp>oldgnu</samp>&rsquo; with the only difference in the way it 
handles long
+numeric fields.
+</p>
+</dd>
+<dt> &lsquo;<samp>ustar</samp>&rsquo;</dt>
+<dd><p>Creates a <acronym>POSIX.1-1988</acronym> compatible archive.
+</p>
+</dd>
+<dt> &lsquo;<samp>posix</samp>&rsquo;</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> &lsquo;<samp>--group=<var>group</var></samp>&rsquo;</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 
&lsquo;<samp>--owner=<var>user</var></samp>&rsquo; 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> &lsquo;<samp>--gzip</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--gunzip</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--ungzip</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-z</samp>&rsquo;</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> &lsquo;<samp>--help</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-?</samp>&rsquo;</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> &lsquo;<samp>--ignore-case</samp>&rsquo;</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> &lsquo;<samp>--ignore-command-error</samp>&rsquo;</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> &lsquo;<samp>--ignore-failed-read</samp>&rsquo;</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> &lsquo;<samp>--ignore-zeros</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-i</samp>&rsquo;</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> &lsquo;<samp>--incremental</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-G</samp>&rsquo;</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> &lsquo;<samp>--index-file=<var>file</var></samp>&rsquo;</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> &lsquo;<samp>--info-script=<var>script-file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--new-volume-script=<var>script-file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-F <var>script-file</var></samp>&rsquo;</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> &lsquo;<samp>--interactive</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--confirmation</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-w</samp>&rsquo;</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> &lsquo;<samp>--keep-newer-files</samp>&rsquo;</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> &lsquo;<samp>--keep-old-files</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-k</samp>&rsquo;</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> &lsquo;<samp>--label=<var>name</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-V <var>name</var></samp>&rsquo;</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> 
&lsquo;<samp>--listed-incremental=<var>snapshot-file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-g <var>snapshot-file</var></samp>&rsquo;</dt>
+<dd>
+<p>During a &lsquo;<samp>--create</samp>&rsquo; 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> &lsquo;<samp>--mode=<var>permissions</var></samp>&rsquo;</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> &lsquo;<samp>--mtime=<var>date</var></samp>&rsquo;</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 &lsquo;<samp>/</samp>&rsquo; or 
&lsquo;<samp>.</samp>&rsquo;.  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> &lsquo;<samp>--multi-volume</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-M</samp>&rsquo;</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> &lsquo;<samp>--new-volume-script</samp>&rsquo;</dt>
+<dd>
+<p>(see &ndash;info-script)
+</p>
+<p><a name="g_t_002d_002dseek"></a>
+<a name="IDX88"></a>
+</p></dd>
+<dt> &lsquo;<samp>--seek</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-n</samp>&rsquo;</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> &lsquo;<samp>--newer=<var>date</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--after-date=<var>date</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-N</samp>&rsquo;</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 
&lsquo;<samp>/</samp>&rsquo; or &lsquo;<samp>.</samp>&rsquo;, 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> &lsquo;<samp>--newer-mtime=<var>date</var></samp>&rsquo;</dt>
+<dd>
+<p>Like &lsquo;<samp>--newer</samp>&rsquo;, but add only files whose
+contents have changed (as opposed to just &lsquo;<samp>--newer</samp>&rsquo;, 
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> &lsquo;<samp>--no-anchored</samp>&rsquo;</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> &lsquo;<samp>--no-delay-directory-restore</samp>&rsquo;</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> &lsquo;<samp>--no-ignore-case</samp>&rsquo;</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> &lsquo;<samp>--no-ignore-command-error</samp>&rsquo;</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> &lsquo;<samp>--no-overwrite-dir</samp>&rsquo;</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> &lsquo;<samp>--no-quote-chars=<var>string</var></samp>&rsquo;</dt>
+<dd><p>Remove characters listed in <var>string</var> from the list of quoted
+characters set by the previous &lsquo;<samp>--quote-chars</samp>&rsquo; 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> &lsquo;<samp>--no-recursion</samp>&rsquo;</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> &lsquo;<samp>--no-same-owner</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-o</samp>&rsquo;</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> &lsquo;<samp>--no-same-permissions</samp>&rsquo;</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> &lsquo;<samp>--no-unquote</samp>&rsquo;</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> &lsquo;<samp>--no-wildcards</samp>&rsquo;</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> &lsquo;<samp>--no-wildcards-match-slash</samp>&rsquo;</dt>
+<dd><p>Wildcards do not match &lsquo;<samp>/</samp>&rsquo;.
+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> &lsquo;<samp>--null</samp>&rsquo;</dt>
+<dd>
+<p>When <code>tar</code> is using the &lsquo;<samp>--files-from</samp>&rsquo; 
option, this option
+instructs <code>tar</code> to expect filenames terminated with 
&lsquo;<samp>NUL</samp>&rsquo;, 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> &lsquo;<samp>--numeric-owner</samp>&rsquo;</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> &lsquo;<samp>-o</samp>&rsquo;</dt>
+<dd><p>The function of this option depends on the action <code>tar</code> is
+performing.  When extracting files, &lsquo;<samp>-o</samp>&rsquo; is a synonym 
for
+&lsquo;<samp>--no-same-owner</samp>&rsquo;, 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
+&lsquo;<samp>--old-archive</samp>&rsquo;.  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> &lsquo;<samp>--occurrence[=<var>number</var>]</samp>&rsquo;</dt>
+<dd>
+<p>This option can be used in conjunction with one of the subcommands
+&lsquo;<samp>--delete</samp>&rsquo;, &lsquo;<samp>--diff</samp>&rsquo;, 
&lsquo;<samp>--extract</samp>&rsquo; or
+&lsquo;<samp>--list</samp>&rsquo; when a list of files is given either on the 
command
+line or via &lsquo;<samp>-T</samp>&rsquo; 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>&nbsp;</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 
&lsquo;<tt>filename</tt>&rsquo; from &lsquo;<tt>archive.tar</tt>&rsquo;
+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> &lsquo;<samp>--old-archive</samp>&rsquo;</dt>
+<dd><p>Synonym for &lsquo;<samp>--format=v7</samp>&rsquo;.
+</p>
+<p><a name="g_t_002d_002done_002dfile_002dsystem"></a>
+<a name="IDX107"></a>
+</p></dd>
+<dt> &lsquo;<samp>--one-file-system</samp>&rsquo;</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> &lsquo;<samp>--overwrite</samp>&rsquo;</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> &lsquo;<samp>--overwrite-dir</samp>&rsquo;</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> &lsquo;<samp>--owner=<var>user</var></samp>&rsquo;</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> &lsquo;<samp>--transform=<var>sed-expr</var></samp>&rsquo;</dt>
+<dd>
+<p>Transform file or member names using <code>sed</code> replacement expression
+<var>sed-expr</var>.  For example,
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar cf 
archive.tar --transform 's,^\./,usr/,' .</kbd>
+</pre></td></tr></table>
+
+<p>will add to &lsquo;<tt>archive</tt>&rsquo; files from the current working 
directory,
+replacing initial &lsquo;<samp>./</samp>&rsquo; prefix with 
&lsquo;<samp>usr/</samp>&rsquo;. 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
+&lsquo;<samp>--show-transformed-names</samp>&rsquo; 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> &lsquo;<samp>--quote-chars=<var>string</var></samp>&rsquo;</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> &lsquo;<samp>--quoting-style=<var>style</var></samp>&rsquo;</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> &lsquo;<samp>--pax-option=<var>keyword-list</var></samp>&rsquo;</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> &lsquo;<samp>--portability</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--old-archive</samp>&rsquo;</dt>
+<dd><p>Synonym for &lsquo;<samp>--format=v7</samp>&rsquo;.
+</p>
+<p><a name="g_t_002d_002dposix"></a>
+<a name="IDX116"></a>
+</p></dd>
+<dt> &lsquo;<samp>--posix</samp>&rsquo;</dt>
+<dd><p>Same as &lsquo;<samp>--format=posix</samp>&rsquo;.
+</p>
+<p><a name="g_t_002d_002dpreserve"></a>
+<a name="IDX117"></a>
+</p></dd>
+<dt> &lsquo;<samp>--preserve</samp>&rsquo;</dt>
+<dd>
+<p>Synonymous with specifying both 
&lsquo;<samp>--preserve-permissions</samp>&rsquo; and
+&lsquo;<samp>--same-order</samp>&rsquo;.  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> &lsquo;<samp>--preserve-order</samp>&rsquo;</dt>
+<dd>
+<p>(See &lsquo;<samp>--same-order</samp>&rsquo;; 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> &lsquo;<samp>--preserve-permissions</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--same-permissions</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-p</samp>&rsquo;</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> &lsquo;<samp>--read-full-records</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-B</samp>&rsquo;</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> &lsquo;<samp>--record-size=<var>size</var></samp>&rsquo;</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> &lsquo;<samp>--recursion</samp>&rsquo;</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> &lsquo;<samp>--recursive-unlink</samp>&rsquo;</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> &lsquo;<samp>--remove-files</samp>&rsquo;</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> &lsquo;<samp>--restrict</samp>&rsquo;</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> &lsquo;<samp>--rmt-command=<var>cmd</var></samp>&rsquo;</dt>
+<dd>
+<p>Notifies <code>tar</code> that it should use <var>cmd</var> instead of
+the default &lsquo;<tt>/usr/libexec/rmt</tt>&rsquo; (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> &lsquo;<samp>--rsh-command=<var>cmd</var></samp>&rsquo;</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> &lsquo;<samp>--same-order</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--preserve-order</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-s</samp>&rsquo;</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> &lsquo;<samp>--same-owner</samp>&rsquo;</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> &lsquo;<samp>--same-permissions</samp>&rsquo;</dt>
+<dd>
+<p>(See &lsquo;<samp>--preserve-permissions</samp>&rsquo;; 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> &lsquo;<samp>--show-defaults</samp>&rsquo;</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>&nbsp;</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> &lsquo;<samp>--show-omitted-dirs</samp>&rsquo;</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> &lsquo;<samp>--show-transformed-names</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--show-stored-names</samp>&rsquo;</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> &lsquo;<samp>--sparse</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-S</samp>&rsquo;</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> &lsquo;<samp>--sparse-version=<var>version</var></samp>&rsquo;</dt>
+<dd>
+<p>Specified the <em>format version</em> to use when archiving sparse
+files.  Implies &lsquo;<samp>--sparse</samp>&rsquo;.  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> &lsquo;<samp>--starting-file=<var>name</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-K <var>name</var></samp>&rsquo;</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> &lsquo;<samp>--strip-components=<var>number</var></samp>&rsquo;</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 
&lsquo;<tt>archive.tar</tt>&rsquo; contained
+&lsquo;<tt>/some/file/name</tt>&rsquo;, then running
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">tar --extract --file 
archive.tar --strip-components=2
+</pre></td></tr></table>
+
+<p>would extract this file to file &lsquo;<tt>name</tt>&rsquo;.
+</p>
+<p><a name="g_t_002d_002dsuffix"></a>
+<a name="IDX140"></a>
+</p></dd>
+<dt> &lsquo;<samp>--suffix=<var>suffix</var></samp>&rsquo;</dt>
+<dd>
+<p>Alters the suffix <code>tar</code> uses when backing up files from the 
default
+&lsquo;<samp>~</samp>&rsquo;.  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> &lsquo;<samp>--tape-length=<var>num</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-L <var>num</var></samp>&rsquo;</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> &lsquo;<samp>--test-label</samp>&rsquo;</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">&ndash;test-label option</a>.
+</p>
+<p><a name="g_t_002d_002dto_002dcommand"></a>
+<a name="IDX143"></a>
+</p></dd>
+<dt> &lsquo;<samp>--to-command=<var>command</var></samp>&rsquo;</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> &lsquo;<samp>--to-stdout</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-O</samp>&rsquo;</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> &lsquo;<samp>--totals[=<var>signo</var>]</samp>&rsquo;</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> &lsquo;<samp>--touch</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-m</samp>&rsquo;</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> &lsquo;<samp>--uncompress</samp>&rsquo;</dt>
+<dd>
+<p>(See &lsquo;<samp>--compress</samp>&rsquo;. see section <a 
href="#SEC126">Creating and Reading Compressed Archives</a>)
+</p>
+<a name="IDX148"></a>
+</dd>
+<dt> &lsquo;<samp>--ungzip</samp>&rsquo;</dt>
+<dd>
+<p>(See &lsquo;<samp>--gzip</samp>&rsquo;. 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> &lsquo;<samp>--unlink-first</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-U</samp>&rsquo;</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> &lsquo;<samp>--unquote</samp>&rsquo;</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> &lsquo;<samp>--use-compress-program=<var>prog</var></samp>&rsquo;</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> &lsquo;<samp>--utc</samp>&rsquo;</dt>
+<dd>
+<p>Display file modification dates in <acronym>UTC</acronym>.  This option 
implies
+&lsquo;<samp>--verbose</samp>&rsquo;.
+</p>
+<p><a name="g_t_002d_002dverbose"></a>
+<a name="IDX153"></a>
+</p></dd>
+<dt> &lsquo;<samp>--verbose</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-v</samp>&rsquo;</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> &lsquo;<samp>--verify</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-W</samp>&rsquo;</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> &lsquo;<samp>--version</samp>&rsquo;</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> &lsquo;<samp>--volno-file=<var>file</var></samp>&rsquo;</dt>
+<dd>
+<p>Used in conjunction with &lsquo;<samp>--multi-volume</samp>&rsquo;.  
<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> &lsquo;<samp>--wildcards</samp>&rsquo;</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> &lsquo;<samp>--wildcards-match-slash</samp>&rsquo;</dt>
+<dd><p>Wildcards match &lsquo;<samp>/</samp>&rsquo;.
+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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC44" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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">&ndash;concatenate</a>.
+</p>
+</td></tr>
+<tr><td><p> -B </p></td><td><p> <a 
href="#g_t_002d_002dread_002dfull_002drecords">&ndash;read-full-records</a>.
+</p>
+</td></tr>
+<tr><td><p> -C </p></td><td><p> <a 
href="#g_t_002d_002ddirectory">&ndash;directory</a>.
+</p>
+</td></tr>
+<tr><td><p> -F </p></td><td><p> <a 
href="#g_t_002d_002dinfo_002dscript">&ndash;info-script</a>.
+</p>
+</td></tr>
+<tr><td><p> -G </p></td><td><p> <a 
href="#g_t_002d_002dincremental">&ndash;incremental</a>.
+</p>
+</td></tr>
+<tr><td><p> -K </p></td><td><p> <a 
href="#g_t_002d_002dstarting_002dfile">&ndash;starting-file</a>.
+</p>
+</td></tr>
+<tr><td><p> -L </p></td><td><p> <a 
href="#g_t_002d_002dtape_002dlength">&ndash;tape-length</a>.
+</p>
+</td></tr>
+<tr><td><p> -M </p></td><td><p> <a 
href="#g_t_002d_002dmulti_002dvolume">&ndash;multi-volume</a>.
+</p>
+</td></tr>
+<tr><td><p> -N </p></td><td><p> <a href="#g_t_002d_002dnewer">&ndash;newer</a>.
+</p>
+</td></tr>
+<tr><td><p> -O </p></td><td><p> <a 
href="#g_t_002d_002dto_002dstdout">&ndash;to-stdout</a>.
+</p>
+</td></tr>
+<tr><td><p> -P </p></td><td><p> <a 
href="#g_t_002d_002dabsolute_002dnames">&ndash;absolute-names</a>.
+</p>
+</td></tr>
+<tr><td><p> -R </p></td><td><p> <a 
href="#g_t_002d_002dblock_002dnumber">&ndash;block-number</a>.
+</p>
+</td></tr>
+<tr><td><p> -S </p></td><td><p> <a 
href="#g_t_002d_002dsparse">&ndash;sparse</a>.
+</p>
+</td></tr>
+<tr><td><p> -T </p></td><td><p> <a 
href="#g_t_002d_002dfiles_002dfrom">&ndash;files-from</a>.
+</p>
+</td></tr>
+<tr><td><p> -U </p></td><td><p> <a 
href="#g_t_002d_002dunlink_002dfirst">&ndash;unlink-first</a>.
+</p>
+</td></tr>
+<tr><td><p> -V </p></td><td><p> <a href="#g_t_002d_002dlabel">&ndash;label</a>.
+</p>
+</td></tr>
+<tr><td><p> -W </p></td><td><p> <a 
href="#g_t_002d_002dverify">&ndash;verify</a>.
+</p>
+</td></tr>
+<tr><td><p> -X </p></td><td><p> <a 
href="#g_t_002d_002dexclude_002dfrom">&ndash;exclude-from</a>.
+</p>
+</td></tr>
+<tr><td><p> -Z </p></td><td><p> <a 
href="#g_t_002d_002dcompress">&ndash;compress</a>.
+</p>
+</td></tr>
+<tr><td><p> -b </p></td><td><p> <a 
href="#g_t_002d_002dblocking_002dfactor">&ndash;blocking-factor</a>.
+</p>
+</td></tr>
+<tr><td><p> -c </p></td><td><p> <a 
href="#g_t_002d_002dcreate">&ndash;create</a>.
+</p>
+</td></tr>
+<tr><td><p> -d </p></td><td><p> <a 
href="#g_t_002d_002dcompare">&ndash;compare</a>.
+</p>
+</td></tr>
+<tr><td><p> -f </p></td><td><p> <a href="#g_t_002d_002dfile">&ndash;file</a>.
+</p>
+</td></tr>
+<tr><td><p> -g </p></td><td><p> <a 
href="#g_t_002d_002dlisted_002dincremental">&ndash;listed-incremental</a>.
+</p>
+</td></tr>
+<tr><td><p> -h </p></td><td><p> <a 
href="#g_t_002d_002ddereference">&ndash;dereference</a>.
+</p>
+</td></tr>
+<tr><td><p> -i </p></td><td><p> <a 
href="#g_t_002d_002dignore_002dzeros">&ndash;ignore-zeros</a>.
+</p>
+</td></tr>
+<tr><td><p> -j </p></td><td><p> <a href="#g_t_002d_002dbzip2">&ndash;bzip2</a>.
+</p>
+</td></tr>
+<tr><td><p> -k </p></td><td><p> <a 
href="#g_t_002d_002dkeep_002dold_002dfiles">&ndash;keep-old-files</a>.
+</p>
+</td></tr>
+<tr><td><p> -l </p></td><td><p> <a 
href="#g_t_002d_002dcheck_002dlinks">&ndash;check-links</a>.
+</p>
+</td></tr>
+<tr><td><p> -m </p></td><td><p> <a href="#g_t_002d_002dtouch">&ndash;touch</a>.
+</p>
+</td></tr>
+<tr><td><p> -o </p></td><td><p> When creating, <a 
href="#g_t_002d_002dno_002dsame_002downer">&ndash;no-same-owner</a>, when 
extracting &mdash;
+<a href="#g_t_002d_002dportability">&ndash;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
+&lsquo;<samp>-o</samp>&rsquo; will be equivalent to 
&lsquo;<samp>--no-same-owner</samp>&rsquo; only.
+</p>
+</td></tr>
+<tr><td><p> -p </p></td><td><p> <a 
href="#g_t_002d_002dpreserve_002dpermissions">&ndash;preserve-permissions</a>.
+</p>
+</td></tr>
+<tr><td><p> -r </p></td><td><p> <a 
href="#g_t_002d_002dappend">&ndash;append</a>.
+</p>
+</td></tr>
+<tr><td><p> -s </p></td><td><p> <a 
href="#g_t_002d_002dsame_002dorder">&ndash;same-order</a>.
+</p>
+</td></tr>
+<tr><td><p> -t </p></td><td><p> <a href="#g_t_002d_002dlist">&ndash;list</a>.
+</p>
+</td></tr>
+<tr><td><p> -u </p></td><td><p> <a 
href="#g_t_002d_002dupdate">&ndash;update</a>.
+</p>
+</td></tr>
+<tr><td><p> -v </p></td><td><p> <a 
href="#g_t_002d_002dverbose">&ndash;verbose</a>.
+</p>
+</td></tr>
+<tr><td><p> -w </p></td><td><p> <a 
href="#g_t_002d_002dinteractive">&ndash;interactive</a>.
+</p>
+</td></tr>
+<tr><td><p> -x </p></td><td><p> <a 
href="#g_t_002d_002dextract">&ndash;extract</a>.
+</p>
+</td></tr>
+<tr><td><p> -z </p></td><td><p> <a href="#g_t_002d_002dgzip">&ndash;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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC45" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--version</samp>&rsquo; 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, &lsquo;<samp>tar --version</samp>&rsquo; might 
print:
+</p>
+<table><tr><td>&nbsp;</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 &lt;http://www.gnu.org/licenses/gpl.html&gt;.
+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 &lsquo;<samp>tar</samp>&rsquo; in the result above 
is the program
+name in the package (for example, <code>rmt</code> is another program),
+while the second occurrence of &lsquo;<samp>tar</samp>&rsquo; is the name of 
the package
+itself, containing possibly many programs.  The package is currently
+named &lsquo;<samp>tar</samp>&rsquo;, 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
+&lsquo;<samp>--help</samp>&rsquo; 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>&nbsp;</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
+&lsquo;<samp>--help</samp>&rsquo; output, another common idiom is doing:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>make dvi</samp>&rsquo;, then print 
&lsquo;<tt>doc/tar.dvi</tt>&rsquo; 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 &lsquo;<samp>info tar</samp>&rsquo; or, if you do not have the
+<code>info</code> program handy, use the Info reader provided within
+<acronym>GNU</acronym> Emacs, calling &lsquo;<samp>tar</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC46" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--show-defaults</samp>&rsquo; option.  This will 
output the
+values in the form of <code>tar</code> command line options:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>gnu</samp>&rsquo; archive format (see section <a 
href="#SEC124">Controlling the Archive Format</a>), it uses standard
+output as the archive, if no &lsquo;<samp>--file</samp>&rsquo; option has been 
given
+(see section <a href="#SEC14">The &lsquo;<samp>--file</samp>&rsquo; 
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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC47" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;) 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 
&lsquo;<samp>--verbose</samp>&rsquo;
+(&lsquo;<samp>-v</samp>&rsquo;) 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 &lsquo;<samp>--create</samp>&rsquo; or 
&lsquo;<samp>--extract</samp>&rsquo;, &lsquo;<samp>--verbose</samp>&rsquo; 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 &lsquo;<samp>--list</samp>&rsquo; already prints  the names of the 
members,
+&lsquo;<samp>--verbose</samp>&rsquo; used once with 
&lsquo;<samp>--list</samp>&rsquo; causes <code>tar</code>
+to print an &lsquo;<samp>ls -l</samp>&rsquo; type listing of the files in the 
archive.
+The following examples both extract members with long list output:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>tar --create
+--file=- --verbose</samp>&rsquo; (&lsquo;<samp>tar cfv -</samp>&rsquo;, or 
even &lsquo;<samp>tar cv</samp>&rsquo;&mdash;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 &lsquo;<samp>--index-file=<var>file</var></samp>&rsquo; 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 &lsquo;<samp>--totals</samp>&rsquo; 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>&nbsp;</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>&nbsp;</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 
&lsquo;<samp>--totals</samp>&rsquo; option
+displays both numbers plus number of bytes removed from the archive:
+</p>
+<table><tr><td>&nbsp;</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
+&lsquo;<samp>--totals</samp>&rsquo; 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> &lsquo;<samp>--totals=<var>signo</var></samp>&rsquo;</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 &lsquo;<samp>SIG</samp>&rsquo; 
prefix are also
+accepted. 
+</p></dd>
+</dl>
+
+<p>Both forms of &lsquo;<samp>--totals</samp>&rsquo; 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 &lsquo;<samp>--checkpoint</samp>&rsquo; 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
+&lsquo;<samp>--block-number</samp>&rsquo; (&lsquo;<samp>-R</samp>&rsquo;), 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>&nbsp;</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 &lsquo;<samp>.</samp>&rsquo; at each checkpoint.  For 
example:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--show-omitted-dirs</samp>&rsquo; option, when reading an 
archive&mdash;with
+&lsquo;<samp>--list</samp>&rsquo; or &lsquo;<samp>--extract</samp>&rsquo;, for 
example&mdash;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
+&lsquo;<samp>--exclude=<var>pattern</var></samp>&rsquo; option, or some other 
reason.
+</p>
+<a name="IDX170"></a>
+<a name="IDX171"></a>
+<p><a name="block_002dnumber"></a>
+If &lsquo;<samp>--block-number</samp>&rsquo; (&lsquo;<samp>-R</samp>&rsquo;) 
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
+&lsquo;<samp>--block-number</samp>&rsquo; (&lsquo;<samp>-R</samp>&rsquo;) 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
+&lsquo;<samp>--list</samp>&rsquo; (&lsquo;<samp>-t</samp>&rsquo;) 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--interactive</samp>&rsquo; 
(&lsquo;<samp>-w</samp>&rsquo;) option.
+<code>tar</code> also accepts &lsquo;<samp>--confirmation</samp>&rsquo; for 
this option.
+</p>
+<a name="IDX173"></a>
+<p>When the &lsquo;<samp>--interactive</samp>&rsquo; 
(&lsquo;<samp>-w</samp>&rsquo;) 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 &lsquo;<samp>y</samp>&rsquo;.  If your input line begins with 
anything other
+than &lsquo;<samp>y</samp>&rsquo;, <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 &lsquo;<tt>/dev/tty</tt>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC49" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC32" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC60">4.3 Options Used by 
&lsquo;<samp>--create</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC63">4.4 Options Used by 
&lsquo;<samp>--extract</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC83">4.5 Backup 
options</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC50" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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, &lsquo;<samp>--create</samp>&rsquo; 
(&lsquo;<samp>-c</samp>&rsquo;),
+&lsquo;<samp>--list</samp>&rsquo; (&lsquo;<samp>-t</samp>&rsquo;) and 
&lsquo;<samp>--extract</samp>&rsquo; (&lsquo;<samp>--get</samp>&rsquo;,
+&lsquo;<samp>-x</samp>&rsquo;), 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> &lsquo;<samp>--create</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-c</samp>&rsquo;</dt>
+<dd>
+<p>Creating an empty archive would have some kind of elegance.  One can
+initialize an empty archive and later use &lsquo;<samp>--append</samp>&rsquo;
+(&lsquo;<samp>-r</samp>&rsquo;) 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 &lsquo;<samp>--create</samp>&rsquo; 
option is
+given, there are no arguments besides options, and
+&lsquo;<samp>--files-from</samp>&rsquo; (&lsquo;<samp>-T</samp>&rsquo;) 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
+&lsquo;<samp>--files-from</samp>&rsquo; option, a file with no names in it, as 
shown in
+the following commands:
+</p>
+<table><tr><td>&nbsp;</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> &lsquo;<samp>--extract</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--get</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-x</samp>&rsquo;</dt>
+<dd>
+<p>A socket is stored, within a <acronym>GNU</acronym> <code>tar</code> 
archive, as a pipe.
+</p>
+</dd>
+<dt> &lsquo;<samp>&lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;)</samp>&rsquo;</dt>
+<dd>
+<p><acronym>GNU</acronym> <code>tar</code> now shows dates as 
&lsquo;<samp>1996-08-30</samp>&rsquo;,
+while it used to show them as &lsquo;<samp>Aug 30 1996</samp>&rsquo;. 
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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC51" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</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: 
&lsquo;<samp>--append</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC57">4.2.4 Combining Archives 
with &lsquo;<samp>--concatenate</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</td><td 
align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC58">4.2.5 Removing Archive 
Members Using 
&lsquo;<samp>--delete</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC52" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>: &lsquo;<samp>--append</samp>&rsquo;, 
&lsquo;<samp>--update</samp>&rsquo;, &lsquo;<samp>--concatenate</samp>&rsquo;,
+&lsquo;<samp>--delete</samp>&rsquo;, and &lsquo;<samp>--compare</samp>&rsquo;.
+</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
+&lsquo;<tt>practice</tt>&rsquo;, the files are 
&lsquo;<samp>jazz</samp>&rsquo;, &lsquo;<samp>blues</samp>&rsquo;, 
&lsquo;<samp>folk</samp>&rsquo;,
+&lsquo;<samp>rock</samp>&rsquo;, and the two archive files you created are
+&lsquo;<samp>collection.tar</samp>&rsquo; and 
&lsquo;<samp>music.tar</samp>&rsquo;.
+</p>
+<p>We will also use the archive files &lsquo;<samp>afiles.tar</samp>&rsquo; and
+&lsquo;<samp>bfiles.tar</samp>&rsquo;.  The archive 
&lsquo;<samp>afiles.tar</samp>&rsquo; contains the members 
&lsquo;<samp>apple</samp>&rsquo;,
+&lsquo;<samp>angst</samp>&rsquo;, and &lsquo;<samp>aspic</samp>&rsquo;; 
&lsquo;<samp>bfiles.tar</samp>&rsquo; contains the members
+&lsquo;<samp>./birds</samp>&rsquo;, &lsquo;<samp>baboon</samp>&rsquo;, and 
&lsquo;<samp>./box</samp>&rsquo;.
+</p>
+<p>Unless we state otherwise, all practicing you do and examples you follow
+in this chapter will take place in the &lsquo;<tt>practice</tt>&rsquo; 
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> &lsquo;<samp>--append</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-r</samp>&rsquo;</dt>
+<dd><p>Add new entries to an archive that already exists.
+</p></dd>
+<dt> &lsquo;<samp>--update</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-r</samp>&rsquo;</dt>
+<dd><p>Add more recent copies of archive members to the end of an archive, if
+they exist.
+</p></dd>
+<dt> &lsquo;<samp>--concatenate</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--catenate</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-A</samp>&rsquo;</dt>
+<dd><p>Add one or more pre-existing archives to the end of another archive.
+</p></dd>
+<dt> &lsquo;<samp>--delete</samp>&rsquo;</dt>
+<dd><p>Delete items from an archive (does not work on tapes).
+</p></dd>
+<dt> &lsquo;<samp>--compare</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--diff</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-d</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC53" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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: 
&lsquo;<samp>--append</samp>&rsquo; </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 &lsquo;<samp>--append</samp>&rsquo; 
(&lsquo;<samp>-r</samp>&rsquo;).
+The archive must already exist in order to use 
&lsquo;<samp>--append</samp>&rsquo;.  (A
+related operation is the &lsquo;<samp>--update</samp>&rsquo; operation; you 
can use this
+to add newer versions of archive members to an existing archive.  To learn how 
to
+do this with &lsquo;<samp>--update</samp>&rsquo;, see section <a 
href="#SEC55">Updating an Archive</a>.)
+</p>
+<p>If you use &lsquo;<samp>--append</samp>&rsquo; 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 &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;), 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 &lsquo;<samp>--extract</samp>&rsquo; 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
+&lsquo;<samp>--extract</samp>&rsquo; 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 &lsquo;<samp>--occurrence</samp>&rsquo; 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
+&lsquo;<tt>archive.tar</tt>&rsquo; contained three copies of file 
&lsquo;<tt>myfile</tt>&rsquo;, then
+the command
+</p>
+<table><tr><td>&nbsp;</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">&mdash;occurrence</a>, for the description of 
&lsquo;<samp>--occurrence</samp>&rsquo;
+option.
+</p>
+
+
+
+
+<a name="IDX177"></a>
+<a name="IDX178"></a>
+<p>If you want to replace an archive member, use 
&lsquo;<samp>--delete</samp>&rsquo; to
+delete the member you want to remove from the archive, , and then use
+&lsquo;<samp>--append</samp>&rsquo; 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
+&ldquo;replace&rdquo; 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 
&lsquo;<samp>--delete</samp>&rsquo;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC54" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<samp>--append</samp>&rsquo; (&lsquo;<samp>-r</samp>&rsquo;) operation, 
which writes specified
+files into the archive whether or not they are already among the
+archived files.
+</p>
+<p>When you use &lsquo;<samp>--append</samp>&rsquo;, 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 &lsquo;<samp>--verbose</samp>&rsquo; 
(&lsquo;<samp>-v</samp>&rsquo;) option will print
+out the names of the files as they are written into the archive.
+</p>
+<p>&lsquo;<samp>--append</samp>&rsquo; 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 &lsquo;<samp>--append</samp>&rsquo; to add a file to 
an archive,
+create a file called &lsquo;<tt>rock</tt>&rsquo; in the 
&lsquo;<tt>practice</tt>&rsquo; directory.
+Make sure you are in the &lsquo;<tt>practice</tt>&rsquo; directory.  Then, run 
the
+following <code>tar</code> command to add &lsquo;<tt>rock</tt>&rsquo; to
+&lsquo;<tt>collection.tar</tt>&rsquo;:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar --append 
--file=collection.tar rock</kbd>
+</pre></td></tr></table>
+
+<p>If you now use the &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;) operation, you will see that
+&lsquo;<tt>rock</tt>&rsquo; has been added to the archive:
+</p>
+<table><tr><td>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC55" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--append</samp>&rsquo; 
(&lsquo;<samp>-r</samp>&rsquo;) 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 &lsquo;<samp>--update</samp>&rsquo;; See section <a 
href="#SEC55">Updating an Archive</a>, for more information.
+We describe this use of &lsquo;<samp>--append</samp>&rsquo; 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 &lsquo;<tt>blues</tt>&rsquo; and then append 
the changed
+version to &lsquo;<tt>collection.tar</tt>&rsquo;.  As you saw above, the 
original
+&lsquo;<tt>blues</tt>&rsquo; is in the archive 
&lsquo;<tt>collection.tar</tt>&rsquo;.  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 
&lsquo;<tt>blues</tt>&rsquo; to the
+archive in this way:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar --append 
--verbose --file=collection.tar blues</kbd>
+blues
+</pre></td></tr></table>
+
+<p>Because you specified the &lsquo;<samp>--verbose</samp>&rsquo; 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>&nbsp;</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 &lsquo;<tt>blues</tt>&rsquo; 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 &lsquo;<tt>blues</tt>&rsquo; will be
+replaced by the newer version.  You can confirm this by extracting
+the archive and running &lsquo;<samp>ls</samp>&rsquo; on the directory.
+</p>
+<p>If you wish to extract the first occurrence of the file 
&lsquo;<tt>blues</tt>&rsquo;
+from the archive, use &lsquo;<samp>--occurrence</samp>&rsquo; option, as shown 
in
+the following example:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--extract</samp>&rsquo; and
+See section <a href="#SEC42">&ndash;occurrence</a>, for the description of
+&lsquo;<samp>--occurrence</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC56" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--append</samp>&rsquo; to
+add a file to an existing archive.  A related operation is
+&lsquo;<samp>--update</samp>&rsquo; (&lsquo;<samp>-u</samp>&rsquo;).  The 
&lsquo;<samp>--update</samp>&rsquo; 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
+&lsquo;<samp>--append</samp>&rsquo;).
+</p>
+<p>Unfortunately, you cannot use &lsquo;<samp>--update</samp>&rsquo; with 
magnetic tape drives.
+The operation will fail.
+</p>
+
+
+
+
+<p>Both &lsquo;<samp>--update</samp>&rsquo; and 
&lsquo;<samp>--append</samp>&rsquo; 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 &lsquo;<samp>--backup</samp>&rsquo; 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 
&lsquo;<samp>--update</samp>&rsquo;</a></td><td>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC57" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--update</samp>&rsquo; </h4>
+
+<p>You must use file name arguments with the 
&lsquo;<samp>--update</samp>&rsquo;
+(&lsquo;<samp>-u</samp>&rsquo;) 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 &lsquo;<samp>--update</samp>&rsquo; option at work, create a new 
file,
+&lsquo;<tt>classical</tt>&rsquo;, in your practice directory, and some extra 
text to the
+file &lsquo;<tt>blues</tt>&rsquo;, using any text editor.  Then invoke 
<code>tar</code> with
+the &lsquo;<samp>update</samp>&rsquo; operation and the 
&lsquo;<samp>--verbose</samp>&rsquo; (&lsquo;<samp>-v</samp>&rsquo;)
+option specified, using the names of all the files in the practice
+directory as file name arguments:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>tar 
--list</samp>&rsquo; and look
+at the archive, you will see &lsquo;<tt>blues</tt>&rsquo; and 
&lsquo;<tt>classical</tt>&rsquo; at its
+end.  There will be a total of two versions of the member 
&lsquo;<samp>blues</samp>&rsquo;;
+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>&lsquo;<samp>--update</samp>&rsquo; (&lsquo;<samp>-u</samp>&rsquo;) 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC58" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--concatenate</samp>&rsquo; </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
+&lsquo;<samp>--concatenate</samp>&rsquo; 
(&lsquo;<samp>--catenate</samp>&rsquo;, &lsquo;<samp>-A</samp>&rsquo;) 
operation.
+</p>
+<p>To use &lsquo;<samp>--concatenate</samp>&rsquo;, give the first archive with
+&lsquo;<samp>--file</samp>&rsquo; 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 &lsquo;<samp>--file</samp>&rsquo; option.  As usual, if you 
omit
+&lsquo;<samp>--file</samp>&rsquo;, <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 &lsquo;<samp>--concatenate</samp>&rsquo; works, create 
two small archives
+called &lsquo;<tt>bluesrock.tar</tt>&rsquo; and 
&lsquo;<tt>folkjazz.tar</tt>&rsquo;, using the relevant
+files from &lsquo;<tt>practice</tt>&rsquo;:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>tar --list</samp>&rsquo; to make sure 
the archives
+contain what they are supposed to:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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 &lsquo;<tt>bluesrock.tar</tt>&rsquo;, 
you will see
+that now it also contains the archive members of 
&lsquo;<tt>jazzfolk.tar</tt>&rsquo;:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar --list 
--file=bluesrock.tar</kbd>
+blues
+rock
+folk
+jazz
+</pre></td></tr></table>
+
+<p>When you use &lsquo;<samp>--concatenate</samp>&rsquo;, 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 &lsquo;<samp>--append</samp>&rsquo; (&lsquo;<samp>-r</samp>&rsquo;), 
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 
&lsquo;<samp>--concatenate</samp>&rsquo;
+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.  &lsquo;<samp>--concatenate</samp>&rsquo; 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
+&lsquo;<samp>--ignore-zeros</samp>&rsquo; (&lsquo;<samp>-i</samp>&rsquo;) 
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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC59" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--delete</samp>&rsquo; </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 
&lsquo;<samp>--delete</samp>&rsquo;
+option.  Specify the name of the archive with &lsquo;<samp>--file</samp>&rsquo;
+(&lsquo;<samp>-f</samp>&rsquo;) and then specify the names of the members to 
be deleted;
+if you list no member names, nothing will be deleted.  The
+&lsquo;<samp>--verbose</samp>&rsquo; option will cause <code>tar</code> to 
print the names
+of the members as they are deleted. As with 
&lsquo;<samp>--extract</samp>&rsquo;, you
+must give the exact member names when using &lsquo;<samp>tar 
--delete</samp>&rsquo;.
+&lsquo;<samp>--delete</samp>&rsquo; will remove all versions of the named file 
from the
+archive.  The &lsquo;<samp>--delete</samp>&rsquo; operation can run very 
slowly.
+</p>
+<p>Unlike other operations, &lsquo;<samp>--delete</samp>&rsquo; has no short 
form.
+</p>
+<a name="IDX189"></a>
+<a name="IDX190"></a>
+<p>This operation will rewrite the archive.  You can only use
+&lsquo;<samp>--delete</samp>&rsquo; 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 &lsquo;<tt>blues</tt>&rsquo; from the 
archive
+&lsquo;<tt>collection.tar</tt>&rsquo; in the &lsquo;<tt>practice</tt>&rsquo; 
directory, make sure you
+are in that directory, and then,
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--delete</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC60" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--compare</samp>&rsquo; (&lsquo;<samp>-d</samp>&rsquo;), 
or &lsquo;<samp>--diff</samp>&rsquo; 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 
&lsquo;<tt>rock</tt>&rsquo;,
+&lsquo;<tt>blues</tt>&rsquo; and &lsquo;<tt>funk</tt>&rsquo; in the archive 
&lsquo;<tt>bluesrock.tar</tt>&rsquo; with
+files of the same name in the file system.  (Note that there is no file,
+&lsquo;<tt>funk</tt>&rsquo;; <code>tar</code> will report an error message.)
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--compare</samp>&rsquo; 
(&lsquo;<samp>--diff</samp>&rsquo;,
+&lsquo;<samp>-d</samp>&rsquo;) 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC61" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--create</samp>&rsquo; 
</h2>
+
+<p>The previous chapter described the basics of how to use
+&lsquo;<samp>--create</samp>&rsquo; (&lsquo;<samp>-c</samp>&rsquo;) 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
+&lsquo;<samp>--create</samp>&rsquo;.
+</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC62" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--mode=<var>permissions</var></samp>&rsquo;</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 &lsquo;<samp>a+rw</samp>&rsquo; 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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar -c -f 
archive.tar --mode='a+rw' .</kbd>
+</pre></td></tr></table>
+
+</dd>
+<dt> &lsquo;<samp>--mtime=<var>date</var></samp>&rsquo;</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 &lsquo;<samp>/</samp>&rsquo; or &lsquo;<samp>.</samp>&rsquo;.  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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar -c -f 
archive.tar --mtime='1970-01-01' .</kbd>
+</pre></td></tr></table>
+
+<p>When used with &lsquo;<samp>--verbose</samp>&rsquo; (see section <a 
href="#SEC15">The &lsquo;<samp>--verbose</samp>&rsquo; 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
+&lsquo;<samp>--mtime</samp>&rsquo; 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>&nbsp;</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
+&hellip;
+</pre></td></tr></table>
+
+</dd>
+<dt> &lsquo;<samp>--owner=<var>user</var></samp>&rsquo;</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 
&lsquo;<samp>0</samp>&rsquo; usually means
+<code>root</code>.  Some people like to force &lsquo;<samp>0</samp>&rsquo; 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>&nbsp;</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> &lsquo;<samp>--group=<var>group</var></samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC63" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--ignore-failed-read</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC64" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--extract</samp>&rsquo; 
</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 &lsquo;<samp>--extract</samp>&rsquo; 
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 &lsquo;<samp>--extract</samp>&rsquo; 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
+&lsquo;<samp>--extract</samp>&rsquo; 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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC65" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--read-full-records</samp>&rsquo; (&lsquo;<samp>-B</samp>&rsquo;) 
option
+in conjunction with the &lsquo;<samp>--extract</samp>&rsquo; or 
&lsquo;<samp>--list</samp>&rsquo; operations.
+See section <a href="#SEC147">Blocking</a>.
+</p>
+<p>The &lsquo;<samp>--read-full-records</samp>&rsquo; 
(&lsquo;<samp>-B</samp>&rsquo;) 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 &lsquo;<samp>--read-full-records</samp>&rsquo; 
(&lsquo;<samp>-B</samp>&rsquo;) and
+&lsquo;<samp>--blocking-factor=<var>512-size</var></samp>&rsquo; 
(&lsquo;<samp>-b
+<var>512-size</var></samp>&rsquo;), 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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC66">Ignoring Blocks of 
Zeros</a></td><td>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC66" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--read-full-records</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-B</samp>&rsquo;</dt>
+<dd><p>Use in conjunction with &lsquo;<samp>--extract</samp>&rsquo; 
(&lsquo;<samp>--get</samp>&rsquo;,
+&lsquo;<samp>-x</samp>&rsquo;) 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC67" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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).
+&lsquo;<samp>--ignore-zeros</samp>&rsquo; (&lsquo;<samp>-i</samp>&rsquo;) 
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 &lsquo;<samp>--ignore-zeros</samp>&rsquo; 
(&lsquo;<samp>-i</samp>&rsquo;) 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> &lsquo;<samp>--ignore-zeros</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-i</samp>&rsquo;</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
+&lsquo;<samp>--extract</samp>&rsquo; or &lsquo;<samp>--list</samp>&rsquo;.
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC68" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</td><td align="left" 
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC69">Overwrite Old 
Files</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC70">Keep Old 
Files</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC71">Keep Newer 
Files</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC72">Unlink 
First</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC73">Recursive 
Unlink</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC74">Setting Data Modification 
Times</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC75">Setting Access 
Permissions</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" 
valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC77">Writing to Standard 
Output</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC79">Removing 
Files</a></td><td>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC69" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--overwrite-dir</samp>&rsquo; option 
enables this
+default behavior.  To be more cautious and preserve the metadata of
+such a directory, use the &lsquo;<samp>--no-overwrite-dir</samp>&rsquo; 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 &lsquo;<samp>--keep-old-files</samp>&rsquo; 
(&lsquo;<samp>-k</samp>&rsquo;) 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
+&lsquo;<samp>--overwrite</samp>&rsquo; 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 &lsquo;<tt>usr/local</tt>&rsquo; is a link to
+&lsquo;<tt>usr/local2</tt>&rsquo;.  Since then, maybe the site removed the 
link and
+renamed the whole hierarchy from &lsquo;<tt>/usr/local2</tt>&rsquo; to
+&lsquo;<tt>/usr/local</tt>&rsquo;.  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
+&lsquo;<tt>/usr/local2</tt>&rsquo;, 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> &lsquo;<samp>--recursive-unlink</samp>&rsquo; is 
specified
+to allow this behavior.  In any case, single files are silently
+removed.
+</p>
+<a name="IDX206"></a>
+<p>Finally, the &lsquo;<samp>--unlink-first</samp>&rsquo; 
(&lsquo;<samp>-U</samp>&rsquo;) 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC70" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--overwrite</samp>&rsquo;</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 &lsquo;<samp>--overwrite</samp>&rsquo; option, 
particularly when
+combined with the &lsquo;<samp>--absolute-names</samp>&rsquo; 
(&lsquo;<samp>-P</samp>&rsquo;) 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> &lsquo;<samp>--overwrite-dir</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC71" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--keep-old-files</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-k</samp>&rsquo;</dt>
+<dd><p>Do not replace existing files from archive.  The
+&lsquo;<samp>--keep-old-files</samp>&rsquo; (&lsquo;<samp>-k</samp>&rsquo;) 
option prevents <code>tar</code>
+from replacing existing files with files with the same name from the
+archive. The &lsquo;<samp>--keep-old-files</samp>&rsquo; option is meaningless 
with
+&lsquo;<samp>--list</samp>&rsquo; (&lsquo;<samp>-t</samp>&rsquo;).  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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC72" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--keep-newer-files</samp>&rsquo;</dt>
+<dd><p>Do not replace existing files that are newer than their archive
+copies.  This option is meaningless with &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;).
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC73" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--unlink-first</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-U</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC74" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--recursive-unlink</samp>&rsquo;</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 &lsquo;<samp>--recursive-unlink</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC75" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--touch</samp>&rsquo; 
(&lsquo;<samp>-m</samp>&rsquo;) option in
+conjunction with &lsquo;<samp>--extract</samp>&rsquo; 
(&lsquo;<samp>--get</samp>&rsquo;, &lsquo;<samp>-x</samp>&rsquo;).
+</p>
+<dl compact="compact">
+<dd><a name="IDX213"></a>
+</dd>
+<dt> &lsquo;<samp>--touch</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-m</samp>&rsquo;</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 &lsquo;<samp>--extract</samp>&rsquo; 
(&lsquo;<samp>--get</samp>&rsquo;, &lsquo;<samp>-x</samp>&rsquo;).
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC76" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--same-permissions</samp>&rsquo;
+in conjunction with the &lsquo;<samp>--extract</samp>&rsquo; 
(&lsquo;<samp>--get</samp>&rsquo;,
+&lsquo;<samp>-x</samp>&rsquo;) operation.  
+</p>
+<dl compact="compact">
+<dd><a name="IDX214"></a>
+<a name="IDX215"></a>
+</dd>
+<dt> &lsquo;<samp>--preserve-permissions</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--same-permissions</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-p</samp>&rsquo;</dt>
+<dd><p>Set modes of extracted archive members to those recorded in the
+archive, instead of current umask settings.  Use in conjunction with
+&lsquo;<samp>--extract</samp>&rsquo; (&lsquo;<samp>--get</samp>&rsquo;, 
&lsquo;<samp>-x</samp>&rsquo;).
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC77" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</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 &lsquo;<tt>bar</tt>&rsquo;
+<acronym>GNU</acronym> <code>tar</code> will assume that all files from the 
directory &lsquo;<tt>foo</tt>&rsquo;
+were already extracted and will therefore restore its timestamp and
+permission bits.  However, after extracting &lsquo;<tt>foo/file2</tt>&rsquo; 
the
+directory timestamp will be offset again.
+</p>
+<p>To correctly restore directory meta-information in such cases, use
+&lsquo;<samp>delay-directory-restore</samp>&rsquo; command line option:
+</p>
+<dl compact="compact">
+<dd><a name="IDX216"></a>
+</dd>
+<dt> &lsquo;<samp>--delay-directory-restore</samp>&rsquo;</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> &lsquo;<samp>--no-delay-directory-restore</samp>&rsquo;</dt>
+<dd><p>Cancel the effect of the previous 
&lsquo;<samp>--delay-directory-restore</samp>&rsquo;.
+Use this option if you have used 
&lsquo;<samp>--delay-directory-restore</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC78" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--to-stdout</samp>&rsquo; (&lsquo;<samp>-O</samp>&rsquo;) in
+conjunction with &lsquo;<samp>--extract</samp>&rsquo; 
(&lsquo;<samp>--get</samp>&rsquo;, &lsquo;<samp>-x</samp>&rsquo;).  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> &lsquo;<samp>--to-stdout</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-O</samp>&rsquo;</dt>
+<dd><p>Writes files to the standard output.  Use only in conjunction with
+&lsquo;<samp>--extract</samp>&rsquo; (&lsquo;<samp>--get</samp>&rsquo;, 
&lsquo;<samp>-x</samp>&rsquo;).  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 
&lsquo;<samp>--list</samp>&rsquo;
+(&lsquo;<samp>-t</samp>&rsquo;).
+</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>&nbsp;</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>&nbsp;</td><td><pre class="smallexample">tar -xOzf foo.tgz 
bigfile1 bigfile2 | process
+</pre></td></tr></table>
+
+<p>Hovewer, &lsquo;<samp>--to-command</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC79" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--to-command=<var>command</var></samp>&rsquo;</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>&nbsp;</td><td><pre class="smallexample">tar: 2345: Child 
returned status 1
+</pre></td></tr></table>
+
+<p>Here, &lsquo;<samp>2345</samp>&rsquo; is the PID of the finished process.
+</p>
+<p>If this behavior is not wanted, use 
&lsquo;<samp>--ignore-command-error</samp>&rsquo;:
+</p>
+<dl compact="compact">
+<dd><a name="IDX232"></a>
+</dd>
+<dt> &lsquo;<samp>--ignore-command-error</samp>&rsquo;</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> &lsquo;<samp>--no-ignore-command-error</samp>&rsquo;</dt>
+<dd><p>Cancel the effect of any previous 
&lsquo;<samp>--ignore-command-error</samp>&rsquo;
+option. This option is useful if you have set
+&lsquo;<samp>--ignore-command-error</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC80" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--remove-files</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC81" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC82">Same 
Order</a></td><td>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC82" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--starting-file=<var>name</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-K <var>name</var></samp>&rsquo;</dt>
+<dd><p>Starts an operation in the middle of an archive.  Use in conjunction
+with &lsquo;<samp>--extract</samp>&rsquo; (&lsquo;<samp>--get</samp>&rsquo;, 
&lsquo;<samp>-x</samp>&rsquo;) or &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;).
+</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 &lsquo;<samp>--starting-file=<var>name</var></samp>&rsquo; 
(&lsquo;<samp>-K
+<var>name</var></samp>&rsquo;) 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, &lsquo;<samp>--starting-file</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC83" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--same-order</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--preserve-order</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-s</samp>&rsquo;</dt>
+<dd><p>To process large lists of file names on machines with small amounts of
+memory.  Use in conjunction with &lsquo;<samp>--compare</samp>&rsquo; 
(&lsquo;<samp>--diff</samp>&rsquo;,
+&lsquo;<samp>-d</samp>&rsquo;), &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;) or &lsquo;<samp>--extract</samp>&rsquo;
+(&lsquo;<samp>--get</samp>&rsquo;, &lsquo;<samp>-x</samp>&rsquo;).
+</p></dd>
+</dl>
+
+<p>The &lsquo;<samp>--same-order</samp>&rsquo; 
(&lsquo;<samp>--preserve-order</samp>&rsquo;, &lsquo;<samp>-s</samp>&rsquo;) 
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 &lsquo;<samp>tar -t</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC84" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--backup[=<var>method</var>]</samp>&rsquo;</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 &lsquo;<samp>existing</samp>&rsquo; method.
+</p>
+<a name="IDX245"></a>
+<p>This option corresponds to the Emacs variable 
&lsquo;<samp>version-control</samp>&rsquo;;
+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> &lsquo;<samp>t</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>numbered</samp>&rsquo;</dt>
+<dd><a name="IDX246"></a>
+<p>Always make numbered backups.
+</p>
+</dd>
+<dt> &lsquo;<samp>nil</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>existing</samp>&rsquo;</dt>
+<dd><a name="IDX247"></a>
+<p>Make numbered backups of files that already have them, simple backups
+of the others.
+</p>
+</dd>
+<dt> &lsquo;<samp>never</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>simple</samp>&rsquo;</dt>
+<dd><a name="IDX248"></a>
+<p>Always make simple backups.
+</p>
+</dd>
+</dl>
+
+</dd>
+<dt> &lsquo;<samp>--suffix=<var>suffix</var></samp>&rsquo;</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 
&lsquo;<samp>--backup</samp>&rsquo;.  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 &lsquo;<samp>~</samp>&rsquo;, 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC85" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</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 &lsquo;<samp>-C</samp>&rsquo; option:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC87" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC48" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>address@hidden</tt>&rsquo; and available on many Unix 
systems.
+This is free software, and it is available at these places:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC88" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--label=<var>archive-label</var></samp>&rsquo;
+(&lsquo;<samp>-V <var>archive-label</var></samp>&rsquo;) 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 &lsquo;<samp>--multi-volume</samp>&rsquo; 
(&lsquo;<samp>-M</samp>&rsquo;) 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 &lsquo;<samp>--one-file-system</samp>&rsquo; option to prevent
+<code>tar</code> from crossing file system boundaries when storing
+(sub)directories.
+</p>
+<p>The &lsquo;<samp>--incremental</samp>&rsquo; 
(&lsquo;<samp>-G</samp>&rsquo;) (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 &lsquo;<samp>--verify</samp>&rsquo; 
(&lsquo;<samp>-W</samp>&rsquo;)
+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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC89" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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: 
&lsquo;<samp>--listed-incremental=<var>snapshot-file</var></samp>&rsquo; 
(&lsquo;<samp>-g
+<var>snapshot-file</var></samp>&rsquo;) and 
&lsquo;<samp>--incremental</samp>&rsquo; (&lsquo;<samp>-G</samp>&rsquo;).
+</p>
+<a name="IDX256"></a>
+<p>The option &lsquo;<samp>--listed-incremental</samp>&rsquo; 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> &lsquo;<samp>--listed-incremental=<var>file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-g <var>file</var></samp>&rsquo;</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
+&lsquo;<samp>--listed-incremental</samp>&rsquo; together with 
&lsquo;<samp>--create</samp>&rsquo;
+(see section <a href="#SEC17">How to Create Archives</a>).  For example:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<tt>archive.1.tar</tt>&rsquo; an incremental 
backup of
+the &lsquo;<tt>/usr</tt>&rsquo; file system, storing additional metadata in 
the file
+&lsquo;<tt>/var/log/usr.snar</tt>&rsquo;.  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 &lsquo;<tt>/var/log/usr.snar</tt>&rsquo; 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 &lsquo;<tt>/usr/doc/old</tt>&rsquo; and create
+directory &lsquo;<tt>/usr/local/db</tt>&rsquo; with the following contents:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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 &lsquo;<tt>archive.2.tar</tt>&rsquo; will contain only 
these
+three members.  This archive is called a <em>level 1 backup</em>.  Notice
+that &lsquo;<tt>/var/log/usr.snar</tt>&rsquo; will be updated with the new 
data, so if
+you plan to create more &lsquo;<samp>level 1</samp>&rsquo; 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>&nbsp;</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 &lsquo;<samp>--atime-preserve=replace</samp>&rsquo; 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
+&lsquo;<samp>--listed-incremental</samp>&rsquo; together with 
&lsquo;<samp>--extract</samp>&rsquo;
+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 &lsquo;<samp>--listed-incremental</samp>&rsquo;, 
the usual
+practice is to use &lsquo;<samp>--listed-incremental=/dev/null</samp>&rsquo;.
+Alternatively, you can use &lsquo;<samp>--incremental</samp>&rsquo;, which 
needs no
+arguments.  In general, &lsquo;<samp>--incremental</samp>&rsquo; 
(&lsquo;<samp>-G</samp>&rsquo;) can be
+used as a shortcut for &lsquo;<samp>--listed-incremental</samp>&rsquo; 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 
&lsquo;<tt>/usr</tt>&rsquo;
+file system, one would do<a name="DOCF12" href="#FOOT12">(12)</a>:
+</p>
+<table><tr><td>&nbsp;</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 
&lsquo;<samp>--list</samp>&rsquo;
+(see section <a href="#SEC23">How to List Archives</a>), as usual.  To obtain 
more information about the
+archive, use &lsquo;<samp>--listed-incremental</samp>&rsquo; or 
&lsquo;<samp>--incremental</samp>&rsquo;
+combined with two &lsquo;<samp>--verbose</samp>&rsquo; options<a name="DOCF13" 
href="#FOOT13">(13)</a>:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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: 
&lsquo;<samp>Y</samp>&rsquo;
+if the file  is present in the archive, &lsquo;<samp>N</samp>&rsquo; if the 
file is not
+included in the archive, or a &lsquo;<samp>D</samp>&rsquo; 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 
&lsquo;<samp>--incremental</samp>&rsquo; (&lsquo;<samp>-G</samp>&rsquo;)
+gives the same behavior as &lsquo;<samp>--listed-incremental</samp>&rsquo; 
when used
+with &lsquo;<samp>--list</samp>&rsquo; and 
&lsquo;<samp>--extract</samp>&rsquo; options.  When used with
+&lsquo;<samp>--create</samp>&rsquo; option, it creates an incremental archive 
without
+creating snapshot file.  Thus, it is impossible to create several
+levels of incremental backups with &lsquo;<samp>--incremental</samp>&rsquo; 
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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC90" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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&mdash;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
+&lsquo;<tt>backup-specs</tt>&rsquo;, which specifies parameters used by the 
backup
+scripts and by the restore script.  This file is usually located
+in &lsquo;<tt>/etc/backup</tt>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC91" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>backup-specs</tt>&rsquo; specifies backup parameters 
for the
+backup and restoration scripts provided with <code>tar</code>.  You must
+edit &lsquo;<tt>backup-specs</tt>&rsquo; to fit your system configuration and 
schedule
+before using these scripts.
+</p>
+<p>Syntactically, &lsquo;<tt>backup-specs</tt>&rsquo; 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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC94">5.4.4 An Example Text of 
&lsquo;<tt>Backup-specs</tt>&rsquo;</a></td><td>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC92" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>now</samp>&rsquo;.
+</p>
+<p>This variable is used by <code>backup</code>.  Its value may be overridden
+using &lsquo;<samp>--time</samp>&rsquo; 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, &lsquo;<samp>--rsh-command</samp>&rsquo; 
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 &mdash; 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
+&lsquo;<tt>/etc/backup/dirs</tt>&rsquo;, but this name may be overridden in
+&lsquo;<tt>backup-specs</tt>&rsquo; 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 &lsquo;<tt>/etc/backup/dirs</tt>&rsquo;.
+</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
+&lsquo;<tt>/etc/backup/files</tt>&rsquo;, but this name may be overridden in
+&lsquo;<tt>backup-specs</tt>&rsquo; 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 &lsquo;<tt>/etc/backup/files</tt>&rsquo;.
+</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 &lsquo;<samp>--rsh-command</samp>&rsquo; 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., &lsquo;<tt>/etc/shadow</tt>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC93" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &ndash; 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>&nbsp;</td><td><pre class="smallexample">MT_BEGIN=mt_begin
+
+mt_begin() {
+    mt -f &quot;$1&quot; 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>&nbsp;</td><td><pre class="smallexample">MT_REWIND=mt_rewind
+
+mt_rewind() {
+    mt -f &quot;$1&quot; 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>&nbsp;</td><td><pre class="smallexample">MT_OFFLINE=mt_offline
+
+mt_offline() {
+    mt -f &quot;$1&quot; 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>&nbsp;</td><td><pre class="smallexample">MT_STATUS=mt_status
+
+mt_status() {
+    mt -f &quot;$1&quot; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC94" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC95" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<tt>Backup-specs</tt>&rsquo; </h3>
+
+<p>The following is an example of &lsquo;<tt>backup-specs</tt>&rsquo;:
+</p>
+<table><tr><td>&nbsp;</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=&quot;
+        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&quot;
+
+BACKUP_FILES=&quot;/com/mailer/aliases /com/mailer/league*[a-z]&quot;
+
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC96" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</td><td><pre class="smallexample">backup 
--level=<var>level</var> --time=<var>time</var>
+</pre></td></tr></table>
+
+<p>The &lsquo;<samp>level</samp>&rsquo; option requests the dump level.  Thus, 
to produce
+a full dump, specify <code>--level=0</code> (this is the default, so
+&lsquo;<samp>--level</samp>&rsquo; may be omitted if its value is 
<code>0</code>).
+<a name="DOCF14" href="#FOOT14">(14)</a>
+</p>
+<p>The &lsquo;<samp>--time</samp>&rsquo; 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 &mdash; 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 &lsquo;<tt>/etc/tar-backup/</tt>&rsquo;, 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
+&lsquo;<tt>log-<var>mm-dd-yyyy</var>-level-<var>n</var></tt>&rsquo;, 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> &lsquo;<samp>-l <var>level</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--level=<var>level</var></samp>&rsquo;</dt>
+<dd><p>Do backup level <var>level</var> (default 0).
+</p>
+</dd>
+<dt> &lsquo;<samp>-f</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--force</samp>&rsquo;</dt>
+<dd><p>Force backup even if today's log file already exists.
+</p>
+</dd>
+<dt> &lsquo;<samp>-v[<var>level</var>]</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--verbose[=<var>level</var>]</samp>&rsquo;</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> &lsquo;<samp>-t <var>start-time</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--time=<var>start-time</var></samp>&rsquo;</dt>
+<dd><p>Wait till <var>time</var>, then do backup.
+</p>
+</dd>
+<dt> &lsquo;<samp>-h</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--help</samp>&rsquo;</dt>
+<dd><p>Display short help message and exit.
+</p>
+</dd>
+<dt> &lsquo;<samp>-V</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--version</samp>&rsquo;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<tt>backup-specs</tt>&rsquo; (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>&nbsp;</td><td><pre class="smallexample">restore 'albert:*'
+</pre></td></tr></table>
+
+<p>will restore all file systems on the machine 
&lsquo;<samp>albert</samp>&rsquo;.  A more
+complicated example:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">restore 'albert:*' 
'*:/var'
+</pre></td></tr></table>
+
+<p>This command will restore all file systems on the machine 
&lsquo;<samp>albert</samp>&rsquo;
+as well as &lsquo;<tt>/var</tt>&rsquo; 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 &lsquo;<samp>--level</samp>&rsquo; option, as shown in the example below:
+</p>
+<table><tr><td>&nbsp;</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> &lsquo;<samp>-a</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--all</samp>&rsquo;</dt>
+<dd><p>Restore all file systems and files specified in 
&lsquo;<tt>backup-specs</tt>&rsquo;
+</p>
+</dd>
+<dt> &lsquo;<samp>-l <var>level</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--level=<var>level</var></samp>&rsquo;</dt>
+<dd><p>Start restoring from the given backup level, instead of the default 0.
+</p>
+</dd>
+<dt> &lsquo;<samp>-v[<var>level</var>]</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--verbose[=<var>level</var>]</samp>&rsquo;</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> &lsquo;<samp>-h</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--help</samp>&rsquo;</dt>
+<dd><p>Display short help message and exit.
+</p>
+</dd>
+<dt> &lsquo;<samp>-V</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--version</samp>&rsquo;</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&mdash;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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC98" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC86" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC99" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo; (&lsquo;<samp>-f 
<var>archive-name</var></samp>&rsquo;)
+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> &lsquo;<samp>--file=<var>archive-name</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-f <var>archive-name</var></samp>&rsquo;</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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar -cvf 
collection.tar blues folk jazz</kbd>
+</pre></td></tr></table>
+
+<p>&lsquo;<tt>collection.tar</tt>&rsquo; is the name of the archive.  It must 
directly
+follow the &lsquo;<samp>-f</samp>&rsquo; option, since whatever directly 
follows &lsquo;<samp>-f</samp>&rsquo;
+<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.  &lsquo;<tt>/dev/tu00</tt>&rsquo;).
+</p>
+<a name="IDX296"></a>
+<a name="IDX297"></a>
+<p>If you use &lsquo;<tt>-</tt>&rsquo; 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
+&lsquo;<tt>-</tt>&rsquo; 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 &lsquo;<tt>sourcedir</tt>&rsquo; to 
&lsquo;<tt>targetdir</tt>&rsquo;.
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>(cd sourcedir; 
tar -cf - .) | (cd targetdir; tar -xpf -)</kbd>
+</pre></td></tr></table>
+
+<p>The &lsquo;<samp>-C</samp>&rsquo; option allows to avoid using subshells:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<tt>sourcedir</tt>&rsquo; to the standard output, while 
the
+rightmost one reads this archive from its standard input and
+extracts it.  The &lsquo;<samp>-p</samp>&rsquo; 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>&nbsp;</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
+&lsquo;<samp>--file=@<var>hostname</var>:/<var>dev</var>/<var>file-name</var></samp>&rsquo;,
 <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 (&lsquo;<samp>:</samp>&rsquo;), then 
it is assumed
+to be a file on another machine.  If the archive file is
+&lsquo;<samp><var>user</var>@<var>host</var>:<var>file</var></samp>&rsquo;, 
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 &lsquo;<samp>@</samp>&rsquo; 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 &lsquo;<tt>rmt</tt>&rsquo; program installed (This command is 
included in
+the <acronym>GNU</acronym> <code>tar</code> distribution and by default is 
installed under
+&lsquo;<tt><var>prefix</var>/libexec/rmt</tt>&rsquo;, 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 &lsquo;<samp>--force-local</samp>&rsquo; option.
+</p>
+<p>When the archive is being created to &lsquo;<tt>/dev/null</tt>&rsquo;, 
<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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC100" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</td><td><pre class="smallexample"><kbd>tar</kbd> 
<var>operation</var> [<var>option1</var> <var>option2</var> &hellip;] 
[<var>file name-1</var> <var>file name-2</var> &hellip;]
+</pre></td></tr></table>
+
+<p>If a file name begins with dash (&lsquo;<samp>-</samp>&rsquo;), precede it 
with
+&lsquo;<samp>--add-file</samp>&rsquo; 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> &lsquo;<samp>--unquote</samp>&rsquo;</dt>
+<dd><p>Enable unquoting input file or member names (default).
+</p>
+<a name="IDX302"></a>
+</dd>
+<dt> &lsquo;<samp>--no-unquote</samp>&rsquo;</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 &lsquo;<samp>--create</samp>&rsquo; 
(&lsquo;<samp>-c</samp>&rsquo;),
+<code>tar</code> will stop immediately, reporting the following:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;) or
+&lsquo;<samp>--extract</samp>&rsquo; (&lsquo;<samp>--get</samp>&rsquo;, 
&lsquo;<samp>-x</samp>&rsquo;), <code>tar</code>
+operates on all the archive members in the archive.
+</p>
+<p>If run with &lsquo;<samp>--diff</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC101" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<samp>--files-from=<var>file-of-names</var></samp>&rsquo; 
(&lsquo;<samp>-T
+<var>file-of-names</var></samp>&rsquo;) option to <code>tar</code>.  Give the 
name of the
+file which contains the list of files to include as the argument to 
+&lsquo;<samp>--files-from</samp>&rsquo;.  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> &lsquo;<samp>--files-from=<var>file-name</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-T <var>file-name</var></samp>&rsquo;</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 
&lsquo;<samp>--files-from</samp>&rsquo;, (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 
&lsquo;<samp>--create</samp>&rsquo;, 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 &lsquo;<samp>-T</samp>&rsquo; 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 &lsquo;<tt>small-files</tt>&rsquo;.  You can then use the 
&lsquo;<samp>-T</samp>&rsquo; option to
+<code>tar</code> to specify the files from that file, 
&lsquo;<tt>small-files</tt>&rsquo;, to
+create the archive &lsquo;<tt>little.tgz</tt>&rsquo;.  (The 
&lsquo;<samp>-z</samp>&rsquo; 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>&nbsp;</td><td><pre class="smallexample">$ <kbd>find .  -size 
-400 -print &gt; 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 &lsquo;<samp>-T</samp>&rsquo; option, any file 
name beginning
+with &lsquo;<samp>-</samp>&rsquo; 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 &lsquo;<samp>-C</samp>&rsquo; option:
+</p>
+<table><tr><td>&nbsp;</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 
&lsquo;<tt>/etc</tt>&rsquo;
+directory and add files &lsquo;<tt>passwd</tt>&rsquo; and 
&lsquo;<tt>hosts</tt>&rsquo; to the
+archive.  Then it will change to &lsquo;<tt>/lib</tt>&rsquo; directory and 
will archive
+the file &lsquo;<tt>libc.a</tt>&rsquo;.  Thus, the resulting archive 
&lsquo;<tt>foo.tar</tt>&rsquo; will
+contain:
+</p>
+<table><tr><td>&nbsp;</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 
&lsquo;<samp>-T</samp>&rsquo; 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>&nbsp;</td><td><pre class="smallexample">--directory
+dir
+</pre></td></tr></table>
+
+<p>and
+</p>
+<table><tr><td>&nbsp;</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 
&lsquo;<samp>-</samp>&rsquo;,
+precede it with &lsquo;<samp>--add-file</samp>&rsquo; 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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC102" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--null</samp>&rsquo; option causes
+&lsquo;<samp>--files-from=<var>file-of-names</var></samp>&rsquo; 
(&lsquo;<samp>-T <var>file-of-names</var></samp>&rsquo;)
+to read file names terminated by a <code>NUL</code> instead of a newline, so
+files whose names contain newlines can be archived using
+&lsquo;<samp>--files-from</samp>&rsquo;. 
+</p>
+<dl compact="compact">
+<dd><a name="IDX306"></a>
+</dd>
+<dt> &lsquo;<samp>--null</samp>&rsquo;</dt>
+<dd><p>Only consider <code>NUL</code> terminated file names, instead of files 
that
+terminate in a newline.
+</p></dd>
+</dl>
+
+<p>The &lsquo;<samp>--null</samp>&rsquo; option is just like the one in 
<acronym>GNU</acronym>
+<code>xargs</code> and <code>cpio</code>, and is useful with the
+&lsquo;<samp>-print0</samp>&rsquo; predicate of <acronym>GNU</acronym> 
<code>find</code>.  In
+<code>tar</code>, &lsquo;<samp>--null</samp>&rsquo; 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
+&lsquo;<tt>long-files</tt>&rsquo;.  The &lsquo;<samp>-print0</samp>&rsquo; 
option to <code>find</code> is just
+like &lsquo;<samp>-print</samp>&rsquo;, 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
+&lsquo;<samp>--null</samp>&rsquo; and &lsquo;<samp>-T</samp>&rsquo; options to 
specify that <code>tar</code> get the
+files from that file, &lsquo;<tt>long-files</tt>&rsquo;, to create the archive
+&lsquo;<tt>big.tgz</tt>&rsquo;.  The &lsquo;<samp>--null</samp>&rsquo; option 
to <code>tar</code> will cause
+<code>tar</code> to recognize the <code>NUL</code> separator between files.
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>find .  -size 
+800 -print0 &gt; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC103" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--exclude</samp>&rsquo; or 
&lsquo;<samp>--exclude-from</samp>&rsquo; options.
+</p>
+<dl compact="compact">
+<dd><a name="IDX310"></a>
+</dd>
+<dt> &lsquo;<samp>--exclude=<var>pattern</var></samp>&rsquo;</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 &lsquo;<samp>--exclude=<var>pattern</var></samp>&rsquo; 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
+&lsquo;<tt>src</tt>&rsquo; except for files whose names end in 
&lsquo;<tt>.o</tt>&rsquo;, use the
+command &lsquo;<samp>tar -cf src.tar --exclude='*.o' src</samp>&rsquo;.
+</p>
+<p>You may give multiple &lsquo;<samp>--exclude</samp>&rsquo; options.
+</p>
+<dl compact="compact">
+<dd><a name="IDX312"></a>
+</dd>
+<dt> &lsquo;<samp>--exclude-from=<var>file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-X <var>file</var></samp>&rsquo;</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 &lsquo;<samp>--exclude-from</samp>&rsquo; 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 &lsquo;<samp>tar -c -X foo .</samp>&rsquo; and the file 
&lsquo;<tt>foo</tt>&rsquo; contains a
+single line &lsquo;<tt>*.o</tt>&rsquo;, no files whose names end in 
&lsquo;<tt>.o</tt>&rsquo; will be
+added to the archive.
+</p>
+<dl compact="compact">
+<dd><a name="IDX314"></a>
+</dd>
+<dt> &lsquo;<samp>--exclude-caches</samp>&rsquo;</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 &lsquo;<samp>--exclude-caches</samp>&rsquo; 
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 &lsquo;<tt>CACHEDIR.TAG</tt>&rsquo; 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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC104" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>exclude</samp>&rsquo; 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 
&lsquo;<samp>*.o</samp>&rsquo;, but
+explicitly name the file &lsquo;<samp>dir.o/foo</samp>&rsquo; after all the 
options have been
+listed, &lsquo;<samp>dir.o/foo</samp>&rsquo; will be excluded from the archive.
+
+</li><li>
+You can sometimes confuse the meanings of &lsquo;<samp>--exclude</samp>&rsquo; 
and
+&lsquo;<samp>--exclude-from</samp>&rsquo;.  Be careful: use 
&lsquo;<samp>--exclude</samp>&rsquo; when files
+to be excluded are given as a pattern on the command line.  Use
+&lsquo;<samp>--exclude-from</samp>&rsquo; 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 &lsquo;<samp>--exclude=<var>pattern</var></samp>&rsquo;, be sure 
to quote the
+<var>pattern</var> parameter, so <acronym>GNU</acronym> <code>tar</code> sees 
wildcard characters
+like &lsquo;<samp>*</samp>&rsquo;.  If you do not do this, the shell might 
expand the
+&lsquo;<samp>*</samp>&rsquo; 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>&nbsp;</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>&nbsp;</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
+&lsquo;<samp>--exclude-from</samp>&rsquo; option was called 
&lsquo;<samp>--exclude</samp>&rsquo; instead.
+Now, &lsquo;<samp>--exclude</samp>&rsquo; applies to patterns listed on the 
command
+line and &lsquo;<samp>--exclude-from</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC105" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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,
+&lsquo;<samp>*</samp>&rsquo; or &lsquo;<samp>?</samp>&rsquo; 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: 
&lsquo;<samp>a</samp>&rsquo;
+will match only &lsquo;<samp>a</samp>&rsquo;, and not 
&lsquo;<samp>A</samp>&rsquo;.  The character &lsquo;<samp>?</samp>&rsquo; in the
+pattern matches any single character in the matched string.  The character
+&lsquo;<samp>*</samp>&rsquo; in the pattern matches zero, one, or more single 
characters in
+the matched string.  The character &lsquo;<samp>\</samp>&rsquo; says to take 
the following
+character of the pattern <em>literally</em>; it is useful when one needs to
+match the &lsquo;<samp>?</samp>&rsquo;, &lsquo;<samp>*</samp>&rsquo;, 
&lsquo;<samp>[</samp>&rsquo; or &lsquo;<samp>\</samp>&rsquo; characters, 
themselves.
+</p>
+<p>The character &lsquo;<samp>[</samp>&rsquo;, up to the matching 
&lsquo;<samp>]</samp>&rsquo;, 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,
+&lsquo;<samp>[abcde]</samp>&rsquo; would match any of the first five letters 
of the alphabet.
+Note that within a character class, all of the &ldquo;special characters&rdquo;
+listed above other than &lsquo;<samp>\</samp>&rsquo; lose their special 
meaning; for example,
+&lsquo;<samp>[-\\[*?]]</samp>&rsquo; would match any of the characters, 
&lsquo;<samp>-</samp>&rsquo;, &lsquo;<samp>\</samp>&rsquo;,
+&lsquo;<samp>[</samp>&rsquo;, &lsquo;<samp>*</samp>&rsquo;, 
&lsquo;<samp>?</samp>&rsquo;, or &lsquo;<samp>]</samp>&rsquo;.  (Due to parsing 
constraints,
+the characters &lsquo;<samp>-</samp>&rsquo; and &lsquo;<samp>]</samp>&rsquo; 
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 
&lsquo;<samp>[</samp>&rsquo;
+is &lsquo;<samp>!</samp>&rsquo; or &lsquo;<samp>^</samp>&rsquo;, 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 &lsquo;<samp>[<var>a</var>-<var>e</var>]</samp>&rsquo;, using an 
hyphen between two
+letters, is meant to represent all characters between <var>a</var> and
+<var>e</var>, inclusive.
+</p>
+
+
+
+
+<p>Periods (&lsquo;<samp>.</samp>&rsquo;) or forward slashes 
(&lsquo;<samp>/</samp>&rsquo;) 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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC106" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--exclude</samp>&rsquo; and
+&lsquo;<samp>--exclude-from</samp>&rsquo; options, and <em>inclusion 
members</em> those
+member names that were given in the command line or read from the file
+specified with &lsquo;<samp>--files-from</samp>&rsquo; option.
+</p>
+<p>These two pairs of member lists are used in the following operations:
+&lsquo;<samp>--diff</samp>&rsquo;, &lsquo;<samp>--extract</samp>&rsquo;, 
&lsquo;<samp>--list</samp>&rsquo;,
+&lsquo;<samp>--update</samp>&rsquo;.
+</p>
+<p>There are no inclusion members in create mode 
(&lsquo;<samp>--create</samp>&rsquo; and
+&lsquo;<samp>--append</samp>&rsquo;), 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>&nbsp;</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> &lsquo;<samp>--wildcards</samp>&rsquo;</dt>
+<dd><p>Treat all member names as wildcards. 
+</p>
+<a name="IDX319"></a>
+</dd>
+<dt> &lsquo;<samp>--no-wildcards</samp>&rsquo;</dt>
+<dd><p>Treat all member names as literal strings.
+</p></dd>
+</dl>
+
+<p>Thus, to extract files whose names end in &lsquo;<samp>.c</samp>&rsquo;, 
you can use:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--wildcards</samp>&rsquo; option is cancelled by
+&lsquo;<samp>--no-wildcards</samp>&rsquo;.  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>&nbsp;</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 &lsquo;<tt>foo.tar</tt>&rsquo; 
all files whose
+names end in &lsquo;<samp>.txt</samp>&rsquo; and the file named 
&lsquo;<tt>[remarks]</tt>&rsquo;.
+</p>
+<p>Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where &lsquo;<samp>*</samp>&rsquo;, 
&lsquo;<samp>?</samp>&rsquo;, and
+&lsquo;<samp>[...]</samp>&rsquo; are the usual shell wildcards, 
&lsquo;<samp>\</samp>&rsquo; escapes wildcards,
+and wildcards can match &lsquo;<samp>/</samp>&rsquo;.
+</p>
+<p>Other than optionally stripping leading &lsquo;<samp>/</samp>&rsquo; from 
names
+(see section <a href="#SEC112">Absolute File Names</a>), patterns and names 
are used as-is.  For
+example, trailing &lsquo;<samp>/</samp>&rsquo; 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>&nbsp;</td><td><pre class="smallexample">--ignore-case 
--exclude='makefile' --no-ignore-case ---exclude='readme'
+</pre></td></tr></table>
+
+<p>ignores case when excluding &lsquo;<samp>makefile</samp>&rsquo;, but not 
when excluding
+&lsquo;<samp>readme</samp>&rsquo;.
+</p>
+<dl compact="compact">
+<dd><a name="IDX320"></a>
+<a name="IDX321"></a>
+</dd>
+<dt> &lsquo;<samp>--anchored</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--no-anchored</samp>&rsquo;</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 &lsquo;<samp>--no-anchored</samp>&rsquo; for 
exclusion members
+and &lsquo;<samp>--anchored</samp>&rsquo; inclusion members.
+</p>
+<a name="IDX322"></a>
+<a name="IDX323"></a>
+</dd>
+<dt> &lsquo;<samp>--ignore-case</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--no-ignore-case</samp>&rsquo;</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> &lsquo;<samp>--wildcards-match-slash</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--no-wildcards-match-slash</samp>&rsquo;</dt>
+<dd><p>When wildcards match slash (the default for exclusion members), a
+wildcard like &lsquo;<samp>*</samp>&rsquo; in the pattern can match a 
&lsquo;<samp>/</samp>&rsquo; in the
+name.  Otherwise, &lsquo;<samp>/</samp>&rsquo; is matched only by 
&lsquo;<samp>/</samp>&rsquo;.
+</p>
+</dd>
+</dl>
+
+<p>The &lsquo;<samp>--recursion</samp>&rsquo; and 
&lsquo;<samp>--no-recursion</samp>&rsquo; 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> &lsquo;<samp>--no-wildcards --anchored 
--no-wildcards-match-slash</samp>&rsquo;
+</p></td></tr>
+<tr><td><p> Exclusion </p></td><td><p> &lsquo;<samp>--wildcards --no-anchored 
--wildcards-match-slash</samp>&rsquo;
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC107" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 (&lsquo;<samp>'</samp>&rsquo; and 
&lsquo;<samp>&quot;</samp>&rsquo;)
+
+</li><li> Backslash (&lsquo;<samp>\</samp>&rsquo;)
+</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 
&lsquo;<samp>Character</samp>&rsquo; in the
+above table, a space is printed as &lsquo;<samp>\ </samp>&rsquo; and a 
backslash as &lsquo;<samp>\\</samp>&rsquo;.
+</p>
+<p><acronym>GNU</acronym> <code>tar</code> offers seven distinct quoting 
styles, which can be selected
+using &lsquo;<samp>--quoting-style</samp>&rsquo; option:
+</p>
+<dl compact="compact">
+<dt> &lsquo;<samp>--quoting-style=<var>style</var></samp>&rsquo;</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 &lsquo;<tt>arch.tar</tt>&rsquo;
+containing the following members:
+</p>
+<table><tr><td>&nbsp;</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&quot;double&quot;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>&nbsp;</td><td><pre class="smallexample">$ <kbd>ls</kbd>
+a\ttab
+a\nnewline
+a\ space
+a&quot;double&quot;quote
+a'single'quote
+a\\backslash
+</pre></td></tr></table>
+
+<p>Quoting styles:
+</p>
+<dl compact="compact">
+<dt> &lsquo;<samp>literal</samp>&rsquo;</dt>
+<dd><p>No quoting, display each character as is:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar tf arch.tar 
--quoting-style=literal</kbd>
+./
+./a space
+./a'single'quote
+./a&quot;double&quot;quote
+./a\backslash
+./a    tab
+./a
+newline
+</pre></td></tr></table>
+
+</dd>
+<dt> &lsquo;<samp>shell</samp>&rsquo;</dt>
+<dd><p>Display characters the same way Bourne shell does:
+control characters, except &lsquo;<samp>\t</samp>&rsquo; and 
&lsquo;<samp>\n</samp>&rsquo;, are printed using
+backslash escapes, &lsquo;<samp>\t</samp>&rsquo; and 
&lsquo;<samp>\n</samp>&rsquo; are printed as is, and a
+single quote is printed as &lsquo;<samp>\'</samp>&rsquo;.  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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar tf arch.tar 
--quoting-style=shell</kbd>
+./
+'./a space'
+'./a'\''single'\''quote'
+'./a&quot;double&quot;quote'
+'./a\backslash'
+'./a   tab'
+'./a
+newline'
+</pre></td></tr></table>
+
+</dd>
+<dt> &lsquo;<samp>shell-always</samp>&rsquo;</dt>
+<dd><p>Same as &lsquo;<samp>shell</samp>&rsquo;, but the names are always 
enclosed in single
+quotes:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar tf arch.tar 
--quoting-style=shell-always</kbd>
+'./'
+'./a space'
+'./a'\''single'\''quote'
+'./a&quot;double&quot;quote'
+'./a\backslash'
+'./a   tab'
+'./a
+newline'
+</pre></td></tr></table>
+
+</dd>
+<dt> &lsquo;<samp>c</samp>&rsquo;</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 
&lsquo;<samp>\&quot;</samp>&rsquo;,
+backslash characters are represented as &lsquo;<samp>\\</samp>&rsquo;.  Single 
quotes and
+spaces are not quoted:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar tf arch.tar 
--quoting-style=c</kbd>
+&quot;./&quot;
+&quot;./a space&quot;
+&quot;./a'single'quote&quot;
+&quot;./a\&quot;double\&quot;quote&quot;
+&quot;./a\\backslash&quot;
+&quot;./a\ttab&quot;
+&quot;./a\nnewline&quot;
+</pre></td></tr></table>
+
+</dd>
+<dt> &lsquo;<samp>escape</samp>&rsquo;</dt>
+<dd><p>Control characters are printed using backslash notation, a space is
+printed as &lsquo;<samp>\ </samp>&rsquo; and a backslash as 
&lsquo;<samp>\\</samp>&rsquo;.  This is the
+default quoting style, unless it was changed when configured the
+package.
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar tf arch.tar 
--quoting-style=escape</kbd>
+./
+./a space
+./a'single'quote
+./a&quot;double&quot;quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+</pre></td></tr></table>
+
+</dd>
+<dt> &lsquo;<samp>locale</samp>&rsquo;</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 &lsquo;<samp>`</samp>&rsquo; as left and 
&lsquo;<samp>'</samp>&rsquo; as right
+quotation marks.  Any occurrences of the right quotation mark in a
+name are escaped with &lsquo;<samp>\</samp>&rsquo;, for example:
+</p>
+<p>For example:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar tf arch.tar 
--quoting-style=locale</kbd>
+`./'
+`./a space'
+`./a\'single\'quote'
+`./a&quot;double&quot;quote'
+`./a\\backslash'
+`./a\ttab'
+`./a\nnewline'
+</pre></td></tr></table>
+
+</dd>
+<dt> &lsquo;<samp>clocale</samp>&rsquo;</dt>
+<dd><p>Same as &lsquo;<samp>locale</samp>&rsquo;, but 
&lsquo;<samp>&quot;</samp>&rsquo; is used for both left and right
+quotation marks, if not provided by the currently selected locale:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar tf arch.tar 
--quoting-style=clocale</kbd>
+&quot;./&quot;
+&quot;./a space&quot;
+&quot;./a'single'quote&quot;
+&quot;./a\&quot;double\&quot;quote&quot;
+&quot;./a\\backslash&quot;
+&quot;./a\ttab&quot;
+&quot;./a\nnewline&quot;
+</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> &lsquo;<samp>--quote-chars=<var>string</var></samp>&rsquo;</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 &lsquo;<samp>escape</samp>&rsquo; quoting (compare with 
the usual
+escape listing above): 
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar tf arch.tar 
--quoting-style=escape --quote-chars=' &quot;'</kbd>
+./
+./a\ space
+./a'single'quote
+./a\&quot;double\&quot;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> &lsquo;<samp>--no-quote-chars=<var>string</var></samp>&rsquo;</dt>
+<dd><p>Remove characters listed in <var>string</var> from the list of quoted
+characters set by the previous &lsquo;<samp>--quote-chars</samp>&rsquo; option.
+</p></dd>
+</dl>
+
+<p>This option is particularly useful if you have added
+&lsquo;<samp>--quote-chars</samp>&rsquo; 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 &lsquo;<samp>--no-quote-chars</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC108" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>../</tt>&rsquo;.  
<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> &lsquo;<samp>--strip-components=<var>number</var></samp>&rsquo;</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 &lsquo;<tt>/usr</tt>&rsquo; 
hierarchy to
+a tar archive named &lsquo;<tt>usr.tar</tt>&rsquo;.  Among other files, this 
archive
+contains &lsquo;<tt>usr/include/stdlib.h</tt>&rsquo;, which you wish to 
extract to
+the current working directory.  To do so, you type:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar -xf usr.tar 
--strip=2 usr/include/stdlib.h</kbd>
+</pre></td></tr></table>
+
+<p>The option &lsquo;<samp>--strip=2</samp>&rsquo; instructs <code>tar</code> 
to strip the
+two leading components (&lsquo;<tt>usr/</tt>&rsquo; and 
&lsquo;<tt>include/</tt>&rsquo;) off the file
+name. 
+</p>
+<p>If you add to the above invocation &lsquo;<samp>--verbose</samp>&rsquo; 
(&lsquo;<samp>-v</samp>&rsquo;)
+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> &lsquo;<samp>--show-transformed-names</samp>&rsquo;</dt>
+<dd><p>Display file or member names with all requested transformations
+applied.
+</p></dd>
+</dl>
+
+<p>For example:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<tt>stdlib.h</tt>&rsquo; 
extracted to the
+current working directory, &lsquo;<samp>--show-transformed-names</samp>&rsquo; 
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>&nbsp;</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>&nbsp;</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> &lsquo;<samp>--transform=<var>expression</var></samp>&rsquo;</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>&nbsp;</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 &quot;s&quot; Command: (sed)The 
&quot;s&quot; Command</a> section `The `s' Command' in <cite>GNU sed</cite>.
+</p>
+<p>Supported <var>flags</var> are:
+</p>
+<dl compact="compact">
+<dt> &lsquo;<samp>g</samp>&rsquo;</dt>
+<dd><p>Apply the replacement to <em>all</em> matches to the <var>regexp</var>, 
not
+just the first.
+</p>
+</dd>
+<dt> &lsquo;<samp>i</samp>&rsquo;</dt>
+<dd><p>Use case-insensitive matching
+</p>
+</dd>
+<dt> &lsquo;<samp>x</samp>&rsquo;</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> &lsquo;<samp><var>number</var></samp>&rsquo;</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 &lsquo;<samp>g</samp>&rsquo; 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 &lsquo;<samp>/</samp>&rsquo;, the 
only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--transform</samp>&rsquo; usage:
+</p>
+<ol>
+<li> Extract &lsquo;<tt>usr/</tt>&rsquo; hierarchy into 
&lsquo;<tt>usr/local/</tt>&rsquo;:
+
+<table><tr><td>&nbsp;</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
+&lsquo;<samp>--strip-components=2</samp>&rsquo;):
+
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar 
--transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar</kbd>
+</pre></td></tr></table>
+
+</li><li> Prepend &lsquo;<tt>/prefix/</tt>&rsquo;  to each file name:
+
+<table><tr><td>&nbsp;</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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar --transform 
's/.*/\L&amp;/' -x -f arch.tar</kbd>
+</pre></td></tr></table>
+
+</li></ol>
+
+<p>Unlike &lsquo;<samp>--strip-components</samp>&rsquo;, 
&lsquo;<samp>--transform</samp>&rsquo; 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 
&lsquo;<tt>usr/</tt>&rsquo;
+component with &lsquo;<tt>var/</tt>&rsquo;:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar -cf 
arch.tar --transform='s,^usr/,var/,' /</kbd>
+</pre></td></tr></table>
+
+<p>To test &lsquo;<samp>--transform</samp>&rsquo; effect we suggest using
+&lsquo;<samp>--show-transformed-names</samp>&rsquo; option:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>--strip-components</samp>&rsquo; and 
&lsquo;<samp>--transform</samp>&rsquo; are used
+together, then &lsquo;<samp>--transform</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC109" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--after-date=<var>date</var></samp>&rsquo; 
(&lsquo;<samp>--newer=<var>date</var></samp>&rsquo;,
+&lsquo;<samp>-N <var>date</var></samp>&rsquo;) 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 
&lsquo;<samp>/</samp>&rsquo; or &lsquo;<samp>.</samp>&rsquo;,
+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
+&lsquo;<samp>--after-date</samp>&rsquo; 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 
&lsquo;<samp>--newer-mtime=<var>date</var></samp>&rsquo; option.
+</p>
+<p>You may use these options with any operation.  Note that these options
+differ from the &lsquo;<samp>--update</samp>&rsquo; 
(&lsquo;<samp>-u</samp>&rsquo;) 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> &lsquo;<samp>--after-date=<var>date</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--newer=<var>date</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-N <var>date</var></samp>&rsquo;</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 &lsquo;<samp>/</samp>&rsquo; or 
&lsquo;<samp>.</samp>&rsquo;, 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> &lsquo;<samp>--newer-mtime=<var>date</var></samp>&rsquo;</dt>
+<dd><p>Acts like &lsquo;<samp>--after-date</samp>&rsquo;, 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 &lsquo;<samp>--after-date</samp>&rsquo; 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 &lsquo;<samp>--newer-mtime</samp>&rsquo; tests only the 
<code>mtime</code>
+field.
+</p>
+<p>To be precise, &lsquo;<samp>--after-date</samp>&rsquo; 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 &lsquo;<samp>--newer-mtime</samp>&rsquo; 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>&nbsp;</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 
&lsquo;<samp>--verbose</samp>&rsquo;
+(see section <a href="#SEC15">The &lsquo;<samp>--verbose</samp>&rsquo; 
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>&nbsp;</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> 
&lsquo;<samp>--after-date</samp>&rsquo; and 
&lsquo;<samp>--newer-mtime</samp>&rsquo;
+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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC110" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--files-from</samp>&rsquo;
+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 &lsquo;<samp>--no-recursion</samp>&rsquo; option inhibits 
<code>tar</code>'s recursive descent
+into specified directories.  If you specify 
&lsquo;<samp>--no-recursion</samp>&rsquo;, 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> &lsquo;<samp>--no-recursion</samp>&rsquo;</dt>
+<dd><p>Prevents <code>tar</code> from recursively descending directories.
+</p>
+<a name="IDX342"></a>
+</dd>
+<dt> &lsquo;<samp>--recursion</samp>&rsquo;</dt>
+<dd><p>Requires <code>tar</code> to recursively descend directories.
+This is the default.
+</p></dd>
+</dl>
+
+<p>When you use &lsquo;<samp>--no-recursion</samp>&rsquo;, 
<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 &lsquo;<samp>-not -type 
d</samp>&rsquo;
+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 &lsquo;<samp>--files-from</samp>&rsquo; 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
+&lsquo;<samp>--same-permissions</samp>&rsquo; 
(&lsquo;<samp>--preserve-permissions</samp>&rsquo;,
+&lsquo;<samp>-p</samp>&rsquo;) option does not affect them&mdash;while users 
might really
+like it to.  Specifying &lsquo;<samp>--no-recursion</samp>&rsquo; 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>&nbsp;</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 &lsquo;<samp>--no-recursion</samp>&rsquo; 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 &lsquo;<samp>--no-recursion</samp>&rsquo; option also affects how 
globbing patterns
+are interpreted (see section <a href="#SEC105">Controlling 
Pattern-Matching</a>).
+</p>
+<p>The &lsquo;<samp>--no-recursion</samp>&rsquo; and 
&lsquo;<samp>--recursion</samp>&rsquo; options apply to
+later options and operands, and can be overridden by later occurrences
+of &lsquo;<samp>--no-recursion</samp>&rsquo; and 
&lsquo;<samp>--recursion</samp>&rsquo;.  For example:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<tt>grape</tt>&rsquo;, and the 
recursive
+contents of &lsquo;<tt>grape/concord</tt>&rsquo;, but no entries under 
&lsquo;<tt>grape</tt>&rsquo;
+other than &lsquo;<tt>grape/concord</tt>&rsquo;.
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC111" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<samp>--one-file-system</samp>&rsquo;.  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 &lsquo;<samp>--files-from</samp>&rsquo;, regardless of where they 
reside.
+</p>
+<dl compact="compact">
+<dd><a name="IDX343"></a>
+</dd>
+<dt> &lsquo;<samp>--one-file-system</samp>&rsquo;</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 &lsquo;<samp>--one-file-system</samp>&rsquo; 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
+&lsquo;<samp>--verbose</samp>&rsquo; (&lsquo;<samp>-v</samp>&rsquo;), 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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC112" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<samp>--files-from</samp>&rsquo; (&lsquo;<samp>-T</samp>&rsquo;), use 
&lsquo;<samp>--directory</samp>&rsquo; (&lsquo;<samp>-C</samp>&rsquo;).
+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> &lsquo;<samp>--directory=<var>directory</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-C <var>directory</var></samp>&rsquo;</dt>
+<dd><p>Changes the working directory in the middle of a command line.
+</p></dd>
+</dl>
+
+<p>For example,
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<tt>grape</tt>&rsquo; and 
&lsquo;<tt>prune</tt>&rsquo; from the current
+directory into the archive &lsquo;<tt>jams.tar</tt>&rsquo;, followed by the 
file
+&lsquo;<tt>cherry</tt>&rsquo; from the directory &lsquo;<tt>food</tt>&rsquo;.  
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 &lsquo;<tt>cherry</tt>&rsquo; is recorded in the archive 
under the
+precise name &lsquo;<tt>cherry</tt>&rsquo;, <em>not</em> 
&lsquo;<tt>food/cherry</tt>&rsquo;.  Thus, the
+archive will contain three files that all appear to have come from the
+same directory; if the archive is extracted with plain &lsquo;<samp>tar
+--extract</samp>&rsquo;, all three files will be written in the current 
directory.
+</p>
+<p>Contrast this with the command,
+</p>
+<table><tr><td>&nbsp;</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
+&lsquo;<tt>red/cherry</tt>&rsquo; so that, if the archive is extracted using
+&lsquo;<samp>tar --extract</samp>&rsquo;, the third file will be written in a 
subdirectory
+named &lsquo;<tt>orange-colored</tt>&rsquo;.
+</p>
+<p>You can use the &lsquo;<samp>--directory</samp>&rsquo; option to make the 
archive
+independent of the original name of the directory holding the files.
+The following command places the files &lsquo;<tt>/etc/passwd</tt>&rsquo;,
+&lsquo;<tt>/etc/hosts</tt>&rsquo;, and &lsquo;<tt>/lib/libc.a</tt>&rsquo; into 
the archive
+&lsquo;<tt>foo.tar</tt>&rsquo;:
+</p>
+<table><tr><td>&nbsp;</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: &lsquo;<tt>passwd</tt>&rsquo;, 
&lsquo;<tt>hosts</tt>&rsquo;, and &lsquo;<tt>libc.a</tt>&rsquo;.
+They will not appear to be related by file name to the original
+directories where those files were located.
+</p>
+<p>Note that &lsquo;<samp>--directory</samp>&rsquo; options are interpreted 
consecutively.  If
+&lsquo;<samp>--directory</samp>&rsquo; 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
+&lsquo;<samp>--directory</samp>&rsquo; option.
+</p>
+<p>When using &lsquo;<samp>--files-from</samp>&rsquo; (see section <a 
href="#SEC100">Reading Names from a File</a>), you can put various
+<code>tar</code> options (including &lsquo;<samp>-C</samp>&rsquo;) 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>&nbsp;</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>&nbsp;</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 &lsquo;<samp>-C</samp>&rsquo;, not 
&lsquo;<samp>--directory</samp>&rsquo;.
+</p>
+<p>The interpretation of &lsquo;<samp>--directory</samp>&rsquo; is disabled by
+&lsquo;<samp>--null</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--absolute-names</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-P</samp>&rsquo;</dt>
+<dd><p>Do not strip leading slashes from file names, and permit file names
+containing a &lsquo;<tt>..</tt>&rsquo; file name component.
+</p></dd>
+</dl>
+
+<p>By default, <acronym>GNU</acronym> <code>tar</code> drops a leading 
&lsquo;<samp>/</samp>&rsquo; on
+input or output, and complains about file names containing a 
&lsquo;<tt>..</tt>&rsquo;
+component.  This option turns off this behavior.
+</p>
+<p>When <code>tar</code> extracts archive members from an archive, it strips 
any
+leading slashes (&lsquo;<samp>/</samp>&rsquo;) 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
+&lsquo;<tt>/etc/passwd</tt>&rsquo;, <code>tar</code> will extract it as if the 
name were
+really &lsquo;<tt>etc/passwd</tt>&rsquo;.
+</p>
+<p>File names containing &lsquo;<tt>..</tt>&rsquo; 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
+&lsquo;<tt>/bin/ls</tt>&rsquo; to an archive, it will do so, but the member 
name will
+be &lsquo;<tt>bin/ls</tt>&rsquo;.<a name="DOCF17" href="#FOOT17">(17)</a>
+</p>
+<p>If you use the &lsquo;<samp>--absolute-names</samp>&rsquo; 
(&lsquo;<samp>-P</samp>&rsquo;) option,
+<code>tar</code> will do none of these transformations.
+</p>
+<p>To archive or extract files relative to the root directory, specify
+the &lsquo;<samp>--absolute-names</samp>&rsquo; 
(&lsquo;<samp>-P</samp>&rsquo;) option.
+</p>
+<p>Normally, <code>tar</code> acts on files relative to the working
+directory&mdash;ignoring superior directory names when archiving, and
+ignoring leading slashes when extracting.
+</p>
+<p>When you specify &lsquo;<samp>--absolute-names</samp>&rsquo; 
(&lsquo;<samp>-P</samp>&rsquo;),
+<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
+&lsquo;<samp>--absolute-names</samp>&rsquo; option, but using this option
+may be more convenient than switching to root.
+</p>
+
+
+
+
+
+
+
+
+<dl compact="compact">
+<dt> &lsquo;<samp>--absolute-names</samp>&rsquo;</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 
&lsquo;<samp>/</samp>&rsquo; 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>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar -c -f 
archive.tar /home 2&gt; /dev/null</kbd>
+</pre></td></tr></table>
+
+<p>Another solution, both nicer and simpler, would be to change to
+the &lsquo;<tt>/</tt>&rsquo; directory first, and then avoid absolute notation.
+For example:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>(cd / 
&amp;&amp; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC114" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC97" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&hellip;  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.  &hellip;
+</p>
+<p>&mdash; 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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">     
TZ=&quot;America/New_York&quot;, TZ=&quot;UTC0&quot;.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC123">7.10 Authors of 
<code>get_date</code></a></td><td>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC115" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<samp>last</samp>&rsquo; stands for <em>-1</em>, 
&lsquo;<samp>this</samp>&rsquo; stands for 0, and
+&lsquo;<samp>first</samp>&rsquo; and &lsquo;<samp>next</samp>&rsquo; both 
stand for 1.  Because the word
+&lsquo;<samp>second</samp>&rsquo; stands for the unit of time there is no way 
to write the
+ordinal number 2, but for convenience &lsquo;<samp>third</samp>&rsquo; stands 
for 3,
+&lsquo;<samp>fourth</samp>&rsquo; for 4, &lsquo;<samp>fifth</samp>&rsquo; for 
5,
+&lsquo;<samp>sixth</samp>&rsquo; for 6, &lsquo;<samp>seventh</samp>&rsquo; for 
7, &lsquo;<samp>eighth</samp>&rsquo; for 8,
+&lsquo;<samp>ninth</samp>&rsquo; for 9, &lsquo;<samp>tenth</samp>&rsquo; for 
10, &lsquo;<samp>eleventh</samp>&rsquo; for 11 and
+&lsquo;<samp>twelfth</samp>&rsquo; 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 &ldquo;spelled in full&rdquo;; this changes the
+allowed strings.
+</p>
+<a name="IDX355"></a>
+<p>In the current implementation, only English is supported for words and
+abbreviations like &lsquo;<samp>AM</samp>&rsquo;, 
&lsquo;<samp>DST</samp>&rsquo;, &lsquo;<samp>EST</samp>&rsquo;, 
&lsquo;<samp>first</samp>&rsquo;,
+&lsquo;<samp>January</samp>&rsquo;, &lsquo;<samp>Sunday</samp>&rsquo;, 
&lsquo;<samp>tomorrow</samp>&rsquo;, and &lsquo;<samp>year</samp>&rsquo;.
+</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 &lsquo;<samp>IST</samp>&rsquo;.  
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 &lsquo;<samp>UTC</samp>&rsquo; and 
&lsquo;<samp>Z</samp>&rsquo;.  Here are some
+ways to do this:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>2005-02-29</samp>&rsquo; or times like 
&lsquo;<samp>24:00</samp>&rsquo; are
+rejected.  In the typical case of a host that does not support leap
+seconds, a time like &lsquo;<samp>23:59:60</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC116" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</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>&nbsp;</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
+&lsquo;<samp><var>year</var>-<var>month</var>-<var>day</var></samp>&rsquo; 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
+&lsquo;<samp><var>month</var>/<var>day</var>/<var>year</var></samp>&rsquo;, 
popular in the United States,
+is accepted.  Also &lsquo;<samp><var>month</var>/<var>day</var></samp>&rsquo;, 
omitting the year.
+</p>
+<a name="IDX362"></a>
+<a name="IDX363"></a>
+<p>Literal months may be spelled out in full: 
&lsquo;<samp>January</samp>&rsquo;,
+&lsquo;<samp>February</samp>&rsquo;, &lsquo;<samp>March</samp>&rsquo;, 
&lsquo;<samp>April</samp>&rsquo;, &lsquo;<samp>May</samp>&rsquo;, 
&lsquo;<samp>June</samp>&rsquo;,
+&lsquo;<samp>July</samp>&rsquo;, &lsquo;<samp>August</samp>&rsquo;, 
&lsquo;<samp>September</samp>&rsquo;, &lsquo;<samp>October</samp>&rsquo;,
+&lsquo;<samp>November</samp>&rsquo; or &lsquo;<samp>December</samp>&rsquo;.  
Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write &lsquo;<samp>Sept</samp>&rsquo; instead of 
&lsquo;<samp>September</samp>&rsquo;.
+</p>
+<p>When months are written literally, the calendar date may be given as any
+of the following:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC117" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</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
+&lsquo;<samp><var>hour</var>:<var>minute</var>:<var>second</var></samp>&rsquo;,
 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
+&lsquo;<samp>.</samp>&rsquo; or &lsquo;<samp>,</samp>&rsquo; and a fraction 
containing one or more digits.
+Alternatively,
+&lsquo;<samp>:<var>second</var></samp>&rsquo; 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 &lsquo;<samp>am</samp>&rsquo; or 
&lsquo;<samp>pm</samp>&rsquo; (or &lsquo;<samp>a.m.</samp>&rsquo;
+or &lsquo;<samp>p.m.</samp>&rsquo;), <var>hour</var> is restricted to run from 
1 to 12, and
+&lsquo;<samp>:<var>minute</var></samp>&rsquo; may be omitted (taken to be 
zero).  &lsquo;<samp>am</samp>&rsquo;
+indicates the first half of the day, &lsquo;<samp>pm</samp>&rsquo; indicates 
the second
+half of the day.  In this notation, 12 is the predecessor of 1:
+midnight is &lsquo;<samp>12am</samp>&rsquo; while noon is 
&lsquo;<samp>12pm</samp>&rsquo;.
+(This is the zero-oriented interpretation of &lsquo;<samp>12am</samp>&rsquo; 
and &lsquo;<samp>12pm</samp>&rsquo;,
+as opposed to the old tradition derived from Latin
+which uses &lsquo;<samp>12m</samp>&rsquo; for noon and 
&lsquo;<samp>12pm</samp>&rsquo; 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 
&lsquo;<samp><var>s</var><var>hh</var><var>mm</var></samp>&rsquo;, where 
<var>s</var> is &lsquo;<samp>+</samp>&rsquo;
+or &lsquo;<samp>-</samp>&rsquo;, <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,
+&lsquo;<samp>+0530</samp>&rsquo; and &lsquo;<samp>+05:30</samp>&rsquo; 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 &lsquo;<samp>am</samp>&rsquo;/&lsquo;<samp>pm</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC118" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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., &lsquo;<samp>UTC</samp>&rsquo; or 
&lsquo;<samp>Z</samp>&rsquo;
+for Coordinated Universal
+Time.  Any included periods are ignored.  By following a
+non-daylight-saving time zone by the string &lsquo;<samp>DST</samp>&rsquo; 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 &lsquo;<samp>UTC</samp>&rsquo;; for example, 
&lsquo;<samp>UTC+05:30</samp>&rsquo; is equivalent to
+&lsquo;<samp>+05:30</samp>&rsquo;.
+</p>
+<p>Time zone items other than &lsquo;<samp>UTC</samp>&rsquo; and 
&lsquo;<samp>Z</samp>&rsquo;
+are obsolescent and are not recommended, because they
+are ambiguous; for example, &lsquo;<samp>EST</samp>&rsquo; has a different 
meaning in
+Australia than in the United States.  Instead, it's better to use
+unambiguous numeric time zone corrections like 
&lsquo;<samp>-0500</samp>&rsquo;, 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC119" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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: 
&lsquo;<samp>Sunday</samp>&rsquo;,
+&lsquo;<samp>Monday</samp>&rsquo;, &lsquo;<samp>Tuesday</samp>&rsquo;, 
&lsquo;<samp>Wednesday</samp>&rsquo;, &lsquo;<samp>Thursday</samp>&rsquo;,
+&lsquo;<samp>Friday</samp>&rsquo; or &lsquo;<samp>Saturday</samp>&rsquo;.  
Days may be abbreviated to their
+first three letters, optionally followed by a period.  The special
+abbreviations &lsquo;<samp>Tues</samp>&rsquo; for 
&lsquo;<samp>Tuesday</samp>&rsquo;, &lsquo;<samp>Wednes</samp>&rsquo; for
+&lsquo;<samp>Wednesday</samp>&rsquo; and &lsquo;<samp>Thur</samp>&rsquo; or 
&lsquo;<samp>Thurs</samp>&rsquo; for &lsquo;<samp>Thursday</samp>&rsquo; 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 &lsquo;<samp>third
+monday</samp>&rsquo;.  In this context, &lsquo;<samp>last 
<var>day</var></samp>&rsquo; or &lsquo;<samp>next
+<var>day</var></samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC120" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;</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 
&lsquo;<samp>year</samp>&rsquo;
+or &lsquo;<samp>month</samp>&rsquo; 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 &lsquo;<samp>fortnight</samp>&rsquo; which is worth 14 days, 
&lsquo;<samp>week</samp>&rsquo; worth 7
+days, &lsquo;<samp>day</samp>&rsquo; worth 24 hours, 
&lsquo;<samp>hour</samp>&rsquo; worth 60 minutes,
+&lsquo;<samp>minute</samp>&rsquo; or &lsquo;<samp>min</samp>&rsquo; worth 60 
seconds, and &lsquo;<samp>second</samp>&rsquo; or
+&lsquo;<samp>sec</samp>&rsquo; worth one second.  An 
&lsquo;<samp>s</samp>&rsquo; 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 &lsquo;<samp>ago</samp>&rsquo; 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 &lsquo;<samp>tomorrow</samp>&rsquo; is worth one day in the 
future (equivalent
+to &lsquo;<samp>day</samp>&rsquo;), the string 
&lsquo;<samp>yesterday</samp>&rsquo; is worth
+one day in the past (equivalent to &lsquo;<samp>day ago</samp>&rsquo;).
+</p>
+<a name="IDX383"></a>
+<a name="IDX384"></a>
+<a name="IDX385"></a>
+<p>The strings &lsquo;<samp>now</samp>&rsquo; or 
&lsquo;<samp>today</samp>&rsquo; 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 &lsquo;<samp>12:00 today</samp>&rsquo;.  The string 
&lsquo;<samp>this</samp>&rsquo; also has
+the meaning of a zero-valued time displacement, but is preferred in
+date strings like &lsquo;<samp>this thursday</samp>&rsquo;.
+</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, &lsquo;<samp>2003-07-31 -1 month</samp>&rsquo; 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>&nbsp;</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=&quot;$(date +%Y-%m-15) -1 month&quot; +'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
+&lsquo;<samp>UTC0</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC121" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC122" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>@</samp>&rsquo;, it represents an 
internal time
+stamp as a count of seconds.  The number can contain an internal
+decimal point (either &lsquo;<samp>.</samp>&rsquo; or 
&lsquo;<samp>,</samp>&rsquo;); 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&mdash;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
+&lsquo;<samp>@0</samp>&rsquo; represents this time, 
&lsquo;<samp>@1</samp>&rsquo; 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 
&lsquo;<samp>@-1</samp>&rsquo;
+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 &lsquo;<samp>@915148799</samp>&rsquo; represents 
1998-12-31
+23:59:59 <small>UTC</small>, &lsquo;<samp>@915148800</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC123" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>TZ=&quot;<var>rule</var>&quot;</samp>&rsquo;.  The
+two quote characters (&lsquo;<samp>&quot;</samp>&rsquo;) 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 &ldquo;What time is it in New York when a Paris clock
+shows 6:30am on October 31, 2004?&rdquo; by using a date beginning with
+&lsquo;<samp>TZ=&quot;Europe/Paris&quot;</samp>&rsquo; as shown in the 
following shell transcript:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="example">$ export 
TZ=&quot;America/New_York&quot;
+$ date --date='TZ=&quot;Europe/Paris&quot; 2004-10-31 06:30'
+Sun Oct 31 01:30:00 EDT 2004
+</pre></td></tr></table>
+
+<p>In this example, the &lsquo;<samp>--date</samp>&rsquo; operand begins with 
its own
+<code>TZ</code> setting, so the rest of that operand is processed according
+to &lsquo;<samp>Europe/Paris</samp>&rsquo; rules, treating the string 
&lsquo;<samp>2004-10-31
+06:30</samp>&rsquo; 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";>&lsquo;<samp>tz</samp>&rsquo; 
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.,
+&lsquo;<samp>TZ=&quot;:America/New_York&quot;</samp>&rsquo;.
+</p>
+<p>The &lsquo;<samp>tz</samp>&rsquo; database includes a wide variety of 
locations ranging
+from &lsquo;<samp>Arctic/Longyearbyen</samp>&rsquo; to 
&lsquo;<samp>Antarctica/South_Pole</samp>&rsquo;, 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 
&lsquo;<samp>tz</samp>&rsquo;
+database, you may need to use a <acronym>POSIX</acronym> rule instead.  Simple
+<acronym>POSIX</acronym> rules like &lsquo;<samp>UTC0</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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&ccedil;ois Pinard
+(<a href="mailto:address@hidden";>address@hidden</a>) from the 
&lsquo;<tt>getdate.y</tt>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC125" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC113" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>gnu</samp>&rsquo; 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&ouml;rg Schilling <code>star</code>
+implementation.  <acronym>GNU</acronym> <code>tar</code> is able to read 
&lsquo;<samp>star</samp>&rsquo; 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 &lsquo;<samp>ustar</samp>&rsquo; archives will be 
able to read
+most &lsquo;<samp>posix</samp>&rsquo; 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 &lsquo;<samp>gnu</samp>&rsquo; format, however, future 
version will
+switch to &lsquo;<samp>posix</samp>&rsquo;.
+</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC126" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC127" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>-z</samp>&rsquo; 
(&lsquo;<samp>--gzip</samp>&rsquo;) to
+create a <code>gzip</code> compressed archive, &lsquo;<samp>-j</samp>&rsquo;
+(&lsquo;<samp>--bzip2</samp>&rsquo;) to create a <code>bzip2</code> compressed 
archive, and
+&lsquo;<samp>-Z</samp>&rsquo; (&lsquo;<samp>--compress</samp>&rsquo;) to use 
<code>compress</code> program.
+For example:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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 (&lsquo;<samp>--update</samp>&rsquo; 
(&lsquo;<samp>-u</samp>&rsquo;)) them or delete
+(&lsquo;<samp>--delete</samp>&rsquo;) members from them.  Likewise, you cannot 
append
+another <code>tar</code> archive to a compressed archive using
+&lsquo;<samp>--append</samp>&rsquo; (&lsquo;<samp>-r</samp>&rsquo;)).  
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> &lsquo;<samp>-z</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--gzip</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--ungzip</samp>&rsquo;</dt>
+<dd><p>Filter the archive through <code>gzip</code>.
+</p>
+<p>You can use &lsquo;<samp>--gzip</samp>&rsquo; and 
&lsquo;<samp>--gunzip</samp>&rsquo; 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>&nbsp;</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 &lsquo;<samp>--gzip</samp>&rsquo; 
(&lsquo;<samp>--gunzip</samp>&rsquo;, &lsquo;<samp>--ungzip</samp>&rsquo;, 
&lsquo;<samp>-z</samp>&rsquo;) option and run
+<code>gzip</code> explicitly:
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">$ <kbd>tar cf - subdir 
| gzip --best -c - &gt; 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> &lsquo;<samp>-j</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--bzip2</samp>&rsquo;</dt>
+<dd><p>Filter the archive through <code>bzip2</code>.  Otherwise like 
&lsquo;<samp>--gzip</samp>&rsquo;.
+</p>
+<a name="IDX394"></a>
+<a name="IDX395"></a>
+</dd>
+<dt> &lsquo;<samp>-Z</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--compress</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--uncompress</samp>&rsquo;</dt>
+<dd><p>Filter the archive through <code>compress</code>.  Otherwise like 
&lsquo;<samp>--gzip</samp>&rsquo;.
+</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> &lsquo;<samp>--use-compress-program=<var>prog</var></samp>&rsquo;</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 &lsquo;<samp>-d</samp>&rsquo; 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 &lsquo;<samp>--use-compress-program</samp>&rsquo; 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 &mdash;- encryption and 
signing tool' in <cite>GNU Privacy Guard Manual</cite>).  The following script 
does that:  
+</p>
+<table><tr><td>&nbsp;</td><td><pre class="smallexample">#! /bin/sh
+case $1 in
+-d) gpg --decrypt - | gzip -d -c;;
+'') gzip -c | gpg -s ;;
+*)  echo &quot;Unknown option $1&quot;&gt;&amp;2; exit 1;;
+esac
+</pre></td></tr></table>
+
+<p>Suppose you name it &lsquo;<tt>gpgz</tt>&rsquo; 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>&nbsp;</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>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--sparse</samp>&rsquo;
+(&lsquo;<samp>-S</samp>&rsquo;).  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 &ldquo;real contents&rdquo; of the file.  On
+extraction (using &lsquo;<samp>--sparse</samp>&rsquo; is not needed on 
extraction) any
+such files have holes created wherever the continuous stretches of zeros
+were found.  Thus, if you use &lsquo;<samp>--sparse</samp>&rsquo;, 
<code>tar</code> archives
+won't take more space than the original.
+</p>
+<dl compact="compact">
+<dd><a name="IDX400"></a>
+</dd>
+<dt> &lsquo;<samp>-S</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--sparse</samp>&rsquo;</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 &lsquo;<samp>--sparse</samp>&rsquo; 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 &lsquo;<samp>--sparse</samp>&rsquo; 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 &lsquo;<samp>--sparse</samp>&rsquo; 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 &lsquo;<samp>POSIX</samp>&rsquo; 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 &lsquo;<samp>1.0</samp>&rsquo; is used.  If, for some reason, 
you wish to
+use an earlier format, you can select it using
+&lsquo;<samp>--sparse-version</samp>&rsquo; option. 
+</p>
+<dl compact="compact">
+<dd><a name="IDX402"></a>
+</dd>
+<dt> &lsquo;<samp>--sparse-version=<var>version</var></samp>&rsquo;</dt>
+<dd>
+<p>Select the format to store sparse files in.  Valid <var>version</var> values
+are: &lsquo;<samp>0.0</samp>&rsquo;, &lsquo;<samp>0.1</samp>&rsquo; and 
&lsquo;<samp>1.0</samp>&rsquo;.  See section <a href="#SEC165">Storing Sparse 
Files</a>,
+for a detailed description of each format.
+</p></dd>
+</dl>
+
+<p>Using &lsquo;<samp>--sparse-format</samp>&rsquo; option implies 
&lsquo;<samp>--sparse</samp>&rsquo;.
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--atime-preserve[=METHOD]</samp>&rsquo; 
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> &lsquo;<samp>--atime-preserve</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--atime-preserve=replace</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--atime-preserve=system</samp>&rsquo;</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>&lsquo;<samp>--atime-preserve=replace</samp>&rsquo; 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>&lsquo;<samp>--atime-preserve=system</samp>&rsquo; 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 &lsquo;<samp>--atime-preserve</samp>&rsquo; with no operand 
defaults to
+&lsquo;<samp>--atime-preserve=replace</samp>&rsquo;, but this is intended to 
change to
+&lsquo;<samp>--atime-preserve=system</samp>&rsquo; when the latter is 
better-supported.
+</p>
+<a name="IDX404"></a>
+</dd>
+<dt> &lsquo;<samp>-m</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--touch</samp>&rsquo;</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 &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;).
+</p>
+<a name="IDX405"></a>
+</dd>
+<dt> &lsquo;<samp>--same-owner</samp>&rsquo;</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 &lsquo;<tt>/etc/passwd</tt>&rsquo;), then it does not write one.  When 
restoring,
+it tries to look the name (if one was written) up in
+&lsquo;<tt>/etc/passwd</tt>&rsquo;.  If it fails, then it uses the user id 
stored in
+the archive instead. 
+</p>
+<a name="IDX406"></a>
+</dd>
+<dt> &lsquo;<samp>--no-same-owner</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>-o</samp>&rsquo;</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> &lsquo;<samp>--numeric-owner</samp>&rsquo;</dt>
+<dd><p>The &lsquo;<samp>--numeric-owner</samp>&rsquo; 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 &lsquo;<samp>--old-archive</samp>&rsquo; 
(&lsquo;<samp>-o</samp>&rsquo;) 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> &lsquo;<samp>-p</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--same-permissions</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--preserve-permissions</samp>&rsquo;</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 &lsquo;<samp>--list</samp>&rsquo; 
(&lsquo;<samp>-t</samp>&rsquo;).
+</p>
+<a name="IDX410"></a>
+</dd>
+<dt> &lsquo;<samp>--preserve</samp>&rsquo;</dt>
+<dd><p>Same as both &lsquo;<samp>--same-permissions</samp>&rsquo; and 
&lsquo;<samp>--same-order</samp>&rsquo;.
+</p>
+<p>The &lsquo;<samp>--preserve</samp>&rsquo; option has no equivalent short 
option name.
+It is equivalent to &lsquo;<samp>--same-permissions</samp>&rsquo; plus 
&lsquo;<samp>--same-order</samp>&rsquo;.
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC130" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC131" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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, &lsquo;<samp>/</samp>&rsquo;, 
&lsquo;<samp>.</samp>&rsquo;, &lsquo;<samp>_</samp>&rsquo;, and
+&lsquo;<samp>-</samp>&rsquo;; it cannot be empty, start with 
&lsquo;<samp>-</samp>&rsquo; or &lsquo;<samp>//</samp>&rsquo;, or
+contain &lsquo;<samp>/-</samp>&rsquo;.  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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC132" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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.
+&lsquo;<samp>--dereference</samp>&rsquo; (&lsquo;<samp>-h</samp>&rsquo;) is 
used with &lsquo;<samp>--create</samp>&rsquo; (&lsquo;<samp>-c</samp>&rsquo;), 
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 &lsquo;<samp>--dereference</samp>&rsquo; 
(&lsquo;<samp>-h</samp>&rsquo;): 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC133" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--format=v7</samp>&rsquo; option in
+conjunction with the &lsquo;<samp>--create</samp>&rsquo; 
(&lsquo;<samp>-c</samp>&rsquo;) (<code>tar</code> also
+accepts &lsquo;<samp>--portability</samp>&rsquo; or 
&lsquo;<samp>--old-archive</samp>&rsquo; 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 &lsquo;<samp>--format=v7</samp>&rsquo;
+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 &lsquo;<samp>--format=v7</samp>&rsquo; for your distributions.  
Notice,
+however, that &lsquo;<samp>ustar</samp>&rsquo; format is a better alternative, 
as it is
+free from many of &lsquo;<samp>v7</samp>&rsquo;'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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC134" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 
&lsquo;<samp>--format=ustar</samp>&rsquo;
+option in conjunction with the &lsquo;<samp>--create</samp>&rsquo; 
(&lsquo;<samp>-c</samp>&rsquo;).
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC135" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>POSIX</samp>&rsquo; format the default.
+</p>
+<p>To force creation a <acronym>GNU</acronym> <code>tar</code> archive, use 
option
+&lsquo;<samp>--format=gnu</samp>&rsquo;.
+</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC136" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>--format=posix</samp>&rsquo; 
(&lsquo;<samp>--format=pax</samp>&rsquo;) 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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC137" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>--pax-option=<var>keyword-list</var></samp>&rsquo;</dt>
+<dd><p>Handle keywords in <acronym>PAX</acronym> extended headers.  This 
option is
+equivalent to &lsquo;<samp>-o</samp>&rsquo; 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>&nbsp;</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 &lsquo;<samp>%</samp>&rsquo; character.
+</p></td></tr>
+</table>
+
+<p>Any other &lsquo;<samp>%</samp>&rsquo; characters in <var>string</var> 
produce undefined
+results.
+</p>
+<p>If no option &lsquo;<samp>exthdr.name=string</samp>&rsquo; is specified, 
<code>tar</code>
+will use the following default value:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>%</samp>&rsquo; character.
+</p></td></tr>
+</table>
+
+<p>Any other &lsquo;<samp>%</samp>&rsquo; characters in <var>string</var> 
produce undefined results.
+</p>
+<p>If no option &lsquo;<samp>globexthdr.name=string</samp>&rsquo; is 
specified, <code>tar</code>
+will use the following default value:
+</p>
+<table><tr><td>&nbsp;</td><td><pre 
class="smallexample">$TMPDIR/GlobalHead.%p.%n
+</pre></td></tr></table>
+
+<p>where &lsquo;<samp>$TMPDIR</samp>&rsquo; represents the value of the 
<var>TMPDIR</var>
+environment variable.  If <var>TMPDIR</var> is not set, <code>tar</code>
+uses &lsquo;<samp>/tmp</samp>&rsquo;.
+</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>&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC138" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC139" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>oldest 
possible</samp>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC140" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC141" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<tt>vol-1.tar</tt>&rsquo; to &lsquo;<tt>vol-2.tar</tt>&rsquo;, you can 
do the following to
+extract them using a third-party <code>tar</code>:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</td><td><pre 
class="smallexample">%d/GNUFileParts.%p/%f.%n
+</pre></td></tr></table>
+
+<p>where symbols preceeded by &lsquo;<samp>%</samp>&rsquo; 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 &lsquo;<tt>var/longfile</tt>&rsquo; was split 
during archive
+creation between three volumes, and the creator <code>tar</code> process
+had process ID &lsquo;<samp>27962</samp>&rsquo;, then the member names will be:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</td><td><pre class="smallexample">$ <kbd>cd var</kbd>
+$ <kbd>cat GNUFileParts.27962/longfile.1 \
+  GNUFileParts.27962/longfile.2 &gt;&gt; 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>&nbsp;</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>&nbsp;</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 &lsquo;<tt>PaxHeaders.*</tt>&rsquo; 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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC142" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt><var>dir</var>/<var>name</var></tt>&rsquo;, then the 
condensed file will be
+named 
&lsquo;<tt><var>dir</var>/GNUSparseFile.<var>n</var>/<var>name</var></tt>&rsquo;,
 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>&nbsp;</td><td><pre class="smallexample">$ <kbd>xsparse 
&lsquo;<tt>cond-file</tt>&rsquo;</kbd>
+</pre></td></tr></table>
+
+<p>where &lsquo;<tt>cond-file</tt>&rsquo; 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 &lsquo;<tt>cond-file</tt>&rsquo; does not contain any directories,
+&lsquo;<tt>../cond-file</tt>&rsquo; will be used;
+
+</li><li> If &lsquo;<tt>cond-file</tt>&rsquo; has the form
+&lsquo;<tt><var>dir</var>/<var>t</var>/<var>name</var></tt>&rsquo;, where both 
<var>t</var> and <var>name</var>
+are simple names, with no &lsquo;<samp>/</samp>&rsquo; characters in them, the 
output file
+name will be &lsquo;<tt><var>dir</var>/<var>name</var></tt>&rsquo;.
+
+</li><li> Otherwise, if &lsquo;<tt>cond-file</tt>&rsquo; has the form
+&lsquo;<tt><var>dir</var>/<var>name</var></tt>&rsquo;, the output file name 
will be
+&lsquo;<tt><var>name</var></tt>&rsquo;.
+</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>&nbsp;</td><td><pre class="smallexample">$ <kbd>xsparse 
&lsquo;<tt>cond-file</tt>&rsquo;</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 &lsquo;<samp>-n</samp>&rsquo; command line argument:
+</p>
+<table><tr><td>&nbsp;</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>&nbsp;</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 &lsquo;<samp>-v</samp>&rsquo; 
option:
+</p>
+<table><tr><td>&nbsp;</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 &lsquo;<samp>-x</samp>&rsquo; sets the name of the extended header 
file to
+use.  Continuing our example:
+</p>
+<table><tr><td>&nbsp;</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
+&lsquo;<tt><var>dir</var>/<var>name</var></tt>&rsquo;, then the extended 
header file will be
+named 
&lsquo;<tt><var>dir</var>/PaxHeaders.<var>n</var>/<var>name</var></tt>&rsquo;, 
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 
&lsquo;<samp>-R</samp>&rsquo; option).  For example,
+<code>star</code> has &lsquo;<samp>-block-number</samp>&rsquo;.
+
+</li><li>
+Obtain the verbose listing using the &lsquo;<samp>block number</samp>&rsquo; 
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>&nbsp;</td><td><pre class="smallexample">$ <kbd>star -t -v 
-block-number -f arc.tar</kbd>
+&hellip;
+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
+&hellip;
+</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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;</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,&hellip;
+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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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&amp;T (and which is, I think, also
+present in the <code>cpio</code> that Berkeley picked up from AT&amp;T and put
+into a later BSD release&mdash;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 
&quot;binary&quot;
+format, i-numbers are only 16 bits, and in its &quot;portable ASCII&quot; 
format,
+they're 18 bits&mdash;it would have to play games with the &quot;file system 
ID&quot;
+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&amp;T</em>
+had <code>tar</code>, or, if so, whether the people within AT&amp;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 &lsquo;<samp>dd 
skip=<var>nn</var></samp>&rsquo;.
+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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC144" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC124" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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&mdash;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&mdash;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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC147">9.4 
Blocking</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC159">9.9 Write 
Protection</a></td><td>&nbsp;&nbsp;</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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC145" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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> &lsquo;<samp>-f [<var>hostname</var>:]<var>file</var></samp>&rsquo;</dt>
+<dt> 
&lsquo;<samp>--file=[<var>hostname</var>:]<var>file</var></samp>&rsquo;</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 &lsquo;<samp>-</samp>&rsquo;, <code>tar</code> reads 
the archive from standard
+input (when listing or extracting), or writes it to standard output
+(when creating).  If the &lsquo;<samp>-</samp>&rsquo; 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 &lsquo;<samp>:</samp>&rsquo;, it is interpreted 
as
+&lsquo;<samp>hostname:file name</samp>&rsquo;.  If the <var>hostname</var> 
contains an <em>at</em>
+sign (&lsquo;<samp>@</samp>&rsquo;), it is treated as 
&lsquo;<samp>address@hidden:file name</samp>&rsquo;.  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 &lsquo;<tt><var>prefix</var>/libexec/rmt</tt>&rsquo;, where 
<var>prefix</var> stands for
+your installation prefix.  This location may also be overridden at
+runtime by using &lsquo;<samp>rmt-command=<var>command</var></samp>&rsquo; 
option (See section <a href="#SEC42">&mdash;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&mdash;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 &lsquo;<samp>/dev/tape</samp>&rsquo; 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 &lsquo;<samp>DEFTAPE</samp>&rsquo; in
+&lsquo;<tt>&lt;sys/mtio.h&gt;</tt>&rsquo;.
+</p>
+<dl compact="compact">
+<dd><a name="IDX417"></a>
+</dd>
+<dt> &lsquo;<samp>--force-local</samp>&rsquo;</dt>
+<dd><p>Archive file is local even if it contains a colon.
+</p>
+<a name="IDX418"></a>
+</dd>
+<dt> &lsquo;<samp>--rsh-command=<var>command</var></samp>&rsquo;</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 &lsquo;<tt>/usr/ucb/rsh</tt>&rsquo;, 
&lsquo;<tt>/usr/bin/remsh</tt>&rsquo;,
+&lsquo;<tt>/usr/bin/rsh</tt>&rsquo;, &lsquo;<tt>/usr/bsd/rsh</tt>&rsquo; or 
&lsquo;<tt>/usr/bin/nsh</tt>&rsquo;.
+The installer may have overridden this by defining the environment
+variable <code>RSH</code> <em>at installation time</em>.
+</p>
+</dd>
+<dt> &lsquo;<samp>-[0-7][lmh]</samp>&rsquo;</dt>
+<dd><p>Specify drive and density.
+</p>
+<a name="IDX419"></a>
+</dd>
+<dt> &lsquo;<samp>-M</samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--multi-volume</samp>&rsquo;</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&mdash;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> &lsquo;<samp>-L <var>num</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--tape-length=<var>num</var></samp>&rsquo;</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> &lsquo;<samp>-F <var>file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--info-script=<var>file</var></samp>&rsquo;</dt>
+<dt> &lsquo;<samp>--new-volume-script=<var>file</var></samp>&rsquo;</dt>
+<dd><p>Execute &lsquo;<tt>file</tt>&rsquo; at end of each tape.  This implies
+&lsquo;<samp>--multi-volume</samp>&rsquo; (&lsquo;<samp>-M</samp>&rsquo;).  
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"> &lt; </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC146" title="Next section in 
reading order"> &gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left">[<a href="#SEC143" title="Beginning of this 
chapter or previous chapter"> &lt;&lt; </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"> 
&gt;&gt; </a>]</td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </td>
+<td valign="middle" align="left"> &nbsp; </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
+&lsquo;<tt><var>prefix</var>/libexec/rmt</tt>&rsquo; 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 &copy; 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 &lsquo;<samp>--absolute-names</samp>&rsquo; 
(&lsquo;<samp>-P</samp>&rsquo;) 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 &lsquo;<samp>/</samp>&rsquo;.) 
If you try,
+<code>tar</code> will automatically remove the leading 
&lsquo;<samp>/</samp>&rsquo; 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 &lsquo;<tt>/bin</tt>&rsquo; 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 
&lsquo;<tt>/usr/bin/computoy</tt>&rsquo;,
+<acronym>GNU</acronym> <code>tar</code> would extract the file to 
&lsquo;<tt>usr/bin/computoy</tt>&rsquo;,
+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 &lsquo;<samp>cd /</samp>&rsquo; before extracting 
the files
+from the archive, or you should either use the 
&lsquo;<samp>--absolute-names</samp>&rsquo;
+option, or use the command &lsquo;<samp>tar -C / &hellip;</samp>&rsquo;.
+</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 
&lsquo;<samp>lseek</samp>&rsquo;),
+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 &lsquo;<samp>--append</samp>&rsquo;, 
&lsquo;<samp>--concatenate</samp>&rsquo;, and
+&lsquo;<samp>--delete</samp>&rsquo; commands will not work on any other kind 
of file.
+Some media simply cannot be backspaced, which means these commands and
+op