Documented --pax-option

diff --git a/NEWS b/NEWS
index c132f62b60ec85b884d7cd4a9b091ba481a1a796..088fedbda06ad10913fb29b9a767600e902051d7 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,5 @@
 GNU tar NEWS - User visible changes.
 GNU tar NEWS - User visible changes.

-Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2003
+Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004

 Free Software Foundation, Inc.
 See the end for copying conditions.
 
 Free Software Foundation, Inc.
 See the end for copying conditions.
 


@@ -42,6 +42,10 @@ version 1.13.92
   extracts the first occurrence of `filename' from `archive'
   and terminates without scanning to the end of the archive.
 
   extracts the first occurrence of `filename' from `archive'
   and terminates without scanning to the end of the archive.
 

+* New option --pax-option allows to control the handling of POSIX
+  keywords in `pax' extended headers. It is equivalent to `pax'
+  -o option.
+  

 * Removed obsolete command line options:
 ** --absolute-paths superseded by --absolute-names
 ** --block-compress is not needed any longer
 * Removed obsolete command line options:
 ** --absolute-paths superseded by --absolute-names
 ** --block-compress is not needed any longer

diff --git a/doc/tar.texi b/doc/tar.texi
index b57028b515d07a45cea27ecfad2db21c4d453d5a..359d18774cbf0c4f1f78741f6bc50917a714d231 100644 (file)
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -2726,14 +2726,17 @@ Creates an archive that is compatible with Unix V7 @command{tar}.
 Creates an archive that is compatible with GNU @command{tar} version
 1.12 or earlier.
 
 Creates an archive that is compatible with GNU @command{tar} version
 1.12 or earlier.
 

+@item gnu
+Creates archive in GNU tar 1.13 format. Basically it is the same as
+@samp{oldgnu} with the only difference in the way it handles long
+numeric fields.
+

 @item ustar
 Creates a POSIX.1-1988 compatible archive.
 
 @item posix
 Creates a POSIX.1-2001 archive.
 
 @item ustar
 Creates a POSIX.1-1988 compatible archive.
 
 @item posix
 Creates a POSIX.1-2001 archive.
 

-@item gnu
-Creates archive in GNU format.

 @end table
 
 @item --group=@var{group}
 @end table
 
 @item --group=@var{group}


@@ -2985,6 +2988,117 @@ anonymous anyway, so that might as well be the owner of anonymous archives.
 
 This option does not affect extraction from archives.
 
 
 This option does not affect extraction from archives.
 

