Documented --pax-option

NEWS

@@ -1,5 +1,5 @@
 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.
 
@@ -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.
 
+* 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

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.
 
+@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 gnu
-Creates archive in GNU format.
 @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.
 
+@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}.

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\
+                                     gnu       GNU tar 1.13 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\
+  --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\
@@ -1285,9 +1287,11 @@ see the file named COPYING for details."));
     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));
@@ -1296,7 +1300,7 @@ see the file named COPYING for details."));
     {
       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