@set op-format-gnu @kbd{--format=gnu}
@set op-format-oldgnu @kbd{--format=oldgnu}
@set op-format-posix @kbd{--format=posix}
+@set op-format-ustar @kbd{--format=ustar}
@set op-posix @kbd{--posix}
@set ref-posix @ref{posix}
@dircategory Individual utilities
@direntry
-* tar: (tar)tar invocation. Invoking @GNUTAR{}
+* tar: (tar)tar invocation. Invoking @GNUTAR{}.
@end direntry
@shorttitlepage @acronym{GNU} @command{tar}
* Definitions:: Some Definitions
* What tar Does:: What @command{tar} Does
* Naming tar Archives:: How @command{tar} Archives are Named
-* posix compliance::
* Current status:: Current development status of @GNUTAR{}
* Authors:: @GNUTAR{} Authors
* Reports:: Reporting bugs or suggestions
* Definitions:: Some Definitions
* What tar Does:: What @command{tar} Does
* Naming tar Archives:: How @command{tar} Archives are Named
-* posix compliance::
* Current status:: Current development status of @GNUTAR{}
* Authors:: @GNUTAR{} Authors
* Reports:: Reporting bugs or suggestions
this manual, we consistently refer to ``archives'' and ``archive
members'' to make learning to use @command{tar} easier for novice users.
-@node posix compliance
-@section @sc{posix} Compliance
-
-@noindent
-@FIXME{must ask franc,ois about this. dan hagerty thinks this might
-be an issue, but we're not really sure at this time. dan just tried a
-test case of mixing up options' orders while the variable was set, and
-there was no problem...}
-@FIXME{I did not notice any problems either. Besides, the only piece
-of code that really uses POSIXLY_CORRECT is the one that forces
-creation of POSIX archives. I guess this paragraph should be removed.
-
---gray}
-
-
-We make some of our recommendations throughout this book for one
-reason in addition to what we think of as ``good sense''. The main
-additional reason for a recommendation is to be compliant with the
-@sc{posix} standards. If you set the shell environment variable
-@env{POSIXLY_CORRECT}, @GNUTAR{} will force you to
-adhere to these standards. Therefore, if this variable is set and you
-violate one of the @sc{posix} standards in the way you phrase a
-command, for example, @GNUTAR{} will not allow the
-command and will signal an error message. You would then have to
-reorder the options or rephrase the command to comply with the
-@sc{posix} standards.
-
-Notice also, that if this environment variable is set, @GNUTAR{}
-will create @acronym{POSIX} archives. Currently this means that
-no @acronym{GNU} extensions will be allowed (@pxref{posix}).
-
@node Current status
@section Current development status of @GNUTAR{}
@table @asis
@item Use of short option @option{-o}.
Earlier versions of @GNUTAR{} understood @option{-o} command line
-option as a synonim for @option{--old-archive}.
+option as a synonym for @option{--old-archive}.
@GNUTAR{} starting from version 1.13.90 understands this option as
-a synonim for @option{--no-same-owner}. This is compatible with
+a synonym for @option{--no-same-owner}. This is compatible with
UNIX98 @command{tar} implementations.
However, to facilitate transition, @option{-o} option retains its
Users are encouraged to use @value{op-format-oldgnu} instead.
Future versions of @GNUTAR{} will understand @option{-o} only as a
-synonim for @option{--no-same-owner}.
+synonym for @option{--no-same-owner}.
@item Use of short option @option{-l}
Earlier versions of @GNUTAR{} understood @option{-l} option as a
-synonim for @samp{--one-file-system}. Such usage is deprecated.
-For compatiblity with other implementations future versions of
-@GNUTAR{} will understand this option as a synonim for
+synonym for @samp{--one-file-system}. Such usage is deprecated.
+For compatibility with other implementations future versions of
+@GNUTAR{} will understand this option as a synonym for
@option{--check-links}.
@item Use of options @option{--portability} and @option{--old-archive}
consulting. In particular, he is the primary author of @ref{Backups}.
In July, 2003 @GNUTAR{} was put on CVS at @url{savannah.gnu.org}, and
-an active development and maintainance work has started
+an active development and maintenance work has started
again. Currently @GNUTAR{} is being maintained by Paul Eggert, Sergey
Poznyakoff and Jeff Bailey.
does what, and therefore where different names have to be placed.
(Placing options in an unusual order can also cause @command{tar} to
report an error if you have set the shell environment variable
-@env{POSIXLY_CORRECT}; @pxref{posix compliance} for more information
-on this.)
+@env{POSIXLY_CORRECT}.)
@node create dir
@subsection Archiving Directories
@node Mnemonic Options
@subsection Mnemonic Option Style
-@FIXME{have to decide whether or ot to replace other occurrences of
+@FIXME{have to decide whether or not to replace other occurrences of
"mnemonic" with "long", or *ugh* vice versa.}
Each option has at least one long (or mnemonic) name starting with two
@table @samp
@item v7
-Tells @command{tar} to create an archive that is compatible with Unix V7
-@command{tar}.
+Creates an archive that is compatible with Unix V7 @command{tar}.
@item oldgnu
-Tells @command{tar} to create 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
-Tells @command{tar} to create POSIX.1-2001 archive.
+Creates a POSIX.1-2001 archive.
-@item gnu
-Tells @command{tar} to create archive in GNU format.
@end table
@item --group=@var{group}
@FIXME-xref{}
@item -o
-When extracting files, this option is a synonim for
+When extracting files, this option is a synonym for
@option{--no-same-owner}, i.e. it prevents @command{tar} from
restoring ownership of files being extracted.
-When creating an archive, @option{-o} is a synonim for
+When creating an archive, @option{-o} is a synonym for
@option{--old-archive}. This behavior is for compatibility
with previous versions of @GNUTAR{}, and will be
removed in the future releases.
and will terminate without scanning to the end of the archive.
@item --old-archive
-Synonim for @option{--format=v7}.
+Synonym for @option{--format=v7}.
@item --one-file-system
@itemx -l
directory.
Earlier versions of @GNUTAR{} understood @option{-l} as a
-synonim for @option{--one-file-system}. Although such usage is still
+synonym for @option{--one-file-system}. Although such usage is still
allowed in the present version, it is @emph{strongly discouraged}.
The future versions of @GNUTAR{} will use @option{-l} as
-a synonim for @option{--check-links}.
+a synonym for @option{--check-links}.
@xref{Current status}, for more information.
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:
+
+@smallexample
+%d/PaxHeaders.%p/%f
+@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
-Synonim for @option{--format=v7}.
+Synonym for @option{--format=v7}.
@item --posix
Same as @option{--format=posix}.
@smallexample
$ @kbd{tar --extract --file=archive.tar --verbose --verbose}
-$ @kbd{tar xvv archive.tar}
+$ @kbd{tar xvvf archive.tar}
@end smallexample
Verbose output appears on the standard output except when an archive is
@item
Mistakingly using @code{create} instead of @code{extract}, when the
intent was to extract the full contents of an archive. This error
-is likely: keys @kbd{c} and @kbd{x} are right next ot each other on
+is likely: keys @kbd{c} and @kbd{x} are right next to each other on
the QWERTY keyboard. Instead of being unpacked, the archive then
gets wholly destroyed. When users speak about @dfn{exploding} an
archive, they usually mean something else :-).
arguments to @command{tar} (this can help you save time if you expect to
archive the same list of files a number of times), and so forth.
@FIXME{in case it's not obvious, i'm making this up in some sense
-based on my imited memory of what the next chapter *really* does. i
+based on my limited memory of what the next chapter *really* does. i
just wanted to flesh out this final section a little bit so i'd
-remember to sitck it in here. :-)}
+remember to stick it in here. :-)}
If there are too many files to conveniently list on the command line,
you can list the names in a file, and @command{tar} will read that file.
to read and create archives conforming to @sc{posix.1-2001} standard.
A @sc{posix} conformant archive will be created if @command{tar}
-was given @value{op-format-posix} option, or if it was given
-@value{op-format-gnu} option and the environment variable
-@env{POSIXLY_CORRECT} is set. The later usage is retained for
-compatibility with previous versions of @GNUTAR{}
-and is discouraged.
-
+was given @value{op-format-posix} option.
Notice, that currently @acronym{GNU} extensions are not
-alowed with this format. Following is the list of options that
+allowed with this format. Following is the list of options that
cannot be used with @value{op-format-posix}:
@itemize @bullet
archive for the file where the consecutive stretches of zeros are, and
only archives the ``real contents'' of the file. On extraction (using
@value{op-sparse} is not needed on extraction) any such files have
-hols created wherever the continuous stretches of zeros were found.
+holes created wherever the continuous stretches of zeros were found.
Thus, if you use @value{op-sparse}, @command{tar} archives won't take
more space than the original.
Apparently, Exabyte drives have a physical block size of 8K bytes.
If we choose our blocksize as a multiple of 8k bytes, then the problem
-seems to dissapper. Id est, we are using block size of 112 right
+seems to disappear. Id est, we are using block size of 112 right
now, and we haven't had the problem since we switched@dots{}
With @GNUTAR{} the blocking factor is limited only