.TAR File Format – Header block

Schily tar archive (star)

Every member of a star archive starts with a header of exactly 512 bytes. This page is the xstar header of star(5), struct xstar_header, which GNU tar’s tar.h gives in the same form as star_header. The xustar and exustar forms use the same layout without the signature at byte 508. Sparse files have a header of their own, described at the end of this page.

Fields

Offsets and sizes are in bytes, in decimal. The field names are star(5)’s; bytes 0 to 344 hold the same fields as a ustar header.

OffsetSizeTypeNameDescription
0100textt_nameThe member’s name, or the last part of its path when t_prefix holds the rest.
1008octal or base-256t_modePermission bits: 4000 setuid, 2000 setgid, 1000 sticky, then read, write and execute for owner, group and others.
1088octal or base-256t_uidThe owner’s numeric user ID.
1168octal or base-256t_gidThe owner’s numeric group ID.
12412octal or base-256t_sizeThe number of bytes of data after the header.
13612octal or base-256t_mtimeThe modification time, in seconds since 1 January 1970 UTC.
1488octalt_chksumThe header’s checksum.
1561charactert_typeflagWhat the member is: see type flags.
157100textt_linknameThe target of a hard or symbolic link.
2576characterst_magicustar and a NUL, as in POSIX. See magic and signature.
2632characterst_version00.
26532textt_unameThe owner’s user name.
29732textt_gnameThe owner’s group name.
3298octal or base-256t_devmajorThe major device number, for character and block devices.
3378octal or base-256t_devminorThe minor device number.
345131textt_prefixThe folder part of a long path, at most 130 characters. See names and the prefix.
47612octalt_atimeThe access time. See star’s fields.
48812octalt_ctimeThe status change time.
5008fillert_mfillZeros.
5084characterst_xmagictar and a NUL in xstar; zeros in xustar and exustar.

Names and the prefix

Text fields are padded with NUL bytes, and a value that fills its field has no NUL. A path longer than 100 characters is split at a /: the part before goes in t_prefix, the part after in t_name. When the prefix is not empty the path is the prefix, a slash, then the name.

The prefix field is 131 bytes, where ustar’s is 155, and star keeps the prefix to at most 130 characters, so byte 475 always stays NUL. star(5) says this is so that ustar implementations do not fail: a ustar reader stops the prefix at that NUL and gets the right path, without reading the times after it. A path that will not fit the name and the prefix goes in a path record in a pax header.

Writers end a folder’s name with /. The explorer shows names as UTF-8 when they are valid UTF-8, and as Latin-1 when not.

Numbers

Numbers are octal digits as ASCII text, with leading zeros, ended by a space or a NUL. With 7 digits, 8-byte fields reach 2,097,151; with 11 digits, 12-byte fields reach 8,589,934,591, 8 GiB less one byte (star(5) gives the same limits).

Larger values are written in base-256, which star uses in every numeric field. star(5): the first byte is 128 (80) for a positive number and 255 (FF) for a negative one, and the rest of the field is the number in big-endian two’s complement, 56 bits in an 8-byte field and 88 bits in a 12-byte one. Readers take bit 7 of the first byte as the mark and bit 6 as the sign. For example, a size of 600 is 80 00 00 00 00 00 00 00 00 00 02 58.

The explorer reads octal numbers as GNU tar does: one leading NUL and any spaces skipped, octal digits, then a space or a NUL. That description of GNU tar is from memory of its source and is not confirmed.

Checksum

As in ustar, the checksum is the sum of all 512 bytes of the header, each read as an unsigned number, with the eight bytes of t_chksum counted as spaces.

  1. Take the 512 bytes. Replace bytes 148 to 155 with eight spaces (20), which add 256.
  2. Add up the bytes as unsigned numbers, 0 to 255. Readers such as Go and libarchive also accept the sum of the bytes read as signed numbers, which old writers used.
  3. Read the stored field as octal. The header is valid if it equals the sum.
  4. A block of zeros is not a header; readers test for it before checking the sum.