+@item --pax-option=@var{keyword-list}
+
+This option is meaningful only with POSIX.1-2001 archives
+(@FIXME-xref{}). It modifies the way @command{tar} handles the
+extended header keywords. @var{Keyword-list} is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+
+@table @asis
+@item delete=@var{pattern}
+When used with one of archive-creation command (@FIXME-xref{}),
+this option instructs @command{tar} to omit from extended header records
+that it produces any keywords matching the string @var{pattern}.
+
+When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given @var{pattern} in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in POSIX 1003.2, 3.13 (@FIXME-xref{}, see
+man 7 glob). For example:
+
+@smallexample
+--pax-option delete=security.*
+@end smallexample
+
+would suppress security-related information.
+
+@item exthdr.name=@var{string}
+
+This keyword allows user control over the name that is written into the
+ustar header blocks for the extended headers. The name is obtained
+from @var{string} after substituting the following meta-characters:
+
+@multitable @columnfractions .30 .70
+@item Meta-character @tab Replaced By
+@item %d @tab  The directory name of the file, equivalent to the
+result of the @command{dirname} utility on the translated pathname.
+@item %f @tab  The filename of the file, equivalent to the result
+of the @command{basename} utility on the translated pathname.
+@item %p @tab  The process ID of the @command{tar} process.
+@item %% @tab  A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in @var{string} produce undefined
+results.
+
+If no option @samp{exthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@c This should be %d/PaxHeaders.%p/%f
+@smallexample
+././@@PaxHeader
+@end smallexample
+
+@item globexthdr.name=@var{string}
+This keyword allows user control over the name that is written into
+the ustar header blocks for global extended header records. The name
+shall will be obtained from the contents of @var{string}, after the
+following character substitutions have been made:
+
+@multitable @columnfractions .30 .70
+@item Meta-character @tab Replaced By
+@item %n @tab An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
+@item %p @tab The process ID of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in string produce undefined results.
+
+If no option @samp{globexthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+$TMPDIR/GlobalHead.%p.%n
+@end smallexample
+
+@noindent
+where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
+environment variable. If @var{TMPDIR} is not set, @command{tar}
+uses @samp{/tmp}.
+
+@item @var{keyword}=@var{value}
+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,
+@command{tar} will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+
+@item @var{keyword}:=@var{value}
+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{value}
+form except that it creates no global extended header records.
+
+When used with one of archive-reading commands, @command{tar} will
+behave as if these keyword/value pairs were included as records at the
+end of each extended header; thus, they will override any global or
+file-specific extended header record keywords of the same names.
+For example, in the command:
+
+@smallexample
+tar --format=posix --create \
+    --file archive --pax-option gname:=user .
+@end smallexample
+
+the group name will be forced to a new value for all files
+stored in the archive.
+@end table
+

 @item --portability
 @itemx --old-archive
 Synonym for @option{--format=v7}.
 @item --portability
 @itemx --old-archive
 Synonym for @option{--format=v7}.

diff --git a/src/tar.c b/src/tar.c
index 80091fa2053680e55a0bdcc863e883b71f5831c0..5b960ac54d8a5893ea4cb9d56dbc49d50b2c3395 100644 (file)
--- a/src/tar.c
+++ b/src/tar.c
@@ -445,11 +445,13 @@ Archive format selection:\n\
                                      FMTNAME is one of the following:\n\
                                      v7        old V7 tar format\n\
                                      oldgnu    GNU format as per tar <= 1.12\n\
                                      FMTNAME is one of the following:\n\
                                      v7        old V7 tar format\n\
                                      oldgnu    GNU format as per tar <= 1.12\n\

+                                     gnu       GNU tar 1.13 format\n\

                                      ustar     POSIX 1003.1-1988 (ustar) format\n\
                                      posix     POSIX 1003.1-2001 (pax) format\n\
                                      ustar     POSIX 1003.1-1988 (ustar) format\n\
                                      posix     POSIX 1003.1-2001 (pax) format\n\

-                                     gnu       GNU format\n\

       --old-archive, --portability   same as --format=v7\n\
       --posix                        same as --format=posix\n\
       --old-archive, --portability   same as --format=v7\n\
       --posix                        same as --format=posix\n\

+  --pax-option keyword[[:]=value][,keyword[[:]=value], ...]\n\
+                                     control pax keywords\n\

   -V, --label=NAME                   create archive with volume name NAME\n\
               PATTERN                at list/extract time, a globbing PATTERN\n\
   -j, --bzip2                        filter the archive through bzip2\n\
   -V, --label=NAME                   create archive with volume name NAME\n\
               PATTERN                at list/extract time, a globbing PATTERN\n\
   -j, --bzip2                        filter the archive through bzip2\n\


@@ -1285,9 +1287,11 @@ see the file named COPYING for details."));
     assert_format (FORMAT_MASK (OLDGNU_FORMAT)
                   | FORMAT_MASK (GNU_FORMAT));
 
     assert_format (FORMAT_MASK (OLDGNU_FORMAT)
                   | FORMAT_MASK (GNU_FORMAT));
 

-  if (incremental_option
-      || multi_volume_option
-      || sparse_option)
+  if (incremental_option || multi_volume_option)
+    assert_format (FORMAT_MASK (OLDGNU_FORMAT) | FORMAT_MASK (GNU_FORMAT));
+                  
+  
+  if (sparse_option)

     assert_format (FORMAT_MASK (OLDGNU_FORMAT)
                   | FORMAT_MASK (GNU_FORMAT)
                   | FORMAT_MASK (POSIX_FORMAT));
     assert_format (FORMAT_MASK (OLDGNU_FORMAT)
                   | FORMAT_MASK (GNU_FORMAT)
                   | FORMAT_MASK (POSIX_FORMAT));


@@ -1296,7 +1300,7 @@ see the file named COPYING for details."));
     {
       if (!input_files && !files_from_option)
        USAGE_ERROR ((0, 0,
     {
       if (!input_files && !files_from_option)
        USAGE_ERROR ((0, 0,

-                     _("--occurrence is meaningless without file list")));
+                     _("--occurrence is meaningless without a file list")));

       if (subcommand_option != DELETE_SUBCOMMAND
          && subcommand_option != DIFF_SUBCOMMAND
          && subcommand_option != EXTRACT_SUBCOMMAND
       if (subcommand_option != DELETE_SUBCOMMAND
          && subcommand_option != DIFF_SUBCOMMAND
          && subcommand_option != EXTRACT_SUBCOMMAND