Pax extensions

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.

0Extended header type flag x512 bytes
512Records padded with zeros to a multiple of 512size rounded up
…Entry header the ustar header the records apply to512 bytes
…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

Key	Meaning
`path`	The entry’s full path, replacing `name` and `prefix`
`linkpath`	The full link target, replacing `linkname`
`size`	The size of the data, for files of 8 GiB or more
`uid`, `gid`	Numeric owner and group, for values too large for the header
`uname`, `gname`	Owner and group names, of any length
`mtime`	Modification time, in seconds with an optional fraction
`atime`, `ctime`	Access time and status change time, in the same form
`comment`	Free text, ignored when extracting
`charset`	The character set of the file’s contents
`hdrcharset`	The 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.