From: Sergey Poznyakoff Date: Thu, 8 Dec 2005 15:40:52 +0000 (+0000) Subject: (Current status): Renamed to 'Changes' and moved to X-Git-Url: https://git.brokenzipper.com/gitweb?a=commitdiff_plain;h=c9ac15ae0f1c0962ee322e17ec978499e8293da1;p=chaz%2Ftar (Current status): Renamed to 'Changes' and moved to appendices. (Large or Negative Values): Rewritten --- diff --git a/doc/tar.texi b/doc/tar.texi index 09c5f1a..a9ec1b8 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 @@ -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 @@ -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 stores 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 @@ -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