Every member of a tar archive starts with a header of exactly 512 bytes. It holds the member’s name, permissions, owner, size, time and type. Numbers are written as text, in octal, so a header can be read in a text editor. This page is the POSIX ustar header, which pax archives use unchanged, and the Version 7 header it grew from.
Fields
Offsets and sizes are in bytes, in decimal. The examples are from the header shown
at the end of this page. The first 257 bytes, from
name to linkname, are the Version 7 header; the rest was
added by POSIX.1-1988.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 100 | text | name | The member’s name, or the last part of its path when prefix holds the rest. See names and paths. Example: foo. |
100 | 8 | octal | mode | Permission bits: 4000 setuid, 2000 setgid, 1000 sticky, then read, write and execute for owner (400, 200, 100), group (40, 20, 10) and others (4, 2, 1). Example: 0000640. |
108 | 8 | octal | uid | The owner’s numeric user ID. Example: 1160745, which is 319,973. |
116 | 8 | octal | gid | The owner’s numeric group ID. Example: 0011610, which is 5,000. |
124 | 12 | octal | size | The number of bytes of data after the header. Example: 00000001254, which is 684. |
136 | 12 | octal | mtime | The modification time, in seconds since 1 January 1970 UTC. Example: 12575676024, which is 1,442,282,516: 15 September 2015, 02:01:56 UTC. |
148 | 8 | octal | chksum | The header’s checksum. Example: 010640, which is 4,512. |
156 | 1 | character | typeflag | What the member is: see type flags. Example: 0, a regular file. |
157 | 100 | text | linkname | The target of a hard or symbolic link. It has no prefix. |
257 | 6 | characters | magic | ustar and a NUL (75 73 74 61 72 00). See magic and version. |
263 | 2 | characters | version | The two characters 00 (30 30). |
265 | 32 | text | uname | The owner’s user name. A reader uses it in place of uid when that user exists on the system. Example: joetsai. |
297 | 32 | text | gname | The owner’s group name, used in place of gid in the same way. Example: eng. |
329 | 8 | octal | devmajor | The major device number, for character and block devices (types 3 and 4). |
337 | 8 | octal | devminor | The minor device number. |
345 | 155 | text | prefix | The folder part of a path too long for name. See names and paths. |
500 | 12 | unused | – | Not in the POSIX table, which does not say what these bytes are. Writers leave zeros. |
Names and paths
Text fields are padded with NUL bytes. POSIX: each part ends at the first NUL. A value
that fills the whole field has no NUL at the end, so a 100-character name uses all 100
bytes of name.
A path longer than 100 characters can be split at a /: the part before the
slash goes in prefix, the part after it in name, and the slash
itself is not stored. When prefix is not empty, the path is
prefix, a slash, then name. This gives paths of up to 256
characters, as long as a slash falls in the right place. Longer paths, and any link
target over 100 characters, need a path or linkpath record in
a pax header.
Writers end a folder’s name with /. That is a convention, not a rule of
POSIX, but in old Version 7 style archives the slash is the only sign that a member is
a folder.
The bytes of a name are not tagged with an encoding. Pax records are UTF-8 unless a
hdrcharset record says otherwise. The explorer shows names as UTF-8 when
they are valid UTF-8, and as Latin-1 when not.
Numbers
Numeric fields hold octal digits as ASCII text, with leading zeros, ended by one or
more spaces or NULs. Writers differ in the ending. In the example every number is
digits and a NUL; bsdtar writes mode as six digits, a space and a NUL.
Early writers filled numbers with leading spaces instead of zeros: Go’s Version 7 test
archive has the mode 20 20 20 34 34 34 20 00, three spaces,
444, a space and a NUL.
The field sizes set limits. With 7 digits, mode, uid and
gid reach 2,097,151; with 11 digits, size and
mtime reach 8,589,934,591, which is 8 GiB less one byte. Larger values are
written in one of two ways:
- Pax records, the POSIX way: the true value goes in a
size,uid,gidormtimerecord in a pax header, as decimal text of any length. - Base-256, used by GNU tar, star and libarchive. If the top bit of
the field’s first byte is set, the rest of the field is a big-endian two’s complement
binary number; bit 6 of the first byte is the sign. A first byte of
80marks a positive number andFFa negative one. POSIX ustar does not allow it, but Go, libarchive and GNU tar accept it in any header. The size 600 in base-256 is80 00 00 00 00 00 00 00 00 00 02 58.
Readers differ in how strict they are. Go trims leading and trailing spaces and NULs and then requires octal digits only. GNU tar skips one leading NUL and any leading spaces, reads octal digits, and requires the next byte to be a space or a NUL. The explorer reads numbers as GNU tar does; that description of GNU tar is from memory of its source and is not confirmed.
Checksum
POSIX: the checksum is “the octal value of the simple sum of all octets in the
header”, each read as an unsigned number, with the eight bytes of chksum
itself counted as spaces. Many early writers summed signed bytes instead, so Go and
libarchive work out both sums and accept either; libarchive’s source names old BSD,
Solaris and HP-UX tar as the reason.
- Take the 512 bytes. Replace bytes 148 to 155 with eight spaces (
20). They add 8 × 32 = 256. - Add up the bytes as unsigned numbers, 0 to 255: the unsigned sum. Add them up as
signed numbers, −128 to 127: the signed sum. The two differ only if some byte is
80or more. - Read the stored field as an octal number. The header is valid if it equals either sum.
- A block of zeros is not a header: its checksum field reads as zero but its sum is 256. Readers test for a zero block before checking the sum.
The field is usually six octal digits, a NUL and a space. In the example it is
30 31 30 36 34 30 00 20: 010640, which is 4,512.
00000090 30 32 34 00 30 31 30 36 34 30 00 20 30 00 00 00 024.010640. 0...0.Magic and version
Bytes 257 to 264 say which header layout a block is in. Only the first two rows are this format:
| Bytes 257 to 264 | Header |
|---|---|
75 73 74 61 72 00 30 30: ustar, NUL, 00 | POSIX ustar, and pax archives |
| all zeros | the Version 7 header |
75 73 74 61 72 20 20 00: ustar, two spaces, NUL | GNU tar’s header, a separate format whose bytes from 345 on mean something else; some writers from before POSIX wrote the same bytes |
Some writers put a version of two NULs in place of 00; one test archive of
the JavaScript library tar-stream does, in an archive that also pads its numbers with
leading spaces. The explorer accepts the ustar\0 magic with any version
and reports a version other than 00.
star’s headers also carry ustar\0 00. They are told apart by
bytes 475 to 511, and are a separate format.
The Version 7 header
The tar of Version 7 Unix, in 1979, used only the first 257 bytes of the block. The rest, 255 bytes, are unused and filled with NULs. There is no magic, no owner names and no prefix.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 100 | text | name | The full path, up to 100 characters. A folder’s name ends with /. |
100 | 8 | octal | mode | Permission bits. |
108 | 8 | octal | uid | Numeric owner. |
116 | 8 | octal | gid | Numeric group. |
124 | 12 | octal | size | Bytes of data after the header. |
136 | 12 | octal | mtime | Modification time. |
148 | 8 | octal | chksum | Checksum, worked out as above. |
156 | 1 | character | linkflag | NUL for a file, 1 for a hard link. Later Version 7 style writers also wrote 2 and 5. |
157 | 100 | text | linkname | The target of a link. |
257 | 255 | unused | pad | NULs. |
Version 7 style headers often pad numbers with leading spaces and end the checksum
with a NUL and a space: Go’s Version 7 test archive has a checksum field of leading
spaces, 6062, a NUL and a space. An archive of the gd 2.0.15 sources from
2003, examined for this site, is in this style: no magic, type 5 for
folders and numbers ended by NUL.
A ustar header is a Version 7 header with the unused bytes filled in, so a Version 7 reader reads a ustar archive correctly, apart from names that use the prefix. The explorer reports non-zero bytes after 257 in a header without the magic: one test archive of tar-stream has device numbers at 329 to 344, as if a ustar writer had left out the magic.
Example
The header of a 684-byte file, foo, from Go’s test archive
ustar-file-reg.tar. Rows that are all zeros are shown as *.
The marked bytes are the magic and version.
00000000 66 6F 6F 00 00 00 00 00 00 00 00 00 00 00 00 00 foo.............
*
00000060 00 00 00 00 30 30 30 30 36 34 30 00 31 31 36 30 ....0000640.1160
00000070 37 34 35 00 30 30 31 31 36 31 30 00 30 30 30 30 745.0011610.0000
00000080 30 30 30 31 32 35 34 00 31 32 35 37 35 36 37 36 0001254.12575676
00000090 30 32 34 00 30 31 30 36 34 30 00 20 30 00 00 00 024.010640. 0...
*
00000100 00 75 73 74 61 72 00 30 30 6A 6F 65 74 73 61 69 .ustar.00joetsai
*
00000120 00 00 00 00 00 00 00 00 00 65 6E 67 00 00 00 00 .........eng....
*Reading it: the name foo at 0; mode 0000640 at 100
(0x64); uid 1160745 at 108; gid 0011610 at 116;
size 00000001254 at 124, so 684 bytes of data follow, padded to two
blocks; mtime at 136; the checksum at 148; type 0 at 156
(0x9C); the magic and version at 257 (0x101); the user name
joetsai at 265 (0x109) and the group name eng
at 297 (0x129). The link name, device numbers and prefix are empty.