From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 18 Nov 2017 16:39:33 +0000 (-0800)
Subject: Document base-256 representation in GNU format
X-Git-Tag: release_1_30~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=37d7ce16c512d0b049c1d6ce6372432fdcaba3df;p=thirdparty%2Ftar.git

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.
---

diff --git a/doc/intern.texi b/doc/intern.texi
index 8d205679..5ef0ee8c 100644
--- a/doc/intern.texi
+++ b/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
 are zero-filled octal numbers in ASCII.  Each numeric field of width
 @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
 (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
 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.
 
-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
 zero, the precision of which shall be no less than seventeen bits.
 When calculating the checksum, the @code{chksum} field is treated as
@@ -310,6 +310,18 @@ of an archive should have this type.
 
 @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
 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