From: Sergey Poznyakoff Date: Fri, 20 Feb 2004 11:44:46 +0000 (+0000) Subject: Documented --pax-option X-Git-Url: https://git.dogcows.com/gitweb?a=commitdiff_plain;h=b58452bdbd7433cbbc5e5c0887ce846a2fa92f05;p=chaz%2Ftar Documented --pax-option --- diff --git a/NEWS b/NEWS index c132f62..088fedb 100644 --- a/NEWS +++ b/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 diff --git a/doc/tar.texi b/doc/tar.texi index b57028b..359d187 100644 --- 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. +@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}. diff --git a/src/tar.c b/src/tar.c index 80091fa..5b960ac 100644 --- 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\ + 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