SquashFS 3 structures: superblock, inodes, directories, fragments and ids

This page follows squashfs_fs.h of squashfs-tools 3.4 for SquashFS 3.0 and 3.1. The numbers of an image are all little-endian or all big-endian, as the magic says. Some structures pack several small fields into one group of bits, a bit-field; each is described by its bit position and width. In a little-endian image, bit 0 is the lowest bit of the first byte and a field takes the next bits upward; in a big-endian image, bit 0 is the highest bit of the first byte and a field takes the next bits downward. All offsets are bytes (or bits where said) from the start of the structure.

Superblock

119 bytes at the start. The structure is shared with versions 1 and 2, so it has 32-bit and 64-bit versions of some fields: version 3 uses the 64-bit ones.

Offset	Size	Type	Name	Description
`0`	4	text	Magic	`hsqs` little-endian, `sqsh` big-endian; the LZMA builds of some vendors use `shsq` and `qshs`.
`4`	4	uint32	Inode count	The number of inodes.
`8`	4	uint32	Bytes used (32-bit)	Used by versions 1 and 2.
`12`	4	uint32	Uid table start (32-bit)	Used by versions 1 and 2.
`16`	4	uint32	Gid table start (32-bit)	Used by versions 1 and 2.
`20`	4	uint32	Inode table start (32-bit)	Used by versions 1 and 2.
`24`	4	uint32	Directory table start (32-bit)	Used by versions 1 and 2.
`28`	2	uint16	Version major	3.
`30`	2	uint16	Version minor	0 or 1.
`32`	2	uint16	Block size (16-bit)	Used by version 1.
`34`	2	uint16	Block log	The base-2 logarithm of the block size.
`36`	1	uint8	Flags	Bit flags, below.
`37`	1	uint8	Uid count	The number of entries of the uid table; at least 1.
`38`	1	uint8	Gid count	The number of entries of the gid table; may be 0.
`39`	4	uint32	Modification time	Seconds since 1970-01-01 (UTC).
`43`	8	uint64	Root inode	A reference to the root directory’s inode.
`51`	4	uint32	Block size	The size of a data block and of a fragment block before compression: a power of two up to 1,048,576 (131,072 by default).
`55`	4	uint32	Fragment count	The number of fragment blocks.
`59`	4	uint32	Fragment table start (32-bit)	Used by version 2.
`63`	8	uint64	Bytes used	The size of the filesystem: the end of the gid table. The file is then padded with zeros to a multiple of 4096.
`71`	8	uint64	Uid table start	File offset of the uid table.
`79`	8	uint64	Gid table start	File offset of the gid table; 0 when there are no gids.
`87`	8	uint64	Inode table start	File offset of the first metadata block of the inode table. The file data ends here.
`95`	8	uint64	Directory table start	File offset of the first metadata block of the directory table.
`103`	8	uint64	Fragment table start	File offset of the fragment table’s index, or all ones (0xFFFFFFFFFFFFFFFF) when there are no fragments.
`111`	8	uint64	Lookup table start	File offset of the lookup table’s index, or all ones: always all ones in 3.0.

Flags

Mask	Name	Meaning
`0x01`	UNCOMPRESSED_INODES	The inode and directory tables are stored uncompressed.
`0x02`	UNCOMPRESSED_DATA	Data blocks are stored uncompressed.
`0x04`	CHECK	Check data is present.
`0x08`	UNCOMPRESSED_FRAGMENTS	Fragment blocks are stored uncompressed.
`0x10`	NO_FRAGMENTS	Fragments are not used.
`0x20`	ALWAYS_FRAGMENTS	Fragments are always generated: the tail of every file is in one.
`0x40`	DUPLICATES	Files with identical contents are stored once.
`0x80`	EXPORTABLE	There is a lookup table (3.1).

Metadata blocks

The inode table, the directory table, the fragment table and the lookup table are runs of metadata blocks, read as one stream. A block is a 2-byte header (bit 15 set: stored uncompressed; bits 0 to 14: the size of the data, 1 to 8192) and the data, a zlib stream that decompresses to at most 8192 bytes. A reference to a position in a table is block × 65536 + offset: the file offset of a metadata block counted from the start of the table, and a position in that block after decompression. An inode or listing may continue into the next block.

Inodes

The inode table is a stream of inodes with no gaps. Every inode starts with the same 12-byte header; the fields of its type follow. Types: 1 directory, 2 file, 3 symbolic link, 4 block device, 5 character device, 6 FIFO, 7 socket, 8 extended directory, 9 extended file.

Bit	Bits	Name	Description
`0`	4	Type	1 to 9.
`4`	12	Mode	The permission bits, including setuid, setgid and sticky.
`16`	8	Uid index	An index into the uid table.
`24`	8	Gid index	An index into the gid table; 255 means the group is the same as the user.
`32`	32	Modification time	Seconds since 1970-01-01 (UTC).
`64`	32	Inode number	1 to the inode count, unique; the directory entries repeat it.

