busybox/docs/tar_pax.txt
<<
>>
Prefs
   1'pax headers' is POSIX 2003 (iirc) addition designed to fix
   2tar format limitations - older tar format has fixed fields
   3for everything (filename, uid, filesize etc) which can overflow.
   4
   5pax Header Block
   6
   7The pax header block shall be identical to the ustar header block
   8described in ustar Interchange Format, except that two additional
   9typeflag values are defined:
  10
  11x
  12    Represents extended header records for the following file in
  13the archive (which shall have its own ustar header block).
  14
  15g
  16    Represents global extended header records for the following
  17files in the archive. Each value shall affect all subsequent files
  18that do not override that value in their own extended header
  19record and until another global extended header record is reached
  20that provides another value for the same field. The typeflag g
  21global headers should not be used with interchange media that
  22could suffer partial data loss in transporting the archive.
  23
  24For both of these types, the size field shall be the size of the
  25extended header records in octets. The other fields in the header
  26block are not meaningful to this version of the pax utility.
  27However, if this archive is read by a pax utility conforming to
  28the ISO POSIX-2:1993 standard, the header block fields are used to
  29create a regular file that contains the extended header records as
  30data. Therefore, header block field values should be selected to
  31provide reasonable file access to this regular file.
  32
  33A further difference from the ustar header block is that data
  34blocks for files of typeflag 1 (the digit one) (hard link) may be
  35included, which means that the size field may be greater than
  36zero.
  37
  38pax Extended Header
  39
  40An extended header shall consist of one or more records, each
  41constructed as follows:
  42
  43"%d %s=%s\n", <length>, <keyword>, <value>
  44
  45The <length> field shall be the decimal length of the extended
  46header record in octets, including length string itself and the
  47trailing <newline>.
  48
  49[skip]
  50
  51atime
  52    The file access time for the following file(s), equivalent to
  53the value of the st_atime member of the stat structure for a file,
  54as described by the stat() function. The access time shall be
  55restored if the process has the appropriate privilege required to
  56do so. The format of the <value> shall be as described in pax
  57Extended Header File Times.
  58
  59charset
  60    The name of the character set used to encode the data in the
  61following file(s).
  62
  63    The encoding is included in an extended header for information
  64only; when pax is used as described in IEEE Std 1003.1-2001, it
  65shall not translate the file data into any other encoding. The
  66BINARY entry indicates unencoded binary data.
  67
  68    When used in write or copy mode, it is implementation-defined
  69whether pax includes a charset extended header record for a file.
  70
  71comment
  72    A series of characters used as a comment. All characters in
  73the <value> field shall be ignored by pax.
  74
  75gid
  76    The group ID of the group that owns the file, expressed as a
  77decimal number using digits from the ISO/IEC 646:1991 standard.
  78This record shall override the gid field in the following header
  79block(s). When used in write or copy mode, pax shall include a gid
  80extended header record for each file whose group ID is greater
  81than 2097151 (octal 7777777).
  82
  83gname
  84    The group of the file(s), formatted as a group name in the
  85group database. This record shall override the gid and gname
  86fields in the following header block(s), and any gid extended
  87header record. When used in read, copy, or list mode, pax shall
  88translate the name from the UTF-8 encoding in the header record to
  89the character set appropriate for the group database on the
  90receiving system. If any of the UTF-8 characters cannot be
  91translated, and if the -o invalid= UTF-8 option is not specified,
  92the results are implementation-defined. When used in write or copy
  93mode, pax shall include a gname extended header record for each
  94file whose group name cannot be represented entirely with the
  95letters and digits of the portable character set.
  96
  97linkpath
  98    The pathname of a link being created to another file, of any
  99type, previously archived. This record shall override the linkname
 100field in the following ustar header block(s). The following ustar
 101header block shall determine the type of link created. If typeflag
 102of the following header block is 1, it shall be a hard link. If
 103typeflag is 2, it shall be a symbolic link and the linkpath value
 104shall be the contents of the symbolic link. The pax utility shall
 105translate the name of the link (contents of the symbolic link)
 106from the UTF-8 encoding to the character set appropriate for the
 107local file system. When used in write or copy mode, pax shall
 108include a linkpath extended header record for each link whose
 109pathname cannot be represented entirely with the members of the
 110portable character set other than NUL.
 111
 112mtime
 113    The file modification time of the following file(s),
 114equivalent to the value of the st_mtime member of the stat
 115structure for a file, as described in the stat() function. This
 116record shall override the mtime field in the following header
 117block(s). The modification time shall be restored if the process
 118has the appropriate privilege required to do so. The format of the
 119<value> shall be as described in pax Extended Header File Times.
 120
 121path
 122    The pathname of the following file(s). This record shall
 123override the name and prefix fields in the following header
 124block(s). The pax utility shall translate the pathname of the file
 125from the UTF-8 encoding to the character set appropriate for the
 126local file system.
 127
 128    When used in write or copy mode, pax shall include a path
 129extended header record for each file whose pathname cannot be
 130represented entirely with the members of the portable character
 131set other than NUL.
 132
 133realtime.any
 134    The keywords prefixed by "realtime." are reserved for future
 135standardization.
 136
 137security.any
 138    The keywords prefixed by "security." are reserved for future
 139standardization.
 140
 141size
 142    The size of the file in octets, expressed as a decimal number
 143using digits from the ISO/IEC 646:1991 standard. This record shall
 144override the size field in the following header block(s). When
 145used in write or copy mode, pax shall include a size extended
 146header record for each file with a size value greater than
 1478589934591 (octal 77777777777).
 148
 149uid
 150    The user ID of the file owner, expressed as a decimal number
 151using digits from the ISO/IEC 646:1991 standard. This record shall
 152override the uid field in the following header block(s). When used
 153in write or copy mode, pax shall include a uid extended header
 154record for each file whose owner ID is greater than 2097151 (octal
 1557777777).
 156
 157uname
 158    The owner of the following file(s), formatted as a user name
 159in the user database. This record shall override the uid and uname
 160fields in the following header block(s), and any uid extended
 161header record. When used in read, copy, or list mode, pax shall
 162translate the name from the UTF-8 encoding in the header record to
 163the character set appropriate for the user database on the
 164receiving system. If any of the UTF-8 characters cannot be
 165translated, and if the -o invalid= UTF-8 option is not specified,
 166the results are implementation-defined. When used in write or copy
 167mode, pax shall include a uname extended header record for each
 168file whose user name cannot be represented entirely with the
 169letters and digits of the portable character set.
 170
 171If the <value> field is zero length, it shall delete any header
 172block field, previously entered extended header value, or global
 173extended header value of the same name.
 174
 175If a keyword in an extended header record (or in a -o
 176option-argument) overrides or deletes a corresponding field in the
 177ustar header block, pax shall ignore the contents of that header
 178block field.
 179
 180Unlike the ustar header block fields, NULs shall not delimit
 181<value>s; all characters within the <value> field shall be
 182considered data for the field. None of the length limitations of
 183the ustar header block fields in ustar Header Block shall apply to
 184the extended header records.
 185
 186pax Extended Header File Times
 187
 188Time records shall be formatted as a decimal representation of the
 189time in seconds since the Epoch. If a period ( '.' ) decimal point
 190character is present, the digits to the right of the point shall
 191represent the units of a subsecond timing granularity. In read or
 192copy mode, the pax utility shall truncate the time of a file to
 193the greatest value that is not greater than the input header
 194file time. In write or copy mode, the pax utility shall output a
 195time exactly if it can be represented exactly as a decimal number,
 196and otherwise shall generate only enough digits so that the same
 197time shall be recovered if the file is extracted on a system whose
 198underlying implementation supports the same time granularity.
 199
 200Example from Linux kernel archive tarball:
 201
 20200000000  70 61 78 5f 67 6c 6f 62  61 6c 5f 68 65 61 64 65  |pax_global_heade|
 20300000010  72 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |r...............|
 20400000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 20500000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 20600000040  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 20700000050  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 20800000060  00 00 00 00 30 30 30 30  36 36 36 00 30 30 30 30  |....0000666.0000|
 20900000070  30 30 30 00 30 30 30 30  30 30 30 00 30 30 30 30  |000.0000000.0000|
 21000000080  30 30 30 30 30 36 34 00  30 30 30 30 30 30 30 30  |0000064.00000000|
 21100000090  30 30 30 00 30 30 31 34  30 35 33 00 67 00 00 00  |000.0014053.g...|
 212000000a0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 213000000b0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 214000000c0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 215000000d0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 216000000e0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 217000000f0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 21800000100  00 75 73 74 61 72 00 30  30 67 69 74 00 00 00 00  |.ustar.00git....|
 21900000110  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 22000000120  00 00 00 00 00 00 00 00  00 67 69 74 00 00 00 00  |.........git....|
 22100000130  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 22200000140  00 00 00 00 00 00 00 00  00 30 30 30 30 30 30 30  |.........0000000|
 22300000150  00 30 30 30 30 30 30 30  00 00 00 00 00 00 00 00  |.0000000........|
 22400000160  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 22500000170  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 22600000180  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 22700000190  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 228000001a0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 229000001b0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 230000001c0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 231000001d0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 232000001e0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 233000001f0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 23400000200  35 32 20 63 6f 6d 6d 65  6e 74 3d 62 31 30 35 30  |52 comment=b1050|
 23500000210  32 62 32 32 61 31 32 30  39 64 36 62 34 37 36 33  |2b22a1209d6b4763|
 23600000220  39 64 38 38 62 38 31 32  62 32 31 66 62 35 39 34  |9d88b812b21fb594|
 23700000230  39 65 34 0a 00 00 00 00  00 00 00 00 00 00 00 00  |9e4.............|
 23800000240  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
 239...
 240