Browse Source

Document base-256 representation in GNU format

Problem reported by Rodrigo Queiro in:
https://lists.gnu.org/r/bug-tar/2017-11/msg00018.html
* doc/intern.texi (Standard, Extensions):
Document base-256 representations.
Paul Eggert 7 years ago
parent
commit
37d7ce16c5
1 changed files with 18 additions and 6 deletions
  1. 18 6
      doc/intern.texi

+ 18 - 6
doc/intern.texi

@@ -87,6 +87,8 @@ The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
 @code{gname} are null-terminated character strings.  All other fields
 @code{gname} are null-terminated character strings.  All other fields
 are zero-filled octal numbers in ASCII.  Each numeric field of width
 are zero-filled octal numbers in ASCII.  Each numeric field of width
 @var{w} contains @var{w} minus 1 digits, and a null.
 @var{w} contains @var{w} minus 1 digits, and a null.
+(In the extended @acronym{GNU} format, the numeric fields can take
+other forms.)
 
 
 The @code{name} field is the file name of the file, with directory names
 The @code{name} field is the file name of the file, with directory names
 (if any) preceding the file name, separated by slashes.
 (if any) preceding the file name, separated by slashes.
@@ -112,14 +114,12 @@ be ignored.
 The @code{size} field is the size of the file in bytes; linked files
 The @code{size} field is the size of the file in bytes; linked files
 are archived with this field specified as zero.
 are archived with this field specified as zero.
 
 
-The @code{mtime} field is the data modification time of the file at
-the time it was archived.  It is the ASCII representation of the octal
-value of the last time the file's contents were modified, represented
-as an integer number of
+The @code{mtime} field represents the data modification time of the file at
+the time it was archived.  It represents the integer number of
 seconds since January 1, 1970, 00:00 Coordinated Universal Time.
 seconds since January 1, 1970, 00:00 Coordinated Universal Time.
 
 
-The @code{chksum} field is the ASCII representation of the octal value
-of the simple sum of all bytes in the header block.  Each 8-bit
+The @code{chksum} field represents
+the simple sum of all bytes in the header block.  Each 8-bit
 byte in the header is added to an unsigned integer, initialized to
 byte in the header is added to an unsigned integer, initialized to
 zero, the precision of which shall be no less than seventeen bits.
 zero, the precision of which shall be no less than seventeen bits.
 When calculating the checksum, the @code{chksum} field is treated as
 When calculating the checksum, the @code{chksum} field is treated as
@@ -310,6 +310,18 @@ of an archive should have this type.
 
 
 @end table
 @end table
 
 
+For fields containing numbers or timestamps that are out of range for
+the basic format, the @acronym{GNU} format uses a base-256
+representation instead of an ASCII octal number.  If the leading byte
+is 0xff (255), all the bytes of the field (including the leading byte)
+are concatenated in big-endian order, with the result being a negative
+number expressed in two's complement form.  If the leading byte is
+0x80 (128), the non-leading bytes of the field are concatenating in
+big-endian order, with the result being a positive number expressed in
+binary form.  Leading bytes other than 0xff, 0x80 and ASCII octal
+digits are reserved for future use, as are base-256 representations of
+values that would be in range for the basic format.
+
 You may have trouble reading a @acronym{GNU} format archive on a
 You may have trouble reading a @acronym{GNU} format archive on a
 non-@acronym{GNU} system if the options @option{--incremental} (@option{-G}),
 non-@acronym{GNU} system if the options @option{--incremental} (@option{-G}),
 @option{--multi-volume} (@option{-M}), @option{--sparse} (@option{-S}), or @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) were
 @option{--multi-volume} (@option{-M}), @option{--sparse} (@option{-S}), or @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) were