After the header (bit positions counted from the start of the inode, so the first field after the header is at bit 96):

Type	Bit	Bits	Name	Description
1 directory	`96`	32	Link count	2 plus the number of subdirectories.
	`128`	19	File size	The size of the listing in bytes plus 3; an empty directory is 3.
	`147`	13	Offset	Where the listing starts in its metadata block of the directory table.
	`160`	32	Start block	The offset of that metadata block from the start of the directory table.
	`192`	32	Parent inode	The number of the parent directory’s inode.
8 extended directory	`96`	32	Link count	As above.
	`128`	27	File size	The size of the listing plus 3.
	`155`	13	Offset	As above.
	`168`	32	Start block	As above.
	`200`	16	Index count	The number of index entries that follow the inode.
	`216`	32	Parent inode	As above.
	`248`	…	Index	Index count entries, see directories.
2 file	`96`	64	Start block	The file offset of the first data block.
	`160`	32	Fragment	The fragment holding the file’s tail, or 0xFFFFFFFF.
	`192`	32	Offset	Where the tail starts in the decompressed fragment.
	`224`	32	File size	The size of the file in bytes.
	`256`	32 × n	Block list	One size word per data block: with a fragment, the file size divided by the block size rounded down; without, rounded up.
9 extended file	`96`	32	Link count	The number of directory entries that name the inode.
	`128`	64	Start block	As above.
	`192`	32	Fragment	As above.
	`224`	32	Offset	As above.
	`256`	64	File size	The size of the file, up to 2^63 bytes.
	`320`	32 × n	Block list	As above.
3 symbolic link	`96`	32	Link count
	`128`	16	Target size	The length of the target in bytes.
	`144`	8 × size	Target	The path, with no terminator.
4, 5 device	`96`	32	Link count
4, 5 device	`128`	16	Device number	Major in the high 8 bits, minor in the low 8 bits.
6, 7 FIFO, socket	`96`	32	Link count	Nothing else.

Directories

A directory inode names its listing by a block and an offset in the directory table. A listing is a run of headers, each followed by up to 256 entries, sorted by name; “.” and “..” are not stored. A reader takes the listing’s size minus 3 bytes.

Structure	Offset	Size	Name	Description
Header (9 bytes)	`0`	1	Count	The number of entries that follow, minus one.
	`1`	4	Start block	The metadata block of the inode table that holds the inodes of all these entries.
	`5`	4	Inode number	The number of the first entry’s inode.
Entry (5 bytes, then the name)	bits `0` to `12`	13 bits	Offset	Where the entry’s inode starts in that decompressed block.
	bits `13` to `15`	3 bits	Type	The basic type of the inode, 1 to 7.
	bits `16` to `23`	8 bits	Name size	The length of the name minus one.
	bits `24` to `39`	16 bits	Inode delta	Signed: added to the header’s inode number.
	`5`	size + 1	Name	The name, with no terminator.
Index entry of an extended directory (9 bytes, then the name)	`0`	4	Index	The byte position of a header in the listing.
	`4`	4	Start block	The metadata block of the directory table that holds that header.
	`8`	1	Name size	The length of the name minus one; the name is the first entry of that header.

File data

A file’s blocks lie one after another from its start block. Each block has a 32-bit size word in the inode: bits 0 to 23 are the stored size, bit 24 is set when the block is stored uncompressed, and a size of 0 is a sparse block: nothing is stored and it reads as zeros. A block decompresses (a zlib stream) to the block size, except a last block. The tail of a file that is not a whole number of blocks is in a fragment: the inode gives the fragment and the offset of the tail in the decompressed fragment block.

Fragment table

One 16-byte entry for each fragment block, 512 to a metadata block, then an index: an array of 64-bit file offsets of those metadata blocks. The superblock gives the offset of the index.

Offset	Size	Type	Name	Description
`0`	8	uint64	Start	The file offset of the fragment block.
`8`	4	uint32	Size	As a data block’s size word: bit 24 set when stored uncompressed.
`12`	4	uint32	Unused	Zero.

Lookup table (3.1)

Present when the EXPORTABLE flag is set: one 64-bit reference for each inode, entry i for the inode numbered i + 1, 1024 to a metadata block, then an index of 64-bit file offsets of those blocks. The superblock gives the offset of the index.

Uid and gid tables

Two plain arrays of 32-bit ids at the end of the filesystem (not in metadata blocks): the uid table (at least one id), then the gid table. An inode’s uid and gid indexes select an entry; a gid index of 255 means the group is the same as the user.

.SQUASHFS File Format – Structures