This page follows squashfs_fs.h of squashfs-tools 3.4 (its _1 structures, and the _2 ones for directories) for SquashFS 1.0. 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.
Superblock
119 bytes at the start; the structure is shared with versions 2 and 3. Version 1 uses the 32-bit fields and the 16-bit block size; the 64-bit fields from offset 63 and the fields at 51 to 62 are not used.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 4 | text | Magic | hsqs little-endian, sqsh big-endian. |
4 | 4 | uint32 | Inode count | The number of inodes. |
8 | 4 | uint32 | Bytes used | The size of the filesystem: the end of the gid table. The file may be padded with zeros after it. |
12 | 4 | uint32 | Uid table start | File offset of the uid table. |
16 | 4 | uint32 | Gid table start | File offset of the gid table; 0 when there are no gids. |
20 | 4 | uint32 | Inode table start | File offset of the first metadata block of the inode table. The file data ends here. |
24 | 4 | uint32 | Directory table start | File offset of the first metadata block of the directory table. |
28 | 2 | uint16 | Version major | 1. |
30 | 2 | uint16 | Version minor | 0. |
32 | 2 | uint16 | Block size | The size of a data block before compression: a power of two that fits 16 bits (32,768 by default). |
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 most 48. |
38 | 1 | uint8 | Gid count | The number of entries of the gid table: at most 15. |
39 | 4 | uint32 | Modification time | Seconds since 1970-01-01 (UTC); also the time of every inode that has none of its own. |
43 | 8 | uint64 | Root inode | A reference to the root directory’s inode. |
51 | 12 | – | Not used | The 32-bit block size, the fragment count and the fragment table start of version 2: version 1 has no fragments. |
63 | 56 | – | Not used | The 64-bit fields of version 3. |
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 to 0x20 | (later versions) | Fragment flags: not used in version 1. |
0x40 | DUPLICATES | Files with identical contents are stored once. |
0x80 | EXPORTABLE | Not used in version 1. |
Metadata blocks
The inode table and the directory 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 a 3-byte header; the fields of its type follow. There are no inode numbers and no link counts. The owner is spread over the header and the type: the uid index is the 4 bits at bit 16 plus 16 times the number of the group of 5 types the type is in.
| Bit | Bits | Name | Description |
|---|---|---|---|
0 | 4 | Type | 1 to 15: the real type is ((type − 1) mod 5) + 1, and the uid index gets 16 × ((type − 1) ÷ 5) added to the 4 bits below. Real types: 1 directory, 2 file, 3 symbolic link, 4 block device, 5 character device. Type 0 is a FIFO or a socket, see below. |
4 | 12 | Mode | The permission bits, including setuid, setgid and sticky. |
16 | 4 | Uid index | The low 4 bits of an index into the uid table. |
20 | 4 | Gid index | An index into the gid table; 15 means the group is the same as the user. |
After the header (bit positions counted from the start of the inode, so the first field after the header is at bit 24). Only files and directories have a time; the others have the superblock’s modification time.
| Type | Bit | Bits | Name | Description |
|---|---|---|---|---|
| 1 directory | 24 | 19 | File size | The size of the listing in bytes. |
43 | 13 | Offset | Where the listing starts in its metadata block of the directory table. | |
56 | 32 | Modification time | Seconds since 1970-01-01 (UTC). | |
88 | 24 | Start block | The offset of that metadata block from the start of the directory table. | |
| 2 file | 24 | 32 | Modification time | Seconds since 1970-01-01 (UTC). |
56 | 32 | Start block | The file offset of the first data block. | |
88 | 32 | File size | The size of the file in bytes. | |
120 | 16 × n | Block list | One size word per data block, the file size divided by the block size, rounded up. | |
| 3 symbolic link | 24 | 16 | Target size | The length of the target in bytes. |
40 | 8 × size | Target | The path, with no terminator. | |
| 4, 5 device | 24 | 16 | Device number | Major in the high 8 bits, minor in the low 8 bits. |
| 0 FIFO, socket | 24 | 4 | Real type | 6 FIFO or 7 socket. |
28 | 4 | Uid group | The number of the group of 16 uids the uid index is in: the index is this times 16 plus the 4 bits at bit 16. The header is 4 bytes long. |
Directories
A directory inode names its listing by a block and an offset in the directory table, and gives its length. A listing is a run of headers, each followed by up to 256 entries; “.” and “..” are not stored, and nothing is added to the size. There is no extended directory and no index.
| Structure | Offset | Size | Name | Description |
|---|---|---|---|---|
| Header (4 bytes) | bits 0 to 7 | 8 bits | Count | The number of entries that follow, minus one. |
bits 8 to 31 | 24 bits | Start block | The metadata block of the inode table that holds the inodes of all these entries. | |
| Entry (3 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 type of the inode, 1 to 7. | |
bits 16 to 23 | 8 bits | Name size | The length of the name minus one. | |
3 | size + 1 | Name | The name, with no terminator. |
File data
A file’s blocks lie one after another from its start block. Each block has a 16-bit size word in the inode: bits 0 to 14 are the stored size (the value 0 stands for 32,768) and bit 15 is set when the block is stored uncompressed. A block decompresses (a zlib stream) to the block size, except the last block of a file, which is short: there are no fragments and no sparse blocks in version 1.
Uid and gid tables
Two plain arrays of 32-bit ids at the end of the filesystem (not in metadata blocks): the uid table, then the gid table. An inode’s uid and gid indexes select an entry; a gid index of 15 means the group is the same as the user.