X-Git-Url: https://git.brokenzipper.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=b899260ae514d29c0612f682183b615c99b96ab2;hb=273810a9f73a71bc8417a09a9a9c4c569df0fa11;hp=f77a19af8fb77223c093e0ebe4281add1d9a46c8;hpb=49e7ba5b17aa74483e9d9debdfd31a7748dad8d1;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index f77a19a..b899260 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -96,6 +96,7 @@ document. The rest of the menu lists all the lower level nodes. Appendices +* Changes:: * Genfile:: * Snapshot Files:: * Free Software Needs Free Documentation:: @@ -112,7 +113,6 @@ Introduction * Definitions:: Some Definitions * What tar Does:: What @command{tar} Does * Naming tar Archives:: How @command{tar} Archives are Named -* Current status:: Current development status of @GNUTAR{} * Authors:: @GNUTAR{} Authors * Reports:: Reporting bugs or suggestions @@ -349,6 +349,7 @@ GNU tar internals and development Copying This Manual +* Free Software Needs Free Documentation:: * GNU Free Documentation License:: License for copying this manual @end detailmenu @@ -369,7 +370,6 @@ archives need not (and these days, typically do not) reside on tapes. * Definitions:: Some Definitions * What tar Does:: What @command{tar} Does * Naming tar Archives:: How @command{tar} Archives are Named -* Current status:: Current development status of @GNUTAR{} * Authors:: @GNUTAR{} Authors * Reports:: Reporting bugs or suggestions @end menu @@ -537,63 +537,6 @@ the operation of @command{tar}, this causes no difficulty. However, in this manual, we consistently refer to ``archives'' and ``archive members'' to make learning to use @command{tar} easier for novice users. -@node Current status -@section Current development status of @GNUTAR{} - -@GNUTAR{} is currently in the process of active development, whose -primary aims are: - -@itemize @bullet -@item Improve compatibility between @GNUTAR{} and other @command{tar} -implementations. -@item Switch to using @acronym{POSIX} archives. -@item Revise sparse file handling and multiple volume processing. -@item Merge with the @acronym{GNU} @code{paxutils} project. -@end itemize - -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 synonym for @option{--old-archive}. - -@GNUTAR{} starting from version 1.13.90 understands this option as -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 @option{--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 -synonym for @option{--no-same-owner}. - -@item Use of short option @option{-l} - -Earlier versions of @GNUTAR{} understood @option{-l} option as a -synonym for @option{--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 - @node Authors @section @GNUTAR{} Authors @@ -1332,7 +1275,7 @@ like: @smallexample $ @kbd{tar --list --verbose --file=collection.tar folk} --rw-rw-rw- myself user 62 1990-05-23 10:55 folk +-rw-r--r-- myself user 62 1990-05-23 10:55 folk @end smallexample @cindex listing member and file names @@ -1421,10 +1364,10 @@ $ @kbd{tar --list --verbose --file=music.tar practice} @smallexample drwxrwxrwx myself user 0 1990-05-31 21:49 practice/ --rw-rw-rw- myself user 42 1990-05-21 13:29 practice/blues --rw-rw-rw- myself user 62 1990-05-23 10:55 practice/folk --rw-rw-rw- myself user 40 1990-05-21 13:30 practice/jazz --rw-rw-rw- myself user 10240 1990-05-31 21:49 practice/collection.tar +-rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues +-rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk +-rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz +-rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar @end smallexample When you use a directory name as a file name argument, @command{tar} acts on @@ -1475,9 +1418,9 @@ $ @kbd{tar -xvf collection.tar} produces this: @smallexample --rw-rw-rw- me user 28 1996-10-18 16:31 jazz --rw-rw-rw- me user 21 1996-09-23 16:44 blues --rw-rw-rw- me user 20 1996-09-23 16:44 folk +-rw-r--r-- me user 28 1996-10-18 16:31 jazz +-rw-r--r-- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me user 20 1996-09-23 16:44 folk @end smallexample @node extracting files @@ -1575,8 +1518,8 @@ 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 +-rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz +-rw-r--r-- me user 20 1996-09-23 16:44 practice/folk @end smallexample @noindent @@ -2343,7 +2286,7 @@ Future versions will take @option{-l} as a short version of @option{--check-links}. However, current release still retains the old semantics for @option{-l}. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @opindex compress, summary @opindex uncompress, summary @@ -2690,7 +2633,7 @@ When creating an archive, @option{-o} is a synonym for with previous versions of @GNUTAR{}, and will be removed in the future releases. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @opindex occurrence, summary @item --occurrence[=@var{number}] @@ -2728,7 +2671,7 @@ allowed in the present version, it is @emph{strongly discouraged}. The future versions of @GNUTAR{} will use @option{-l} as a synonym for @option{--check-links}. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @opindex overwrite, summary @item --overwrite @@ -3272,7 +3215,7 @@ them with the equivalent long option. is retained for compatibility with the earlier versions of GNU @command{tar}, and will be changed in future releases. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @item -m @@ -3863,10 +3806,10 @@ If you now use the @option{--list} (@option{-t}) operation, you will see that @smallexample $ @kbd{tar --list --file=collection.tar} --rw-rw-rw- me user 28 1996-10-18 16:31 jazz --rw-rw-rw- me user 21 1996-09-23 16:44 blues --rw-rw-rw- me user 20 1996-09-23 16:44 folk --rw-rw-rw- me user 20 1996-09-23 16:44 rock +-rw-r--r-- me user 28 1996-10-18 16:31 jazz +-rw-r--r-- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me user 20 1996-09-23 16:44 folk +-rw-r--r-- me user 20 1996-09-23 16:44 rock @end smallexample @FIXME{in theory, dan will (soon) try to turn this node into what it's @@ -3917,11 +3860,11 @@ list the contents of the archive: @smallexample $ @kbd{tar --list --verbose --file=collection.tar} --rw-rw-rw- me user 28 1996-10-18 16:31 jazz --rw-rw-rw- me user 21 1996-09-23 16:44 blues --rw-rw-rw- me user 20 1996-09-23 16:44 folk --rw-rw-rw- me user 20 1996-09-23 16:44 rock --rw-rw-rw- me user 58 1996-10-24 18:30 blues +-rw-r--r-- me user 28 1996-10-18 16:31 jazz +-rw-r--r-- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me user 20 1996-09-23 16:44 folk +-rw-r--r-- me user 20 1996-09-23 16:44 rock +-rw-r--r-- me user 58 1996-10-24 18:30 blues @end smallexample @noindent @@ -3937,7 +3880,7 @@ the following example: @smallexample $ @kbd{tar --extract -vv --occurrence --file=collection.tar blues} --rw-rw-rw- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me user 21 1996-09-23 16:44 blues @end smallexample @xref{Writing}, for more information on @option{--extract} and @@ -4066,11 +4009,11 @@ contain what they are supposed to: @smallexample $ @kbd{tar -tvf bluesrock.tar} --rw-rw-rw- melissa user 105 1997-01-21 19:42 blues --rw-rw-rw- melissa user 33 1997-01-20 15:34 rock +-rw-r--r-- melissa user 105 1997-01-21 19:42 blues +-rw-r--r-- melissa user 33 1997-01-20 15:34 rock $ @kbd{tar -tvf folkjazz.tar} --rw-rw-rw- melissa user 20 1996-09-23 16:44 folk --rw-rw-rw- melissa user 65 1997-01-30 14:15 jazz +-rw-r--r-- melissa user 20 1996-09-23 16:44 folk +-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz @end smallexample We can concatenate these two archives with @command{tar}: @@ -7097,40 +7040,36 @@ a @command{tar} able to read the good archives they receive. @cindex large values @cindex future time stamps @cindex negative time stamps - -@acronym{POSIX} @command{tar} format uses fixed-sized unsigned octal strings -to represent numeric values. User and group IDs and device major and -minor numbers have unsigned 21-bit representations, and file sizes and -times have unsigned 33-bit representations. @GNUTAR{} -generates @acronym{POSIX} representations when possible, but for values -outside the @acronym{POSIX} range it generates two's-complement base-256 -strings: uids, gids, and device numbers have signed 57-bit -representations, and file sizes and times have signed 89-bit -representations. These representations are an extension to @acronym{POSIX} -@command{tar} format, so they are not universally portable. - -The most common portability problems with out-of-range numeric values -are large files and future or negative time stamps. - -Portable archives should avoid members of 8 GB or larger, as @acronym{POSIX} -@command{tar} format cannot represent them. - -Portable archives should avoid time stamps from the future. @acronym{POSIX} -@command{tar} format can represent time stamps in the range 1970-01-01 -00:00:00 through 2242-03-16 12:56:31 @sc{utc}. However, many current -hosts use a signed 32-bit @code{time_t}, or internal time stamp format, -and cannot represent time stamps after 2038-01-19 03:14:07 @sc{utc}; so -portable archives must avoid these time stamps for many years to come. - -Portable archives should also avoid time stamps before 1970. These time -stamps are a common @acronym{POSIX} extension but their @code{time_t} -representations are negative. Many traditional @command{tar} -implementations generate a two's complement representation for negative -time stamps that assumes a signed 32-bit @code{time_t}; hence they -generate archives that are not portable to hosts with differing -@code{time_t} representations. @GNUTAR{} recognizes this -situation when it is run on host with a signed 32-bit @code{time_t}, but -it issues a warning, as these time stamps are nonstandard and unportable. +@UNREVISED{} + +The above sections suggest to use @samp{oldest possible} archive +format if in doubt. However, sometimes it is not possible. If you +attempt to archive a file whose metadata cannot be represented using +required format, @GNUTAR{} will print error message and ignore such a +file. You will than have to switch to a format that is able to +handle such values. The format summary table (@pxref{Formats}) will +help you to do so. + +In particular, when trying to archive files larger than 8GB or with +timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 +12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and +@acronym{POSIX} archive formats. When considering which format to +choose, bear in mind that the @acronym{GNU} format uses +two's-complement base-256 notation to store values that do not fit +into standard @acronym{ustar} range. Such archives can generally be +read only by a @GNUTAR{} implementation. Moreover, they sometimes +cannot be correctly restored on another hosts even by @GNUTAR{}. For +example, using two's complement representation for negative time +stamps that assumes a signed 32-bit @code{time_t} generates archives +that are not portable to hosts with differing @code{time_t} +representations. + +On the other hand, @acronym{POSIX} archives, generally speaking, can +be extracted by any tar implementation that understands older +@acronym{ustar} format. The only exception are files larger than 8GB. + +@FIXME{Describe how @acronym{POSIX} archives are extracted by non +POSIX-aware tars.} @node Compression @section Using Less Space through Compression @@ -9221,7 +9160,7 @@ explicitely marked as in the example below: @group $ @kbd{tar --verbose --list --file=iamanarchive} V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header-- --rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename +-rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename @end group @end smallexample @@ -9405,9 +9344,53 @@ disabled) switch, a notch which can be popped out or covered, a ring which can be removed from the center of a tape reel, or some other changeable feature. -@node Free Software Needs Free Documentation -@appendix Free Software Needs Free Documentation -@include freemanuals.texi +@node Changes +@appendix Changes + +This appendix lists some important user-visible changes between +version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date +version of this document is available at +@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the +@GNUTAR{} documentation page}. + +@table @asis +@item Use of short option @option{-o}. + +Earlier versions of @GNUTAR{} understood @option{-o} command line +option as a synonym for @option{--old-archive}. + +@GNUTAR{} starting from version 1.13.90 understands this option as +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 @option{--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 +synonym for @option{--no-same-owner}. + +@item Use of short option @option{-l} + +Earlier versions of @GNUTAR{} understood @option{-l} option as a +synonym for @option{--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 @node Genfile @appendix Genfile @@ -9417,6 +9400,10 @@ changeable feature. @appendix Format of the Incremental Snapshot Files @include snapshot.texi +@node Free Software Needs Free Documentation +@appendix Free Software Needs Free Documentation +@include freemanuals.texi + @node Copying This Manual @appendix Copying This Manual