IOCTL-XFS-FSINUMBERS(2)

💖 ioctl_xfs_fsinumbers — it's giving inode inventory ✨

okay bestie, welcome to section 2 of the System Calls Manual, where we're talking about ioctl_xfs_fsinumbers, which is literally the way you pull a whole list of valid inode numbers out of an XFS filesystem. it's not a libc thing, it's a system call manual thing, iykyk 🎀

🌸 NAME 🌸

ioctl_xfs_fsinumbers</p> — extract a list of valid inode numbers from an XFS filesystem 🦋

💅 SYNOPSIS 💅

#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_FSINUMBERS, struct xfs_fsop_bulkreq *arg);

✨ DESCRIPTION ✨

so this bad boy queries inode allocation info from an XFS filesystem. the vibe is that you're supposed to call it iteratively until you've got the entire set of inodes — it's not a one-and-done situation, it's a "keep going until it says zero" situation, no cap 💀

these ioctls use struct xfs_fsop_bulkreq to set up a bulk transfer with the kernel:

struct xfs_fsop_bulkreq {
     __u64   *lastip;
     __s32   count;
     void    *ubuffer;
     __s32   *ocount;
};

lastip points to a value that will receive the number of the "last inode." set it to one less than the number of the first inode you want info about, or set it to zero if you wanna start with the very first inode in the filesystem. after the call, this value gets updated to the number of the last inode for which information is supplied. 🫶 heads up tho — this field will not be updated if ocount is NULL.

count is the number of elements in the ubuffer array, and therefore the number of inode groups you want allocation info for. it's giving "how many at a time, bestie" 💖

ocount points to a value that receives the number of records returned. an output value of zero means there are no more inode groups left to enumerate — that's your finish line, babes 🏁 if this value is NULL, then neither ocount nor lastip will be updated. yes, both. together. they're a package deal 💀

ubuffer points to a memory buffer where inode group information gets copied. this buffer must be an array of struct xfs_inogrp, which we're describing below. the array must have at least count elements. ⭐

struct xfs_inogrp {
     __u64   xi_startino;
     __s32   xi_alloccount;
     __u64   xi_allocmask;
}

this structure describes inode usage info for a group of 64 consecutive inode numbers. the fields are as follows, bestie, stay with me:

xi_startino is the first inode number of this group. 🌸

xi_alloccount is the number of bits that are set in xi_allocmask. this is the number of inodes allocated in this group. it's the headcount, basically 💅

xi_allocmask is a bitmask of inodes that are allocated in this inode group. the bitmask is 64 bits long, and the least significant bit corresponds to inode xi_startino. 🦋

😭 RETURN VALUE 😭

on error, -1 is returned, and errno is set to indicate the error. classic. not me getting a negative one 😭

💀 ERRORS 💀

error codes can be one of, but are not limited to, the following — so like, don't assume this list is the whole alphabet, bestie:

• EFAULT — the kernel was not able to copy into the userspace buffer. rude, honestly.
• EFSBADCRC — metadata checksum validation failed while performing the query. the checksum said "no ❤️".
• EFSCORRUPTED — metadata corruption was encountered while performing the query. something is deeply wrong in there 🙈
• EINVAL — one of the arguments was not valid. you passed it something cursed, bestie.
• EIO — an I/O error was encountered while performing the query. the disk said "not today" 💀
• ENOMEM — there was insufficient memory to perform the query. no room, no vibes.

👑 CONFORMING TO 👑

this API is specific to XFS filesystem on the Linux kernel. periodt. it's a very exclusive club, no other filesystem invited 💅

🌈 SEE ALSO 🌈

• ioctl(2)

and that's the whole page, bestie!! this was XFS, dated 2019-06-17, and it lives in the IOCTL-XFS-FSINUMBERS(2) corner of the manual. go forth and enumerate those inodes, you absolute icon 👑✨🎀