0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 The Contents of inode.i_block
0004 ------------------------------
0005
0006 Depending on the type of file an inode describes, the 60 bytes of
0007 storage in ``inode.i_block`` can be used in different ways. In general,
0008 regular files and directories will use it for file block indexing
0009 information, and special files will use it for special purposes.
0010
0011 Symbolic Links
0012 ~~~~~~~~~~~~~~
0013
0014 The target of a symbolic link will be stored in this field if the target
0015 string is less than 60 bytes long. Otherwise, either extents or block
0016 maps will be used to allocate data blocks to store the link target.
0017
0018 Direct/Indirect Block Addressing
0019 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0020
0021 In ext2/3, file block numbers were mapped to logical block numbers by
0022 means of an (up to) three level 1-1 block map. To find the logical block
0023 that stores a particular file block, the code would navigate through
0024 this increasingly complicated structure. Notice that there is neither a
0025 magic number nor a checksum to provide any level of confidence that the
0026 block isn't full of garbage.
0027
0028 .. ifconfig:: builder != 'latex'
0029
0030 .. include:: blockmap.rst
0031
0032 .. ifconfig:: builder == 'latex'
0033
0034 [Table omitted because LaTeX doesn't support nested tables.]
0035
0036 Note that with this block mapping scheme, it is necessary to fill out a
0037 lot of mapping data even for a large contiguous file! This inefficiency
0038 led to the creation of the extent mapping scheme, discussed below.
0039
0040 Notice also that a file using this mapping scheme cannot be placed
0041 higher than 2^32 blocks.
0042
0043 Extent Tree
0044 ~~~~~~~~~~~
0045
0046 In ext4, the file to logical block map has been replaced with an extent
0047 tree. Under the old scheme, allocating a contiguous run of 1,000 blocks
0048 requires an indirect block to map all 1,000 entries; with extents, the
0049 mapping is reduced to a single ``struct ext4_extent`` with
0050 ``ee_len = 1000``. If flex_bg is enabled, it is possible to allocate
0051 very large files with a single extent, at a considerable reduction in
0052 metadata block use, and some improvement in disk efficiency. The inode
0053 must have the extents flag (0x80000) flag set for this feature to be in
0054 use.
0055
0056 Extents are arranged as a tree. Each node of the tree begins with a
0057 ``struct ext4_extent_header``. If the node is an interior node
0058 (``eh.eh_depth`` > 0), the header is followed by ``eh.eh_entries``
0059 instances of ``struct ext4_extent_idx``; each of these index entries
0060 points to a block containing more nodes in the extent tree. If the node
0061 is a leaf node (``eh.eh_depth == 0``), then the header is followed by
0062 ``eh.eh_entries`` instances of ``struct ext4_extent``; these instances
0063 point to the file's data blocks. The root node of the extent tree is
0064 stored in ``inode.i_block``, which allows for the first four extents to
0065 be recorded without the use of extra metadata blocks.
0066
0067 The extent tree header is recorded in ``struct ext4_extent_header``,
0068 which is 12 bytes long:
0069
0070 .. list-table::
0071 :widths: 8 8 24 40
0072 :header-rows: 1
0073
0074 * - Offset
0075 - Size
0076 - Name
0077 - Description
0078 * - 0x0
0079 - __le16
0080 - eh_magic
0081 - Magic number, 0xF30A.
0082 * - 0x2
0083 - __le16
0084 - eh_entries
0085 - Number of valid entries following the header.
0086 * - 0x4
0087 - __le16
0088 - eh_max
0089 - Maximum number of entries that could follow the header.
0090 * - 0x6
0091 - __le16
0092 - eh_depth
0093 - Depth of this extent node in the extent tree. 0 = this extent node
0094 points to data blocks; otherwise, this extent node points to other
0095 extent nodes. The extent tree can be at most 5 levels deep: a logical
0096 block number can be at most ``2^32``, and the smallest ``n`` that
0097 satisfies ``4*(((blocksize - 12)/12)^n) >= 2^32`` is 5.
0098 * - 0x8
0099 - __le32
0100 - eh_generation
0101 - Generation of the tree. (Used by Lustre, but not standard ext4).
0102
0103 Internal nodes of the extent tree, also known as index nodes, are
0104 recorded as ``struct ext4_extent_idx``, and are 12 bytes long:
0105
0106 .. list-table::
0107 :widths: 8 8 24 40
0108 :header-rows: 1
0109
0110 * - Offset
0111 - Size
0112 - Name
0113 - Description
0114 * - 0x0
0115 - __le32
0116 - ei_block
0117 - This index node covers file blocks from 'block' onward.
0118 * - 0x4
0119 - __le32
0120 - ei_leaf_lo
0121 - Lower 32-bits of the block number of the extent node that is the next
0122 level lower in the tree. The tree node pointed to can be either another
0123 internal node or a leaf node, described below.
0124 * - 0x8
0125 - __le16
0126 - ei_leaf_hi
0127 - Upper 16-bits of the previous field.
0128 * - 0xA
0129 - __u16
0130 - ei_unused
0131 -
0132
0133 Leaf nodes of the extent tree are recorded as ``struct ext4_extent``,
0134 and are also 12 bytes long:
0135
0136 .. list-table::
0137 :widths: 8 8 24 40
0138 :header-rows: 1
0139
0140 * - Offset
0141 - Size
0142 - Name
0143 - Description
0144 * - 0x0
0145 - __le32
0146 - ee_block
0147 - First file block number that this extent covers.
0148 * - 0x4
0149 - __le16
0150 - ee_len
0151 - Number of blocks covered by extent. If the value of this field is <=
0152 32768, the extent is initialized. If the value of the field is > 32768,
0153 the extent is uninitialized and the actual extent length is ``ee_len`` -
0154 32768. Therefore, the maximum length of a initialized extent is 32768
0155 blocks, and the maximum length of an uninitialized extent is 32767.
0156 * - 0x6
0157 - __le16
0158 - ee_start_hi
0159 - Upper 16-bits of the block number to which this extent points.
0160 * - 0x8
0161 - __le32
0162 - ee_start_lo
0163 - Lower 32-bits of the block number to which this extent points.
0164
0165 Prior to the introduction of metadata checksums, the extent header +
0166 extent entries always left at least 4 bytes of unallocated space at the
0167 end of each extent tree data block (because (2^x % 12) >= 4). Therefore,
0168 the 32-bit checksum is inserted into this space. The 4 extents in the
0169 inode do not need checksumming, since the inode is already checksummed.
0170 The checksum is calculated against the FS UUID, the inode number, the
0171 inode generation, and the entire extent block leading up to (but not
0172 including) the checksum itself.
0173
0174 ``struct ext4_extent_tail`` is 4 bytes long:
0175
0176 .. list-table::
0177 :widths: 8 8 24 40
0178 :header-rows: 1
0179
0180 * - Offset
0181 - Size
0182 - Name
0183 - Description
0184 * - 0x0
0185 - __le32
0186 - eb_checksum
0187 - Checksum of the extent block, crc32c(uuid+inum+igeneration+extentblock)
0188
0189 Inline Data
0190 ~~~~~~~~~~~
0191
0192 If the inline data feature is enabled for the filesystem and the flag is
0193 set for the inode, it is possible that the first 60 bytes of the file
0194 data are stored here.