In Go’s star test archive the field is seven digits and a space, 30 30 31 36 37 33 30 20: 0016730, which is 7,640. GNU tar and libarchive write six digits, a NUL and a space instead; a reader should accept both.

Magic and signature

A star header has the POSIX magic and version at 257 to 264, 75 73 74 61 72 00 30 30, so the magic alone does not tell it from ustar. The three forms of the header:

FormBytes 508 to 511What star(5) says
xstar74 61 72 00, tar and a NULThe header “defined in 1994”.
xustarzeros“‘xstar’ format without "tar" signature at header offset 508”.
exustarzeros“‘xustar’ format variant that always includes x-headers and g-headers”.

star(5) says setting t_xmagic to tar “should be avoided in the future”, and that t_mfill and t_xmagic “need to be zero for a 100% ustar compliant implementation”.

Without the signature, a reader tells a star header by its times. GNU tar’s test, which the explorer follows: byte 475 is NUL, bytes 476 and 488 are octal digits, and bytes 487 and 499 are spaces. star(5) as published online gives the same test but says byte 475 should be a space; Go’s star test archive has a NUL there. That GNU tar tests for NUL is from memory of its source and is not confirmed.

star’s fields

Bytes 476 to 511, which ustar reads as the end of the prefix and unused bytes:

OffsetSizeNameMeaning
47612t_atimeThe last access time, in octal, ending in a space.
48812t_ctimeThe last status change time, in the same form.
5008t_mfillFiller, zeros.
5084t_xmagic“tar” in xstar; Go’s trailerSTAR is "tar\x00", so in practice a NUL follows.

The end of the header of small.txt, a 5-byte file in Go’s test archive star.tar. Rows shown as … are left out. The marked bytes are the two times and the signature.

00000100  00 75 73 74 61 72 00 30 30 64 73 79 6D 6F 6E 64  .ustar.00dsymond
…
000001D0  00 00 00 00 00 00 00 00 00 00 00 00 31 31 32 31  ............1121
000001E0  33 35 37 35 32 31 37 20 31 31 32 31 33 35 37 35  3575217 11213575
000001F0  32 31 37 20 00 00 00 00 00 00 00 00 74 61 72 00  217 ........tar.
atime at 0x1DC, ctime at 0x1E8, filler, and tar\0 at 0x1FC.

Both times are 11213575217 and a space: octal 11213575217 is 1,244,592,783 seconds, which is 10 June 2009, 00:13:03 UTC. Byte 475 (0x1DB), the prefix’s last, is NUL, as the time test expects.

The sparse header

For a sparse file, type S, star’s header has yet another layout. It is not in star(5); the table below is star_in_header from GNU tar’s tar.h, which the explorer decodes. It has not been checked against a sparse file written by star.

OffsetSizeTypeNameDescription
0345–fillThe ordinary header fields, name to devminor.
3451textprefixThe prefix, cut to one byte.
3461fillerfill2Filler.
3478fillerfill3Filler.
3551flagisextendedNon-zero when extension blocks follow the header.
356964 × 24 bytesspFour sparse map entries, each a 12-byte octal offset and a 12-byte octal length.
45212octalrealsizeThe file’s full size, holes included.
46412octaloffsetFor a multi-volume continuation, where this part starts in the whole file.
47612octalatimeThe access time, as in the ordinary header.
48812octalctimeThe status change time.
5008fillermfillZeros.
5084charactersxmagictar and a NUL.

When isextended is set, extension blocks follow the header, before the data (star_ext_header in tar.h):

OffsetSizeTypeNameDescription
050421 × 24 bytessp21 more map entries.
5041flagisextendedNon-zero when another extension block follows.
5057padding–Zeros.

Go’s reader notes that “the STAR format also has a sparse header format that uses the same type flag but has a completely different layout” from GNU tar’s sparse header. star(5) says that in star’s formats t_size holds “the sum of the sparse hole descriptors plus the size of the compacted file data”, and that the real size and the offset are now kept in the pax records SCHILY.realsize and SCHILY.offset; see pax extensions.