IOCTL-XFS-INUMBERS(2)

💖 ioctl-xfs-inumbers — the manual page, but make it cute ✨

okay bestie, this is ioctl-xfs-inumbers(2) from the System Calls Manual, and it's literally the glow-up your XFS inode-querying era needed. no cap. 🦋

🌸 NAME 🌸

ioctl_xfs_inumbers — ask the kernel for allocation info about whole groups of XFS inodes, not just one at a time. it's giving bulk energy 👑

✨ SYNOPSIS ✨

#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_INUMBERS, struct xfs_inumbers_req *arg);

💅 DESCRIPTION 💅

so the whole vibe here is: you wanna know which inodes are allocated, but you're not about to do it one by one like some kind of peasant. this ioctl does a bulk transfer straight from the kernel, and it uses struct xfs_inumbers_req to set that up. iconic.

struct xfs_inumbers_req {
     struct xfs_bulk_ireq    hdr;
     struct xfs_inumbers     inumbers[];
};

and yes, the xfs_inumbers structure definition is coming, keep scrolling bestie 🫶

struct xfs_bulk_ireq {
     uint64_t                ino;
     uint32_t                flags;
     uint32_t                icount;
     uint32_t                ocount;
     uint32_t                agno;
     uint64_t                reserved[5];
};

hdr is the part that describes what you're querying. its layout and behavior are fully documented over in the ioctl_xfs_bulkstat(2) manpage, so we're not gonna re-explain all that here. go read that one, it's a whole thing, and this page said not to discuss it further. periodt. 💀

inumbers is an array of struct xfs_inumbers, which is the next thing down there 👇 that array must have at least icount elements. no skimping.

struct xfs_inumbers {
     uint64_t                xi_startino;
     uint64_t                xi_allocmask;
     uint8_t                 xi_alloccount;
     uint8_t                 xi_version;
     uint8_t                 xi_padding[6];
};

this little struct describes inode usage info for a group of 64 consecutive inode numbers. sixty-four. a whole squad. 🎀

• xi_startino — the first inode number of this group. the leader of the pack, the main character 👑
• xi_allocmask — a bitmask telling you which inodes in the group are allocated. to clarify (because the kernel is extra like that): bit N is set if inode xi_startino+N is allocated. 💅
• xi_alloccount — how many inodes in this group are allocated. this should be equal to popcnt(xi_allocmask). like, that's the math, bestie. 🧮
• xi_version — the version of this data structure. the kernel will set it to XFS_INUMBERS_VERSION_V5. slay ⭐
• xi_padding[6] — zeroed. just vibes and emptiness. 🫧

🔥 RETURN VALUE 🔥

if something goes wrong, -1 comes back at you and errno gets set to tell you what happened. that's it, that's the drama. 😭

💀 ERRORS 💀

error codes can be one of, but are not limited to, these cuties:

• EFAULT — the kernel could not copy into the userspace buffer. sad. 🙈
• EFSBADCRC — metadata checksum validation failed while doing the query. the checksum said nope. 💔
• EFSCORRUPTED — metadata corruption was encountered while doing the query. something is deeply wrong in there. 😱
• EINVAL — one of the arguments was not valid. invalid argument era. 🚫
• EIO — an I/O error was encountered while doing the query. 👎
• ENOMEM — not enough memory to do the query. the RAM said "not today". 💸

🌈 CONFORMING TO 🌈

this API is specific to the XFS filesystem on the Linux kernel. it does not play nice with others, it's exclusive. 💜

🦋 SEE ALSO 🦋

• ioctl(2)
• ioctl_xfs_bulkstat(2)

okay that's the whole page, you're officially an XFS inode-group querying girly now 💖 go forth and ioctl responsibly. and yes, this lil masterpiece is from XFS, dated 2019-05-23 — old but so iconic, she's been serving since 2019 and she's still booked and busy ✨🎀

mwah 💋 bye bestie!