.TAR File Format – Pax extensions

Tape archive

The pax format, from POSIX.1-2001, keeps the ustar header and adds extended headers that hold any number of key and value records. They lift the old limits: paths of any length, files of any size, times to the nanosecond, Unicode names and extended attributes.

Extended headers

An extended header is an ordinary 512-byte header with type flag x or g, followed by data blocks holding the records. Its own size is the length of the records.

  • An x header applies to the entry straight after it. Its records replace the matching fields of that entry’s header.
  • A g header applies to every entry that follows, until another g header changes it. Values from an x header take priority over global ones.

The extended header’s own name is not used for anything. Writers give it a name such as PaxHeader/hello.txt, so that a program that does not understand pax extracts it as a small, recognisable file.

  1. 0Extended header type flag x512 bytes
  2. 512Records padded with zeros to a multiple of 512size rounded up
  3. …Entry header the ustar header the records apply to512 bytes
  4. …Entry datasize rounded up
An entry with an extended header in front of it.

Records

Each record is a line of text:

30 mtime=1730851200.123456789
51 path=a/very/long/directory/name/report-2024.pdf
Two records, each starting with its own length.

The line is a decimal length, a space, the key, =, the value and a line feed. The length counts the whole record, including the digits of the length itself, the space and the line feed. In the first record above, the key and value mtime=1730851200.123456789 are 26 bytes; with the space, the line feed and the two digits of 30, the whole record is 30 bytes. Because of the length, a value can contain any byte, including line feeds.

Keys and values are UTF-8 unless a hdrcharset record says otherwise. Numbers are decimal text of any length. A record with an empty value removes a setting made earlier by a global header.

Keys

KeyMeaning
pathThe entry’s full path, replacing name and prefix
linkpathThe full link target, replacing linkname
sizeThe size of the data, for files of 8 GiB or more
uid, gidNumeric owner and group, for values too large for the header
uname, gnameOwner and group names, of any length
mtimeModification time, in seconds with an optional fraction
atime, ctimeAccess time and status change time, in the same form
commentFree text, ignored when extracting
charsetThe character set of the file’s contents
hdrcharsetThe character set of the header values; BINARY means raw bytes

Programs add their own keys under a vendor prefix. Common ones are SCHILY.xattr. and LIBARCHIVE.xattr. followed by an extended attribute name, SCHILY.acl. keys for access control lists, and GNU.sparse. keys, which GNU tar uses to describe sparse files in pax archives. A reader skips keys it does not know.