IOCTL-XFS-SCRUBV-METADATA(2)

💖 IOCTL-XFS-SCRUBV-METADATA 💖

okay bestie, welcome to the System Calls Manual page for ioctl_xfs_scrubv_metadata, aka the XFS ioctl that does a whole vibe check on a bunch of your filesystem metadata at once. sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

ioctl_xfs_scrubv_metadata — check a lot of XFS filesystem metadata 💅

✨ SYNOPSIS ✨

#include <xfs/xfs_fs.h>

int ioctl(int dest_fd, XFS_IOC_SCRUBV_METADATA, struct
xfs_scrub_vec_head *arg);

✨ DESCRIPTION ✨

so basically, this XFS ioctl walks up to the kernel driver and is like "hey, can you look at several pieces of filesystem metadata for errors, or for metadata that's just... not giving? 😬" and the kernel is like "say less." Multiple scrub types can be invoked to target a single filesystem object. If you want the whole discussion of what metadata validation even is, plus documentation of all the various XFS_SCRUB_TYPE and XFS_SCRUB_FLAGS values mentioned below, go read ioctl_xfs_scrub_metadata(2). it's giving prequel. 📖

The types and location of the metadata to scrub are conveyed as a vector with a header of the following form:

struct xfs_scrub_vec_head {
     __u64 svh_ino;
     __u32 svh_gen;
     __u32 svh_agno;
     __u32 svh_flags;
     __u16 svh_rest_us;
     __u16 svh_nr;
     __u64 svh_reserved;
     __u64 svh_vectors;
};

The fields svh_ino, svh_gen, and svh_agno correspond to the sm_ino, sm_gen, and sm_agno fields of the regular scrub ioctl. Exactly one filesystem object can be specified in a single call — one object per call, we do not share, this is a monogamous syscall 🫶. The kernel will proceed with each vector in svh_vectors until progress is no longer possible.

The field svh_rest_us specifies an amount of time to pause between each scrub invocation to give the system a chance to process other requests. like a little breather. a hydration break. 💧

The field svh_nr specifies the number of vectors in the svh_vectors array.

The field svh_vectors is a pointer to an array of struct xfs_scrub_vec structures.

The field svh_reserved must be zero. zero. nada. nothing. don't even think about it 🙈

Each vector has the following form:

struct xfs_scrub_vec {
     __u32 sv_type;
     __u32 sv_flags;
     __s32 sv_ret;
     __u32 sv_reserved;
};

The fields sv_type and sv_flags indicate the type of metadata to check and the behavioral changes that userspace will permit of the kernel. The sv_flags field will be updated upon completion of the scrub call — so it's not just input, it's got main character energy coming and going. ✨ See the documentation of XFS_SCRUB_TYPE_* and XFS_SCRUB_[IO]FLAG_* values in ioctl_xfs_scrub_metadata(2) for a detailed description of their purpose.

If a vector's sv_type field is set to the value XFS_SCRUB_TYPE_BARRIER, the kernel will stop processing vectors and return to userspace if a scrubber flags corruption by setting one of the XFS_SCRUB_OFLAG_* values in sv_flags or returns an operation error in sv_ret. Otherwise, the kernel returns only after processing all vectors. so like... it's a barrier. a little "we stop here if it's messy" checkpoint 🚧

The sv_ret field is set to the return value of the scrub function. See the RETURN VALUE section of the ioctl_xfs_scrub_metadata(2) manual page for more information.

The sv_reserved field must be zero. again. zero. it's the rule. ⭐

✨ RETURN VALUE ✨

On error, -1 is returned, and errno is set to indicate the error. classic. 😭

✨ ERRORS ✨

Error codes can be one of, but are not limited to, the following:

• EINVAL — One or more of the arguments specified is invalid. (not me passing a bad argument 😔)
• EINTR — The operation was interrupted.
• ENOMEM — There was not sufficient memory to perform the scrub or repair operation. bestie we are BROKE on memory 💀
• EFAULT — A memory fault was encountered while reading or writing the vector.

✨ CONFORMING TO ✨

This API is specific to XFS filesystem on the Linux kernel. it does not play nice with others, it's exclusive, it's an XFS-only situation 💜

✨ NOTES ✨

These operations may block other filesystem operations for a long time. A calling process can stop the operation by being sent a fatal signal, but non-fatal signals are blocked.

translation: it can hog the whole filesystem for a while, and the only way out is a fatal signal. non-fatal signals? blocked. ignored. not the moment. 😤

✨ SEE ALSO ✨

ioctl(2) · ioctl_xfs_scrub_metadata(2) · xfs_scrub(8) · xfs_repair(8)

and that's the whole page bestie!! 🎀 this one's from XFS, dated 2024-05-21, and it lives under the manual name IOCTL-XFS-SCRUBV-METADATA(2) — slay, go scrub something responsibly 💅✨