123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578 |
- .. SPDX-License-Identifier: GPL-2.0
- Index Nodes
- -----------
- In a regular UNIX filesystem, the inode stores all the metadata
- pertaining to the file (time stamps, block maps, extended attributes,
- etc), not the directory entry. To find the information associated with a
- file, one must traverse the directory files to find the directory entry
- associated with a file, then load the inode to find the metadata for
- that file. ext4 appears to cheat (for performance reasons) a little bit
- by storing a copy of the file type (normally stored in the inode) in the
- directory entry. (Compare all this to FAT, which stores all the file
- information directly in the directory entry, but does not support hard
- links and is in general more seek-happy than ext4 due to its simpler
- block allocator and extensive use of linked lists.)
- The inode table is a linear array of ``struct ext4_inode``. The table is
- sized to have enough blocks to store at least
- ``sb.s_inode_size * sb.s_inodes_per_group`` bytes. The number of the
- block group containing an inode can be calculated as
- ``(inode_number - 1) / sb.s_inodes_per_group``, and the offset into the
- group's table is ``(inode_number - 1) % sb.s_inodes_per_group``. There
- is no inode 0.
- The inode checksum is calculated against the FS UUID, the inode number,
- and the inode structure itself.
- The inode table entry is laid out in ``struct ext4_inode``.
- .. list-table::
- :widths: 8 8 24 40
- :header-rows: 1
- :class: longtable
- * - Offset
- - Size
- - Name
- - Description
- * - 0x0
- - \_\_le16
- - i\_mode
- - File mode. See the table i_mode_ below.
- * - 0x2
- - \_\_le16
- - i\_uid
- - Lower 16-bits of Owner UID.
- * - 0x4
- - \_\_le32
- - i\_size\_lo
- - Lower 32-bits of size in bytes.
- * - 0x8
- - \_\_le32
- - i\_atime
- - Last access time, in seconds since the epoch. However, if the EA\_INODE
- inode flag is set, this inode stores an extended attribute value and
- this field contains the checksum of the value.
- * - 0xC
- - \_\_le32
- - i\_ctime
- - Last inode change time, in seconds since the epoch. However, if the
- EA\_INODE inode flag is set, this inode stores an extended attribute
- value and this field contains the lower 32 bits of the attribute value's
- reference count.
- * - 0x10
- - \_\_le32
- - i\_mtime
- - Last data modification time, in seconds since the epoch. However, if the
- EA\_INODE inode flag is set, this inode stores an extended attribute
- value and this field contains the number of the inode that owns the
- extended attribute.
- * - 0x14
- - \_\_le32
- - i\_dtime
- - Deletion Time, in seconds since the epoch.
- * - 0x18
- - \_\_le16
- - i\_gid
- - Lower 16-bits of GID.
- * - 0x1A
- - \_\_le16
- - i\_links\_count
- - Hard link count. Normally, ext4 does not permit an inode to have more
- than 65,000 hard links. This applies to files as well as directories,
- which means that there cannot be more than 64,998 subdirectories in a
- directory (each subdirectory's '..' entry counts as a hard link, as does
- the '.' entry in the directory itself). With the DIR\_NLINK feature
- enabled, ext4 supports more than 64,998 subdirectories by setting this
- field to 1 to indicate that the number of hard links is not known.
- * - 0x1C
- - \_\_le32
- - i\_blocks\_lo
- - Lower 32-bits of “block” count. If the huge\_file feature flag is not
- set on the filesystem, the file consumes ``i_blocks_lo`` 512-byte blocks
- on disk. If huge\_file is set and EXT4\_HUGE\_FILE\_FL is NOT set in
- ``inode.i_flags``, then the file consumes ``i_blocks_lo + (i_blocks_hi
- << 32)`` 512-byte blocks on disk. If huge\_file is set and
- EXT4\_HUGE\_FILE\_FL IS set in ``inode.i_flags``, then this file
- consumes (``i_blocks_lo + i_blocks_hi`` << 32) filesystem blocks on
- disk.
- * - 0x20
- - \_\_le32
- - i\_flags
- - Inode flags. See the table i_flags_ below.
- * - 0x24
- - 4 bytes
- - i\_osd1
- - See the table i_osd1_ for more details.
- * - 0x28
- - 60 bytes
- - i\_block[EXT4\_N\_BLOCKS=15]
- - Block map or extent tree. See the section “The Contents of inode.i\_block”.
- * - 0x64
- - \_\_le32
- - i\_generation
- - File version (for NFS).
- * - 0x68
- - \_\_le32
- - i\_file\_acl\_lo
- - Lower 32-bits of extended attribute block. ACLs are of course one of
- many possible extended attributes; I think the name of this field is a
- result of the first use of extended attributes being for ACLs.
- * - 0x6C
- - \_\_le32
- - i\_size\_high / i\_dir\_acl
- - Upper 32-bits of file/directory size. In ext2/3 this field was named
- i\_dir\_acl, though it was usually set to zero and never used.
- * - 0x70
- - \_\_le32
- - i\_obso\_faddr
- - (Obsolete) fragment address.
- * - 0x74
- - 12 bytes
- - i\_osd2
- - See the table i_osd2_ for more details.
- * - 0x80
- - \_\_le16
- - i\_extra\_isize
- - Size of this inode - 128. Alternately, the size of the extended inode
- fields beyond the original ext2 inode, including this field.
- * - 0x82
- - \_\_le16
- - i\_checksum\_hi
- - Upper 16-bits of the inode checksum.
- * - 0x84
- - \_\_le32
- - i\_ctime\_extra
- - Extra change time bits. This provides sub-second precision. See Inode
- Timestamps section.
- * - 0x88
- - \_\_le32
- - i\_mtime\_extra
- - Extra modification time bits. This provides sub-second precision.
- * - 0x8C
- - \_\_le32
- - i\_atime\_extra
- - Extra access time bits. This provides sub-second precision.
- * - 0x90
- - \_\_le32
- - i\_crtime
- - File creation time, in seconds since the epoch.
- * - 0x94
- - \_\_le32
- - i\_crtime\_extra
- - Extra file creation time bits. This provides sub-second precision.
- * - 0x98
- - \_\_le32
- - i\_version\_hi
- - Upper 32-bits for version number.
- * - 0x9C
- - \_\_le32
- - i\_projid
- - Project ID.
- .. _i_mode:
- The ``i_mode`` value is a combination of the following flags:
- .. list-table::
- :widths: 16 64
- :header-rows: 1
- * - Value
- - Description
- * - 0x1
- - S\_IXOTH (Others may execute)
- * - 0x2
- - S\_IWOTH (Others may write)
- * - 0x4
- - S\_IROTH (Others may read)
- * - 0x8
- - S\_IXGRP (Group members may execute)
- * - 0x10
- - S\_IWGRP (Group members may write)
- * - 0x20
- - S\_IRGRP (Group members may read)
- * - 0x40
- - S\_IXUSR (Owner may execute)
- * - 0x80
- - S\_IWUSR (Owner may write)
- * - 0x100
- - S\_IRUSR (Owner may read)
- * - 0x200
- - S\_ISVTX (Sticky bit)
- * - 0x400
- - S\_ISGID (Set GID)
- * - 0x800
- - S\_ISUID (Set UID)
- * -
- - These are mutually-exclusive file types:
- * - 0x1000
- - S\_IFIFO (FIFO)
- * - 0x2000
- - S\_IFCHR (Character device)
- * - 0x4000
- - S\_IFDIR (Directory)
- * - 0x6000
- - S\_IFBLK (Block device)
- * - 0x8000
- - S\_IFREG (Regular file)
- * - 0xA000
- - S\_IFLNK (Symbolic link)
- * - 0xC000
- - S\_IFSOCK (Socket)
- .. _i_flags:
- The ``i_flags`` field is a combination of these values:
- .. list-table::
- :widths: 16 64
- :header-rows: 1
- * - Value
- - Description
- * - 0x1
- - This file requires secure deletion (EXT4\_SECRM\_FL). (not implemented)
- * - 0x2
- - This file should be preserved, should undeletion be desired
- (EXT4\_UNRM\_FL). (not implemented)
- * - 0x4
- - File is compressed (EXT4\_COMPR\_FL). (not really implemented)
- * - 0x8
- - All writes to the file must be synchronous (EXT4\_SYNC\_FL).
- * - 0x10
- - File is immutable (EXT4\_IMMUTABLE\_FL).
- * - 0x20
- - File can only be appended (EXT4\_APPEND\_FL).
- * - 0x40
- - The dump(1) utility should not dump this file (EXT4\_NODUMP\_FL).
- * - 0x80
- - Do not update access time (EXT4\_NOATIME\_FL).
- * - 0x100
- - Dirty compressed file (EXT4\_DIRTY\_FL). (not used)
- * - 0x200
- - File has one or more compressed clusters (EXT4\_COMPRBLK\_FL). (not used)
- * - 0x400
- - Do not compress file (EXT4\_NOCOMPR\_FL). (not used)
- * - 0x800
- - Encrypted inode (EXT4\_ENCRYPT\_FL). This bit value previously was
- EXT4\_ECOMPR\_FL (compression error), which was never used.
- * - 0x1000
- - Directory has hashed indexes (EXT4\_INDEX\_FL).
- * - 0x2000
- - AFS magic directory (EXT4\_IMAGIC\_FL).
- * - 0x4000
- - File data must always be written through the journal
- (EXT4\_JOURNAL\_DATA\_FL).
- * - 0x8000
- - File tail should not be merged (EXT4\_NOTAIL\_FL). (not used by ext4)
- * - 0x10000
- - All directory entry data should be written synchronously (see
- ``dirsync``) (EXT4\_DIRSYNC\_FL).
- * - 0x20000
- - Top of directory hierarchy (EXT4\_TOPDIR\_FL).
- * - 0x40000
- - This is a huge file (EXT4\_HUGE\_FILE\_FL).
- * - 0x80000
- - Inode uses extents (EXT4\_EXTENTS\_FL).
- * - 0x100000
- - Verity protected file (EXT4\_VERITY\_FL).
- * - 0x200000
- - Inode stores a large extended attribute value in its data blocks
- (EXT4\_EA\_INODE\_FL).
- * - 0x400000
- - This file has blocks allocated past EOF (EXT4\_EOFBLOCKS\_FL).
- (deprecated)
- * - 0x01000000
- - Inode is a snapshot (``EXT4_SNAPFILE_FL``). (not in mainline)
- * - 0x04000000
- - Snapshot is being deleted (``EXT4_SNAPFILE_DELETED_FL``). (not in
- mainline)
- * - 0x08000000
- - Snapshot shrink has completed (``EXT4_SNAPFILE_SHRUNK_FL``). (not in
- mainline)
- * - 0x10000000
- - Inode has inline data (EXT4\_INLINE\_DATA\_FL).
- * - 0x20000000
- - Create children with the same project ID (EXT4\_PROJINHERIT\_FL).
- * - 0x80000000
- - Reserved for ext4 library (EXT4\_RESERVED\_FL).
- * -
- - Aggregate flags:
- * - 0x705BDFFF
- - User-visible flags.
- * - 0x604BC0FF
- - User-modifiable flags. Note that while EXT4\_JOURNAL\_DATA\_FL and
- EXT4\_EXTENTS\_FL can be set with setattr, they are not in the kernel's
- EXT4\_FL\_USER\_MODIFIABLE mask, since it needs to handle the setting of
- these flags in a special manner and they are masked out of the set of
- flags that are saved directly to i\_flags.
- .. _i_osd1:
- The ``osd1`` field has multiple meanings depending on the creator:
- Linux:
- .. list-table::
- :widths: 8 8 24 40
- :header-rows: 1
- * - Offset
- - Size
- - Name
- - Description
- * - 0x0
- - \_\_le32
- - l\_i\_version
- - Inode version. However, if the EA\_INODE inode flag is set, this inode
- stores an extended attribute value and this field contains the upper 32
- bits of the attribute value's reference count.
- Hurd:
- .. list-table::
- :widths: 8 8 24 40
- :header-rows: 1
- * - Offset
- - Size
- - Name
- - Description
- * - 0x0
- - \_\_le32
- - h\_i\_translator
- - ??
- Masix:
- .. list-table::
- :widths: 8 8 24 40
- :header-rows: 1
- * - Offset
- - Size
- - Name
- - Description
- * - 0x0
- - \_\_le32
- - m\_i\_reserved
- - ??
- .. _i_osd2:
- The ``osd2`` field has multiple meanings depending on the filesystem creator:
- Linux:
- .. list-table::
- :widths: 8 8 24 40
- :header-rows: 1
- * - Offset
- - Size
- - Name
- - Description
- * - 0x0
- - \_\_le16
- - l\_i\_blocks\_high
- - Upper 16-bits of the block count. Please see the note attached to
- i\_blocks\_lo.
- * - 0x2
- - \_\_le16
- - l\_i\_file\_acl\_high
- - Upper 16-bits of the extended attribute block (historically, the file
- ACL location). See the Extended Attributes section below.
- * - 0x4
- - \_\_le16
- - l\_i\_uid\_high
- - Upper 16-bits of the Owner UID.
- * - 0x6
- - \_\_le16
- - l\_i\_gid\_high
- - Upper 16-bits of the GID.
- * - 0x8
- - \_\_le16
- - l\_i\_checksum\_lo
- - Lower 16-bits of the inode checksum.
- * - 0xA
- - \_\_le16
- - l\_i\_reserved
- - Unused.
- Hurd:
- .. list-table::
- :widths: 8 8 24 40
- :header-rows: 1
- * - Offset
- - Size
- - Name
- - Description
- * - 0x0
- - \_\_le16
- - h\_i\_reserved1
- - ??
- * - 0x2
- - \_\_u16
- - h\_i\_mode\_high
- - Upper 16-bits of the file mode.
- * - 0x4
- - \_\_le16
- - h\_i\_uid\_high
- - Upper 16-bits of the Owner UID.
- * - 0x6
- - \_\_le16
- - h\_i\_gid\_high
- - Upper 16-bits of the GID.
- * - 0x8
- - \_\_u32
- - h\_i\_author
- - Author code?
- Masix:
- .. list-table::
- :widths: 8 8 24 40
- :header-rows: 1
- * - Offset
- - Size
- - Name
- - Description
- * - 0x0
- - \_\_le16
- - h\_i\_reserved1
- - ??
- * - 0x2
- - \_\_u16
- - m\_i\_file\_acl\_high
- - Upper 16-bits of the extended attribute block (historically, the file
- ACL location).
- * - 0x4
- - \_\_u32
- - m\_i\_reserved2[2]
- - ??
- Inode Size
- ~~~~~~~~~~
- In ext2 and ext3, the inode structure size was fixed at 128 bytes
- (``EXT2_GOOD_OLD_INODE_SIZE``) and each inode had a disk record size of
- 128 bytes. Starting with ext4, it is possible to allocate a larger
- on-disk inode at format time for all inodes in the filesystem to provide
- space beyond the end of the original ext2 inode. The on-disk inode
- record size is recorded in the superblock as ``s_inode_size``. The
- number of bytes actually used by struct ext4\_inode beyond the original
- 128-byte ext2 inode is recorded in the ``i_extra_isize`` field for each
- inode, which allows struct ext4\_inode to grow for a new kernel without
- having to upgrade all of the on-disk inodes. Access to fields beyond
- EXT2\_GOOD\_OLD\_INODE\_SIZE should be verified to be within
- ``i_extra_isize``. By default, ext4 inode records are 256 bytes, and (as
- of August 2019) the inode structure is 160 bytes
- (``i_extra_isize = 32``). The extra space between the end of the inode
- structure and the end of the inode record can be used to store extended
- attributes. Each inode record can be as large as the filesystem block
- size, though this is not terribly efficient.
- Finding an Inode
- ~~~~~~~~~~~~~~~~
- Each block group contains ``sb->s_inodes_per_group`` inodes. Because
- inode 0 is defined not to exist, this formula can be used to find the
- block group that an inode lives in:
- ``bg = (inode_num - 1) / sb->s_inodes_per_group``. The particular inode
- can be found within the block group's inode table at
- ``index = (inode_num - 1) % sb->s_inodes_per_group``. To get the byte
- address within the inode table, use
- ``offset = index * sb->s_inode_size``.
- Inode Timestamps
- ~~~~~~~~~~~~~~~~
- Four timestamps are recorded in the lower 128 bytes of the inode
- structure -- inode change time (ctime), access time (atime), data
- modification time (mtime), and deletion time (dtime). The four fields
- are 32-bit signed integers that represent seconds since the Unix epoch
- (1970-01-01 00:00:00 GMT), which means that the fields will overflow in
- January 2038. For inodes that are not linked from any directory but are
- still open (orphan inodes), the dtime field is overloaded for use with
- the orphan list. The superblock field ``s_last_orphan`` points to the
- first inode in the orphan list; dtime is then the number of the next
- orphaned inode, or zero if there are no more orphans.
- If the inode structure size ``sb->s_inode_size`` is larger than 128
- bytes and the ``i_inode_extra`` field is large enough to encompass the
- respective ``i_[cma]time_extra`` field, the ctime, atime, and mtime
- inode fields are widened to 64 bits. Within this “extra” 32-bit field,
- the lower two bits are used to extend the 32-bit seconds field to be 34
- bit wide; the upper 30 bits are used to provide nanosecond timestamp
- accuracy. Therefore, timestamps should not overflow until May 2446.
- dtime was not widened. There is also a fifth timestamp to record inode
- creation time (crtime); this field is 64-bits wide and decoded in the
- same manner as 64-bit [cma]time. Neither crtime nor dtime are accessible
- through the regular stat() interface, though debugfs will report them.
- We use the 32-bit signed time value plus (2^32 \* (extra epoch bits)).
- In other words:
- .. list-table::
- :widths: 20 20 20 20 20
- :header-rows: 1
- * - Extra epoch bits
- - MSB of 32-bit time
- - Adjustment for signed 32-bit to 64-bit tv\_sec
- - Decoded 64-bit tv\_sec
- - valid time range
- * - 0 0
- - 1
- - 0
- - ``-0x80000000 - -0x00000001``
- - 1901-12-13 to 1969-12-31
- * - 0 0
- - 0
- - 0
- - ``0x000000000 - 0x07fffffff``
- - 1970-01-01 to 2038-01-19
- * - 0 1
- - 1
- - 0x100000000
- - ``0x080000000 - 0x0ffffffff``
- - 2038-01-19 to 2106-02-07
- * - 0 1
- - 0
- - 0x100000000
- - ``0x100000000 - 0x17fffffff``
- - 2106-02-07 to 2174-02-25
- * - 1 0
- - 1
- - 0x200000000
- - ``0x180000000 - 0x1ffffffff``
- - 2174-02-25 to 2242-03-16
- * - 1 0
- - 0
- - 0x200000000
- - ``0x200000000 - 0x27fffffff``
- - 2242-03-16 to 2310-04-04
- * - 1 1
- - 1
- - 0x300000000
- - ``0x280000000 - 0x2ffffffff``
- - 2310-04-04 to 2378-04-22
- * - 1 1
- - 0
- - 0x300000000
- - ``0x300000000 - 0x37fffffff``
- - 2378-04-22 to 2446-05-10
- This is a somewhat odd encoding since there are effectively seven times
- as many positive values as negative values. There have also been
- long-standing bugs decoding and encoding dates beyond 2038, which don't
- seem to be fixed as of kernel 3.12 and e2fsprogs 1.42.8. 64-bit kernels
- incorrectly use the extra epoch bits 1,1 for dates between 1901 and
- 1970. At some point the kernel will be fixed and e2fsck will fix this
- situation, assuming that it is run before 2310.
|