@c do not alter them inconsiderately. Much work is needed for GNU tar
@c internals (the sources, the programs themselves). Revising the
@c adequacy of the manual while revising the sources, and cleaning them
-@c both at the same time, seems to him like a good way to proceed.
+@c both at the same time, is a good way to proceed.
@c ---------------------------------------------------------------------
@c Output marks for nodes needing revision, but not in PUBLISH rendition.
@set pxref-interactive @pxref{interactive}
@set op-keep-old-files @kbd{--keep-old-files} (@kbd{-k})
-@set ref-keep-old-files @ref{Writing}
-@set xref-keep-old-files @xref{Writing}
-@set pxref-keep-old-files @pxref{Writing}
+@set ref-keep-old-files @ref{Keep Old Files}
+@set xref-keep-old-files @xref{Keep Old Files}
+@set pxref-keep-old-files @pxref{Keep Old Files}
+
+@set op-keep-newer-files @kbd{--keep-old-files}
+@set ref-keep-newer-files @ref{Keep Newer Files}
+@set xref-keep-newer-files @xref{Keep Newer Files}
+@set pxref-keep-newer-files @pxref{Keep Newer Files}
@set op-label @kbd{--label=@var{archive-label}} (@kbd{-V @var{archive-label}})
@set ref-label @ref{label}
@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}
from archives.
Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003 Free Software Foundation, Inc.
+2003, 2004 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@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
* Dealing with Old Files::
* Overwrite Old Files::
* Keep Old Files::
+* Keep Newer Files::
* Unlink First::
* Recursive Unlink::
* Modification Times::
* Day of week items:: Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings:: 19931219, 1440.
-* Authors of getdate:: Bellovin, Eggert, Salz, Berets, et al.
+* Seconds since the Epoch:: @@1078100502.
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
Controlling the Archive Format
@chapter Introduction
@GNUTAR{} creates
-and manipulates (@dfn{archives}) which are actually collections of
+and manipulates @dfn{archives} 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 ``tar'' originally came from the phrase ``Tape ARchive'', but
* 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
In addition, one section of this manual (@pxref{Standard}) contains a
big quote which is taken directly from @command{tar} sources.
-In general, we give both the long and short (abbreviated) option names
+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
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{}
@item Improve compatibility between @GNUTAR{} and other @command{tar}
implementations.
@item Switch to using @acronym{POSIX} archives.
-@item Revise sparse file handling.
-@item Revise multiple volume processing.
+@item Revise sparse file handling and multiple volume processing.
+@item Merge with the @acronym{GNU} @code{paxutils} project.
@end itemize
-The following issues need mentioning:
+Some of these aims are already attained, while others are still
+being worked upon. From the point of view of an end user, the
+following issues need special mentioning:
@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
old semantics when it is used with one of archive-creation commands.
Users are encouraged to use @value{op-format-oldgnu} instead.
+It is especially important, since versions of @acronym{GNU} Automake
+up to and including 1.8.4 invoke tar with this option to produce
+distribution tarballs. @xref{Formats,v7}, for the detailed discussion
+of this issue and its implications.
+
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}
+
These options are deprecated. Please use @option{--format=v7} instead.
@item Use of option @option{--posix}
+
This option is deprecated. Please use @option{--format=posix} instead.
@end table
@GNUTAR{} was originally written by John Gilmore,
and modified by many people. The @acronym{GNU} enhancements were
written by Jay Fenlason, then Joy Kendall, and the whole package has
-been further maintained by Thomas Bushnell, n/BSG, and finally
-Fran@,{c}ois Pinard, with the help of numerous and kind users.
+been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois
+Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
+numerous and kind users.
We wish to stress that @command{tar} is a collective work, and owes much to
all those people who reported problems, offered solutions and other
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.
If you find problems or have suggestions about this program or manual,
please report them to @file{bug-tar@@gnu.org}.
+When reporting a bug, please be sure to include as much detail as
+possible, in order to reproduce it. @FIXME{Be more specific, I'd
+like to make this node as detailed as 'Bug reporting' node in Emacs
+manual}.
+
@node Tutorial
@chapter Tutorial Introduction to @command{tar}
precedes lines you should type; to make this more clear, those lines are
shown in @kbd{this font}, as opposed to lines which represent the
computer's response; those lines are shown in @code{this font}, or
-sometimes @samp{like this}. When we have lines which are too long to be
-displayed in any other way, we will show them like this:
-
-@smallexample
-This is an example of a line which would otherwise not fit in this space.
-@end smallexample
+sometimes @samp{like this}.
-@FIXME{how often do we use smallexample?}
+@c When we have lines which are too long to be
+@c displayed in any other way, we will show them like this:
@node basic tar options
@section Basic @command{tar} Operations and Options
exist in @GNUTAR{} for compatibility with Unix
@command{tar}. We present a full discussion of this way of writing
options and operations appears in @ref{Old Options}, and we discuss
-the other two styles of writing options in @ref{Mnemonic Options} and
+the other two styles of writing options in @ref{Mnemonic Options}, and
@ref{Short Options}.)
In the examples and in the text of this tutorial, we usually use the
(they are @dfn{file name arguments} to the @samp{--create} operation).
@FIXME{xref here to the discussion of file name args?}Now that they are
in the archive, they are called @emph{archive members}, not files.
-@FIXME{xref to definitions?}
+(@pxref{Definitions,members}).
When you create an archive, you @emph{must} specify which files you
want placed in the archive. If you do not specify any archive
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 list dir
@unnumberedsubsec Listing the Contents of a Stored Directory
-@UNREVISED
-
-@FIXME{i changed the order of these nodes around and haven't had a
-chance to play around with this node's example, yet. i have to play
-with it and see what it actually does for my own satisfaction, even if
-what it says *is* correct..}
To get information about the contents of an archived directory,
use the directory name as a file name argument in conjunction with
one of the files you had placed in the archive @file{collection.tar}
earlier (say, @file{blues}), you can extract it from the archive without
changing the archive's structure. It will be identical to the original
-file @file{blues} that you deleted. @FIXME{check this; will the times,
-permissions, owner, etc be the same, also?}
+file @file{blues} that you deleted. @FIXME{At the time of this
+writing, atime and ctime are not restored. Since this is a tutorial
+for a beginnig user, it should hardly be mentioned here. Maybe in
+a footnote? --gray}.
First, make sure you are in the @file{practice} directory, and list the
files in the directory. Now, delete the file, @samp{blues}, and list
(@pxref{list}).
You can extract a file to standard output by combining the above options
-with the @option{--to-stdout} option (@pxref{Writing to Standard
+with the @value{op-to-stdout} option (@pxref{Writing to Standard
Output}).
If you give the @value{op-verbose} option, then @value{op-extract} will
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.
+files in the working directory were more recent than those extracted
+(there exist, however, special options that alter this behavior
+@pxref{Writing}).
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
@smallexample
$ @kbd{tar -xvf music.tar practice/folk practice/jazz}
+practice/folk
+practice/jazz
@end smallexample
-@FIXME{need to show tar's response; used verbose above. also, here's a
-good place to demonstrate the -v -v thing. have to write that up
-(should be trivial, but i'm too tired!).}
+@noindent
+If you were to specify two @value{op-verbose} options, @command{tar}
+would have displayed more detail about the extracted files, as shown
+in the example below:
+
+@smallexample
+$ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
+-rw-rw-rw- me user 28 1996-10-18 16:31 practice/jazz
+-rw-rw-rw- me user 20 1996-09-23 16:44 practice/folk
+@end smallexample
@noindent
Because you created the directory with @file{practice} as part of the
$ @kbd{tar -xvf ../untrusted.tar}
@end smallexample
+It is also a good practice to examine contents of the archive
+before extracting it, using @option{op-list} option, possibly combined
+with @option{op-verbose}.
+
@node failing commands
@subsection Commands That Will Fail
only use the option style(s) which makes the most sense to you until you
feel comfortable with the others.
-@FIXME{hag to write a brief paragraph on the option(s) which can
-optionally take an argument}
+Some options @emph{may} take an argument (currently, there are
+two such options: @value{op-backup} and @value{op-occurrence}). 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.
@menu
* Mnemonic Options:: Mnemonic Option Style
@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
for those not fully acquainted with @command{tar}.
Mnemonic options which require arguments take those arguments
-immediately following the option name; they are introduced by an equal
-sign. For example, the @samp{--file} option (which tells the name
-of the @command{tar} archive) is given a file such as @file{archive.tar}
-as argument by using the notation @samp{--file=archive.tar} for the
-mnemonic option.
+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 @samp{--file} option (which
+tells the name of the @command{tar} archive) is given a file such as
+@file{archive.tar} as argument by using any of the following notations:
+@samp{--file=archive.tar} or @samp{--file archive.tar}.
+
+In contrast, optional arguments must always be introduced using
+an equal sign. For example, the @samp{--backup} option takes
+an optional argument specifying backup type. It must be used
+as @samp{--backup=@var{backup-type}}.
@node Short Options
@subsection Short Option Style
@w{@samp{-f @var{archive-name}}} denote the option which indicates a
specific archive, here named @file{archive.tar}.
+Short options which take optional arguments take their arguments
+immediately following the option letter, @emph{without any intervening
+white space characters}.
+
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
are quite different. The first example uses @file{archive.tar.gz} as
the value for option @samp{f} and recognizes the option @samp{z}. The
second example, however, uses @file{z} as the value for option
-@samp{f}---probably not what was intended.
+@samp{f} --- probably not what was intended.
Old options are kept for compatibility with old versions of @command{tar}.
@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
+@xref{Formats}, for a detailed discussion of these formats.
+
@item --group=@var{group}
Files added to the @command{tar} archive will have a group id of @var{group},
performing potentially destructive options, such as overwriting files.
@FIXME-xref{}
+@item --keep-newer-files
+
+Do not replace existing files that are newer than their archive copies
+when extracting files from an archive.
+
@item --keep-old-files
@itemx -k
@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}.
(See @samp{--preserve-permissions}; @pxref{Writing}.)
+@item --show-defaults
+
+Displays the default options used by @command{tar} and exits
+successfully. This option is intended for use in shell scripts.
+Here is an example of what you can see using this option:
+
+@smallexample
+$ tar --show-defaults
+--format=gnu -f- -b20
+@end smallexample
+
@item --show-omitted-dirs
Instructs @command{tar} to mention directories its skipping over when
Instructs @command{tar} to access the archive through @var{prog}, which is
presumed to be a compression program of some sort. @FIXME-xref{}
+@item --utc
+
+Display file modification dates in @acronym{UTC}. This option implies
+@samp{--verbose}.
+
@item --verbose
@itemx -v
@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 :-).
which i believe is basically a Stupid way of doing something? certain
aspects of it show ways in which tar is more broken than i'd personally
like to admit to, specifically the last sentence. On the other hand, i
-don't think it's a good idea to be saying that re explicitly don't
+don't think it's a good idea to be saying that we explicitly don't
recommend using something, but i can't see any better way to deal with
the situation.}When you extract the archive, the older version will be
effectively lost. This works because files are extracted from an
* Dealing with Old Files::
* Overwrite Old Files::
* Keep Old Files::
+* Keep Newer Files::
* Unlink First::
* Recursive Unlink::
* Modification Times::
extraction.
@end table
+@node Keep Newer Files
+@unnumberedsubsubsec Keep Newer Files
+
+@table @kbd
+@item --keep-newer-files
+Do not replace existing files that are newer than their archive
+copies. This option is meaningless with @value{op-list}.
+@end table
+
@node Unlink First
@unnumberedsubsubsec Unlink First
@noindent
The command also works using short option forms:
-@FIXME{The following using standard input/output correct??}
@smallexample
$ @w{@kbd{cd sourcedir; tar --create --file=- . | (cd targetdir; tar --extract --file=-)}}
@end smallexample
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.
@table @asis
@item gnu
-Format used by @GNUTAR{}.
+Format used by @GNUTAR{} versions up to 1.13.25. This format derived
+from an early POSIX 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.
-@item v7
-Archive format, compatible with the V7 implementation of tar.
+Archives in @samp{gnu} format are able to hold pathnames of unlimited
+length.
@item oldgnu
Format used by @GNUTAR{} of versions prior to 1.12.
-@item posix
-Archive format defined by POSIX.1-2001 specification.
+@item v7
+Archive format, compatible with the V7 implementation of tar. This
+format imposes a number of limitations. The most important of them
+are:
+
+@enumerate
+@item The maximum length of a file name is limited to 99 characters.
+@item The maximum length of a symbolic link is limited to 99 characters.
+@item It is impossible to store special files (block and character
+devices, fifos etc.)
+@item Maximum value of user or group ID is limited to 2097151 (7777777
+octal)
+@item V7 archives do not contain symbolic ownership information (user
+and group name of the file owner).
+@end enumerate
+
+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 @GNUTAR{} @value{VERSION} and
+Automake prior to 1.9.
+
+@item ustar
+Archive format defined by POSIX.1-1988 specification. It stores
+symbolic ownership information. It is also able to store
+special files. However, it imposes several restrictions as well:
+
+@enumerate
+@item 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.
+@item The maximum length of a symbolic link name is limited to
+100 characters.
+@item Maximum size of a file the archive is able to accomodate
+is 8GB
+@item Maximum value of UID/GID is 2097151.
+@item Maximum number of bits in device major and minor numbers is 21.
+@end enumerate
@item star
-Format used by J@"org Schilling @command{star} implementation.
+Format used by J@"org Schilling @command{star}
+implementation. @GNUTAR{} is able to read @samp{star} archives but
+currently does not produce them.
+
+@item posix
+Archive format defined by POSIX.1-2001 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 @samp{ustar} archives will be able to read
+most @samp{posix} 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.
+
+This archive format will be the default format for future versions
+of @GNUTAR{}.
+
@end table
-@GNUTAR{} is able to create archives in any of these formats,
-except @samp{star}. It is able to read archives in any of these
-formats.
+The following table summarizes the limitations of each of these
+formats:
+
+@multitable @columnfractions .10 .20 .20 .20 .20
+@item Format @tab UID @tab File Size @tab Path Name @tab Devn
+@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
+@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
+@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
+@item ustar @tab 2097151 @tab 8GB @tab 256 @tab 21
+@item posix @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited
+@end multitable
The default format for @GNUTAR{} is defined at compilation
time. You may check it by running @command{tar --help}, and examining
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.
@end table
@node Standard
-@section The Standard Format
+@section Basic Tar Format
@UNREVISED
While an archive may contain many files, the archive itself is a
@acronym{GNU} Emacs.
Physically, an archive consists of a series of file entries terminated
-by an end-of-archive entry, which consists of 512 zero bytes. A file
+by an end-of-archive entry, which consists of two 512 blocks of zero
+bytes. A file
entry usually describes one of the files in the archive (an
@dfn{archive member}), and consists of a file header and the contents
of the file. File headers contain file names and statistics, checksum
Each file archived is represented by a header block which describes
the file, followed by zero or more blocks which give the contents
-of the file. At the end of the archive file there may be a block
+of the file. At the end of the archive file there are two 512-byte blocks
filled with binary zeros as an end-of-file marker. A reasonable system
-should write a block of zeros at the end, but must not assume that
-such a block exists when reading an archive.
+should write such end-of-file marker at the end of an archive, but
+must not assume that such a block exists when reading an archive. In
+particular @GNUTAR{} always issues a warning if it does not encounter it.
The blocks may be @dfn{blocked} for physical I/O operations.
Each record of @var{n} blocks (where @var{n} is set by the
The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
@code{gname} are null-terminated character strings. All other fields
are zero-filled octal numbers in ASCII. Each numeric field of width
-@var{w} contains @var{w} minus 2 digits, a space, and a null, except
-@code{size}, and @code{mtime}, which do not contain the trailing null.
+@var{w} contains @var{w} minus 1 digits, and a null.
The @code{name} field is the file name of the file, with directory names
(if any) preceding the file name, separated by slashes.
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
projects / chaz / tar / blobdiff