579 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3Index Nodes4-----------5 6In a regular UNIX filesystem, the inode stores all the metadata7pertaining to the file (time stamps, block maps, extended attributes,8etc), not the directory entry. To find the information associated with a9file, one must traverse the directory files to find the directory entry10associated with a file, then load the inode to find the metadata for11that file. ext4 appears to cheat (for performance reasons) a little bit12by storing a copy of the file type (normally stored in the inode) in the13directory entry. (Compare all this to FAT, which stores all the file14information directly in the directory entry, but does not support hard15links and is in general more seek-happy than ext4 due to its simpler16block allocator and extensive use of linked lists.)17 18The inode table is a linear array of ``struct ext4_inode``. The table is19sized to have enough blocks to store at least20``sb.s_inode_size * sb.s_inodes_per_group`` bytes. The number of the21block group containing an inode can be calculated as22``(inode_number - 1) / sb.s_inodes_per_group``, and the offset into the23group's table is ``(inode_number - 1) % sb.s_inodes_per_group``. There24is no inode 0.25 26The inode checksum is calculated against the FS UUID, the inode number,27and the inode structure itself.28 29The inode table entry is laid out in ``struct ext4_inode``.30 31.. list-table::32 :widths: 8 8 24 4033 :header-rows: 134 :class: longtable35 36 * - Offset37 - Size38 - Name39 - Description40 * - 0x041 - __le1642 - i_mode43 - File mode. See the table i_mode_ below.44 * - 0x245 - __le1646 - i_uid47 - Lower 16-bits of Owner UID.48 * - 0x449 - __le3250 - i_size_lo51 - Lower 32-bits of size in bytes.52 * - 0x853 - __le3254 - i_atime55 - Last access time, in seconds since the epoch. However, if the EA_INODE56 inode flag is set, this inode stores an extended attribute value and57 this field contains the checksum of the value.58 * - 0xC59 - __le3260 - i_ctime61 - Last inode change time, in seconds since the epoch. However, if the62 EA_INODE inode flag is set, this inode stores an extended attribute63 value and this field contains the lower 32 bits of the attribute value's64 reference count.65 * - 0x1066 - __le3267 - i_mtime68 - Last data modification time, in seconds since the epoch. However, if the69 EA_INODE inode flag is set, this inode stores an extended attribute70 value and this field contains the number of the inode that owns the71 extended attribute.72 * - 0x1473 - __le3274 - i_dtime75 - Deletion Time, in seconds since the epoch.76 * - 0x1877 - __le1678 - i_gid79 - Lower 16-bits of GID.80 * - 0x1A81 - __le1682 - i_links_count83 - Hard link count. Normally, ext4 does not permit an inode to have more84 than 65,000 hard links. This applies to files as well as directories,85 which means that there cannot be more than 64,998 subdirectories in a86 directory (each subdirectory's '..' entry counts as a hard link, as does87 the '.' entry in the directory itself). With the DIR_NLINK feature88 enabled, ext4 supports more than 64,998 subdirectories by setting this89 field to 1 to indicate that the number of hard links is not known.90 * - 0x1C91 - __le3292 - i_blocks_lo93 - Lower 32-bits of “block” count. If the huge_file feature flag is not94 set on the filesystem, the file consumes ``i_blocks_lo`` 512-byte blocks95 on disk. If huge_file is set and EXT4_HUGE_FILE_FL is NOT set in96 ``inode.i_flags``, then the file consumes ``i_blocks_lo + (i_blocks_hi97 << 32)`` 512-byte blocks on disk. If huge_file is set and98 EXT4_HUGE_FILE_FL IS set in ``inode.i_flags``, then this file99 consumes (``i_blocks_lo + i_blocks_hi`` << 32) filesystem blocks on100 disk.101 * - 0x20102 - __le32103 - i_flags104 - Inode flags. See the table i_flags_ below.105 * - 0x24106 - 4 bytes107 - i_osd1108 - See the table i_osd1_ for more details.109 * - 0x28110 - 60 bytes111 - i_block[EXT4_N_BLOCKS=15]112 - Block map or extent tree. See the section “The Contents of inode.i_block”.113 * - 0x64114 - __le32115 - i_generation116 - File version (for NFS).117 * - 0x68118 - __le32119 - i_file_acl_lo120 - Lower 32-bits of extended attribute block. ACLs are of course one of121 many possible extended attributes; I think the name of this field is a122 result of the first use of extended attributes being for ACLs.123 * - 0x6C124 - __le32125 - i_size_high / i_dir_acl126 - Upper 32-bits of file/directory size. In ext2/3 this field was named127 i_dir_acl, though it was usually set to zero and never used.128 * - 0x70129 - __le32130 - i_obso_faddr131 - (Obsolete) fragment address.132 * - 0x74133 - 12 bytes134 - i_osd2135 - See the table i_osd2_ for more details.136 * - 0x80137 - __le16138 - i_extra_isize139 - Size of this inode - 128. Alternately, the size of the extended inode140 fields beyond the original ext2 inode, including this field.141 * - 0x82142 - __le16143 - i_checksum_hi144 - Upper 16-bits of the inode checksum.145 * - 0x84146 - __le32147 - i_ctime_extra148 - Extra change time bits. This provides sub-second precision. See Inode149 Timestamps section.150 * - 0x88151 - __le32152 - i_mtime_extra153 - Extra modification time bits. This provides sub-second precision.154 * - 0x8C155 - __le32156 - i_atime_extra157 - Extra access time bits. This provides sub-second precision.158 * - 0x90159 - __le32160 - i_crtime161 - File creation time, in seconds since the epoch.162 * - 0x94163 - __le32164 - i_crtime_extra165 - Extra file creation time bits. This provides sub-second precision.166 * - 0x98167 - __le32168 - i_version_hi169 - Upper 32-bits for version number.170 * - 0x9C171 - __le32172 - i_projid173 - Project ID.174 175.. _i_mode:176 177The ``i_mode`` value is a combination of the following flags:178 179.. list-table::180 :widths: 16 64181 :header-rows: 1182 183 * - Value184 - Description185 * - 0x1186 - S_IXOTH (Others may execute)187 * - 0x2188 - S_IWOTH (Others may write)189 * - 0x4190 - S_IROTH (Others may read)191 * - 0x8192 - S_IXGRP (Group members may execute)193 * - 0x10194 - S_IWGRP (Group members may write)195 * - 0x20196 - S_IRGRP (Group members may read)197 * - 0x40198 - S_IXUSR (Owner may execute)199 * - 0x80200 - S_IWUSR (Owner may write)201 * - 0x100202 - S_IRUSR (Owner may read)203 * - 0x200204 - S_ISVTX (Sticky bit)205 * - 0x400206 - S_ISGID (Set GID)207 * - 0x800208 - S_ISUID (Set UID)209 * -210 - These are mutually-exclusive file types:211 * - 0x1000212 - S_IFIFO (FIFO)213 * - 0x2000214 - S_IFCHR (Character device)215 * - 0x4000216 - S_IFDIR (Directory)217 * - 0x6000218 - S_IFBLK (Block device)219 * - 0x8000220 - S_IFREG (Regular file)221 * - 0xA000222 - S_IFLNK (Symbolic link)223 * - 0xC000224 - S_IFSOCK (Socket)225 226.. _i_flags:227 228The ``i_flags`` field is a combination of these values:229 230.. list-table::231 :widths: 16 64232 :header-rows: 1233 234 * - Value235 - Description236 * - 0x1237 - This file requires secure deletion (EXT4_SECRM_FL). (not implemented)238 * - 0x2239 - This file should be preserved, should undeletion be desired240 (EXT4_UNRM_FL). (not implemented)241 * - 0x4242 - File is compressed (EXT4_COMPR_FL). (not really implemented)243 * - 0x8244 - All writes to the file must be synchronous (EXT4_SYNC_FL).245 * - 0x10246 - File is immutable (EXT4_IMMUTABLE_FL).247 * - 0x20248 - File can only be appended (EXT4_APPEND_FL).249 * - 0x40250 - The dump(1) utility should not dump this file (EXT4_NODUMP_FL).251 * - 0x80252 - Do not update access time (EXT4_NOATIME_FL).253 * - 0x100254 - Dirty compressed file (EXT4_DIRTY_FL). (not used)255 * - 0x200256 - File has one or more compressed clusters (EXT4_COMPRBLK_FL). (not used)257 * - 0x400258 - Do not compress file (EXT4_NOCOMPR_FL). (not used)259 * - 0x800260 - Encrypted inode (EXT4_ENCRYPT_FL). This bit value previously was261 EXT4_ECOMPR_FL (compression error), which was never used.262 * - 0x1000263 - Directory has hashed indexes (EXT4_INDEX_FL).264 * - 0x2000265 - AFS magic directory (EXT4_IMAGIC_FL).266 * - 0x4000267 - File data must always be written through the journal268 (EXT4_JOURNAL_DATA_FL).269 * - 0x8000270 - File tail should not be merged (EXT4_NOTAIL_FL). (not used by ext4)271 * - 0x10000272 - All directory entry data should be written synchronously (see273 ``dirsync``) (EXT4_DIRSYNC_FL).274 * - 0x20000275 - Top of directory hierarchy (EXT4_TOPDIR_FL).276 * - 0x40000277 - This is a huge file (EXT4_HUGE_FILE_FL).278 * - 0x80000279 - Inode uses extents (EXT4_EXTENTS_FL).280 * - 0x100000281 - Verity protected file (EXT4_VERITY_FL).282 * - 0x200000283 - Inode stores a large extended attribute value in its data blocks284 (EXT4_EA_INODE_FL).285 * - 0x400000286 - This file has blocks allocated past EOF (EXT4_EOFBLOCKS_FL).287 (deprecated)288 * - 0x01000000289 - Inode is a snapshot (``EXT4_SNAPFILE_FL``). (not in mainline)290 * - 0x04000000291 - Snapshot is being deleted (``EXT4_SNAPFILE_DELETED_FL``). (not in292 mainline)293 * - 0x08000000294 - Snapshot shrink has completed (``EXT4_SNAPFILE_SHRUNK_FL``). (not in295 mainline)296 * - 0x10000000297 - Inode has inline data (EXT4_INLINE_DATA_FL).298 * - 0x20000000299 - Create children with the same project ID (EXT4_PROJINHERIT_FL).300 * - 0x80000000301 - Reserved for ext4 library (EXT4_RESERVED_FL).302 * -303 - Aggregate flags:304 * - 0x705BDFFF305 - User-visible flags.306 * - 0x604BC0FF307 - User-modifiable flags. Note that while EXT4_JOURNAL_DATA_FL and308 EXT4_EXTENTS_FL can be set with setattr, they are not in the kernel's309 EXT4_FL_USER_MODIFIABLE mask, since it needs to handle the setting of310 these flags in a special manner and they are masked out of the set of311 flags that are saved directly to i_flags.312 313.. _i_osd1:314 315The ``osd1`` field has multiple meanings depending on the creator:316 317Linux:318 319.. list-table::320 :widths: 8 8 24 40321 :header-rows: 1322 323 * - Offset324 - Size325 - Name326 - Description327 * - 0x0328 - __le32329 - l_i_version330 - Inode version. However, if the EA_INODE inode flag is set, this inode331 stores an extended attribute value and this field contains the upper 32332 bits of the attribute value's reference count.333 334Hurd:335 336.. list-table::337 :widths: 8 8 24 40338 :header-rows: 1339 340 * - Offset341 - Size342 - Name343 - Description344 * - 0x0345 - __le32346 - h_i_translator347 - ??348 349Masix:350 351.. list-table::352 :widths: 8 8 24 40353 :header-rows: 1354 355 * - Offset356 - Size357 - Name358 - Description359 * - 0x0360 - __le32361 - m_i_reserved362 - ??363 364.. _i_osd2:365 366The ``osd2`` field has multiple meanings depending on the filesystem creator:367 368Linux:369 370.. list-table::371 :widths: 8 8 24 40372 :header-rows: 1373 374 * - Offset375 - Size376 - Name377 - Description378 * - 0x0379 - __le16380 - l_i_blocks_high381 - Upper 16-bits of the block count. Please see the note attached to382 i_blocks_lo.383 * - 0x2384 - __le16385 - l_i_file_acl_high386 - Upper 16-bits of the extended attribute block (historically, the file387 ACL location). See the Extended Attributes section below.388 * - 0x4389 - __le16390 - l_i_uid_high391 - Upper 16-bits of the Owner UID.392 * - 0x6393 - __le16394 - l_i_gid_high395 - Upper 16-bits of the GID.396 * - 0x8397 - __le16398 - l_i_checksum_lo399 - Lower 16-bits of the inode checksum.400 * - 0xA401 - __le16402 - l_i_reserved403 - Unused.404 405Hurd:406 407.. list-table::408 :widths: 8 8 24 40409 :header-rows: 1410 411 * - Offset412 - Size413 - Name414 - Description415 * - 0x0416 - __le16417 - h_i_reserved1418 - ??419 * - 0x2420 - __u16421 - h_i_mode_high422 - Upper 16-bits of the file mode.423 * - 0x4424 - __le16425 - h_i_uid_high426 - Upper 16-bits of the Owner UID.427 * - 0x6428 - __le16429 - h_i_gid_high430 - Upper 16-bits of the GID.431 * - 0x8432 - __u32433 - h_i_author434 - Author code?435 436Masix:437 438.. list-table::439 :widths: 8 8 24 40440 :header-rows: 1441 442 * - Offset443 - Size444 - Name445 - Description446 * - 0x0447 - __le16448 - h_i_reserved1449 - ??450 * - 0x2451 - __u16452 - m_i_file_acl_high453 - Upper 16-bits of the extended attribute block (historically, the file454 ACL location).455 * - 0x4456 - __u32457 - m_i_reserved2[2]458 - ??459 460Inode Size461~~~~~~~~~~462 463In ext2 and ext3, the inode structure size was fixed at 128 bytes464(``EXT2_GOOD_OLD_INODE_SIZE``) and each inode had a disk record size of465128 bytes. Starting with ext4, it is possible to allocate a larger466on-disk inode at format time for all inodes in the filesystem to provide467space beyond the end of the original ext2 inode. The on-disk inode468record size is recorded in the superblock as ``s_inode_size``. The469number of bytes actually used by struct ext4_inode beyond the original470128-byte ext2 inode is recorded in the ``i_extra_isize`` field for each471inode, which allows struct ext4_inode to grow for a new kernel without472having to upgrade all of the on-disk inodes. Access to fields beyond473EXT2_GOOD_OLD_INODE_SIZE should be verified to be within474``i_extra_isize``. By default, ext4 inode records are 256 bytes, and (as475of August 2019) the inode structure is 160 bytes476(``i_extra_isize = 32``). The extra space between the end of the inode477structure and the end of the inode record can be used to store extended478attributes. Each inode record can be as large as the filesystem block479size, though this is not terribly efficient.480 481Finding an Inode482~~~~~~~~~~~~~~~~483 484Each block group contains ``sb->s_inodes_per_group`` inodes. Because485inode 0 is defined not to exist, this formula can be used to find the486block group that an inode lives in:487``bg = (inode_num - 1) / sb->s_inodes_per_group``. The particular inode488can be found within the block group's inode table at489``index = (inode_num - 1) % sb->s_inodes_per_group``. To get the byte490address within the inode table, use491``offset = index * sb->s_inode_size``.492 493Inode Timestamps494~~~~~~~~~~~~~~~~495 496Four timestamps are recorded in the lower 128 bytes of the inode497structure -- inode change time (ctime), access time (atime), data498modification time (mtime), and deletion time (dtime). The four fields499are 32-bit signed integers that represent seconds since the Unix epoch500(1970-01-01 00:00:00 GMT), which means that the fields will overflow in501January 2038. If the filesystem does not have orphan_file feature, inodes502that are not linked from any directory but are still open (orphan inodes) have503the dtime field overloaded for use with the orphan list. The superblock field504``s_last_orphan`` points to the first inode in the orphan list; dtime is then505the number of the next orphaned inode, or zero if there are no more orphans.506 507If the inode structure size ``sb->s_inode_size`` is larger than 128508bytes and the ``i_inode_extra`` field is large enough to encompass the509respective ``i_[cma]time_extra`` field, the ctime, atime, and mtime510inode fields are widened to 64 bits. Within this “extra” 32-bit field,511the lower two bits are used to extend the 32-bit seconds field to be 34512bit wide; the upper 30 bits are used to provide nanosecond timestamp513accuracy. Therefore, timestamps should not overflow until May 2446.514dtime was not widened. There is also a fifth timestamp to record inode515creation time (crtime); this field is 64-bits wide and decoded in the516same manner as 64-bit [cma]time. Neither crtime nor dtime are accessible517through the regular stat() interface, though debugfs will report them.518 519We use the 32-bit signed time value plus (2^32 * (extra epoch bits)).520In other words:521 522.. list-table::523 :widths: 20 20 20 20 20524 :header-rows: 1525 526 * - Extra epoch bits527 - MSB of 32-bit time528 - Adjustment for signed 32-bit to 64-bit tv_sec529 - Decoded 64-bit tv_sec530 - valid time range531 * - 0 0532 - 1533 - 0534 - ``-0x80000000 - -0x00000001``535 - 1901-12-13 to 1969-12-31536 * - 0 0537 - 0538 - 0539 - ``0x000000000 - 0x07fffffff``540 - 1970-01-01 to 2038-01-19541 * - 0 1542 - 1543 - 0x100000000544 - ``0x080000000 - 0x0ffffffff``545 - 2038-01-19 to 2106-02-07546 * - 0 1547 - 0548 - 0x100000000549 - ``0x100000000 - 0x17fffffff``550 - 2106-02-07 to 2174-02-25551 * - 1 0552 - 1553 - 0x200000000554 - ``0x180000000 - 0x1ffffffff``555 - 2174-02-25 to 2242-03-16556 * - 1 0557 - 0558 - 0x200000000559 - ``0x200000000 - 0x27fffffff``560 - 2242-03-16 to 2310-04-04561 * - 1 1562 - 1563 - 0x300000000564 - ``0x280000000 - 0x2ffffffff``565 - 2310-04-04 to 2378-04-22566 * - 1 1567 - 0568 - 0x300000000569 - ``0x300000000 - 0x37fffffff``570 - 2378-04-22 to 2446-05-10571 572This is a somewhat odd encoding since there are effectively seven times573as many positive values as negative values. There have also been574long-standing bugs decoding and encoding dates beyond 2038, which don't575seem to be fixed as of kernel 3.12 and e2fsprogs 1.42.8. 64-bit kernels576incorrectly use the extra epoch bits 1,1 for dates between 1901 and5771970. At some point the kernel will be fixed and e2fsck will fix this578situation, assuming that it is run before 2310.579