filesystems/ext4/journal.rst

6 Introduced in ext3, the ext4 filesystem employs a journal to protect the
7 filesystem against metadata inconsistencies in the case of a system crash. Up
9 size limits) can be reserved inside the filesystem as a place to land
12 cache, a record of the data being committed is also written to the journal. At
14 final locations on disk (this could involve a lot of seeking or a lot of small
19 guarantee that the filesystem does not become stuck midway through a
24 guaranteed to be in any consistent state after a crash. If this default
25 guarantee level (``data=ordered``) is not satisfactory, there is a mount
37 or if JBD2 commit timer goes off, Ext4 performs a traditional full commit.
38 A full commit invalidates all the fast commits that happened before
53 The maximum size of a journal embedded in an ext4 filesystem is 2^32
73 Notice that a transaction begins with either a descriptor and some data,
74 or a block revocation list. A finished transaction always ends with a
82 device (as opposed to an internal journal, which uses a reserved inode).
85 will be an ext4 super block in the usual place, with a matching UUID.
108 Every block in the journal starts with a common 12-byte header
112    :widths: 8 8 24 40
144      - Descriptor. This block precedes a series of data blocks that were
145        written through the journal during a transaction.
147      - Block commit record. This block signifies the completion of a
168    :widths: 8 8 24 40
182      - Common header identifying this as a superblock.
215      - The remaining fields are only valid in a v2 superblock.
269      - s_padding[40]
351 described by a data structure, but here is the block structure anyway.
352 Descriptor blocks consume at least 36 bytes, but use a full block:
355    :widths: 8 8 24 40
380    :widths: 8 8 24 40
416      - A UUID to go with this tag. This field appears to be copied from the
446    :widths: 8 8 24 40
487      - A UUID to go with this tag. This field appears to be copied from the
492 JBD2_FEATURE_INCOMPAT_CSUM_V3 are set, the end of the block is a
496    :widths: 8 8 24 40
521 A revocation block is used to prevent replay of a block in an earlier
523 time but are no longer journalled. Typically this happens if a metadata
524 block is freed and re-allocated as a file data block; in this case, a
530 mistakenly thought. Any block being added to a transaction will cause
535 length, but use a full block:
538    :widths: 8 8 24 40
558 After r_count is a linear array of block numbers that are effectively
565 block is a ``struct jbd2_journal_revoke_tail``, which has this format:
568    :widths: 8 8 24 40
583 The commit block is a sentry that indicates that a transaction has been
589 bytes long (but uses a full block):
592    :widths: 8 8 24 40
637 Fast commit area is organized as a log of tag length values. Each TLV has
638 a ``struct ext4_fc_tl`` in the beginning which stores the tag and the length
665      - Create directory entry for a newly created file
670      - Link a directory entry to an inode
674      - Unlink a directory entry of an inode
684      - Mark the end of a fast commit
694 committing is that it stores the result of a particular operation instead of
697 Let's consider this rename operation: 'mv /a /b'. Let's assume dirent '/a'
699 operation as a procedure "rename a to b", we store the resulting file system
700 state as a "series" of outcomes:
703 - Unlink dirent a
709 Let's take an example of a procedure that is not idempotent and see how fast
712 1) rm A
713 2) mv B A
714 3) read A
718 file A (which was actually created as a result of "mv B A" operation) would get
719 deleted. Thus, file named A would be absent when we try to read A. So, this
724 (Let's assume dirent A was linked to inode 10 and dirent B was linked to
727 1) Unlink A
728 2) Link A to inode 11
732 If we crash after (3) we will have file A linked to inode 11. During the second
733 replay, we will remove file A (inode 11). But we will create it back and make
736 replay of last inode 11 tag. Thus, by converting a non-idempotent procedure
737 into a series of idempotent outcomes, fast commits ensured idempotence during
749 A journal checkpoint can be triggered from userspace via the ioctl
750 EXT4_IOC_CHECKPOINT. This ioctl takes a single, u64 argument for flags.
754 any checkpointing. This can be used to check whether the ioctl exists on a
760 cannot both be set. The ioctl may be useful when snapshotting a system or for