IOCTL-XFS-GETBMAPX(2)

💖 ioctl_xfs_getbmapx — like, the System Calls Manual page for querying extent info 💖

okay so bestie, welcome to ioctl_xfs_getbmapx, straight out of the System Calls Manual. it's a little query tool that asks an open file "hey, where do your blocks actually live?" and XFS answers. no cap. let's get into it 🦋

✨ NAME ✨

ioctl_xfs_getbmapx — query extent information for an open file

🌸 SYNOPSIS 🌸

#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_GETBMAP, struct getbmap *arg);
int ioctl(int fd, XFS_IOC_GETBMAPA, struct getbmap *arg);
int ioctl(int fd, XFS_IOC_GETBMAPX, struct getbmapx *arg);

👑 DESCRIPTION 👑

So basically, this gets you the block map for a segment of a file living in an XFS file system. The mapping info gets handed back to you through an array of structs that look like this, periodt:

struct getbmap {
     __s64   bmv_offset;
     __s64   bmv_block;
     __s64   bmv_length;
     __s32   bmv_count;
     __s32   bmv_entries;
};

And the XFS_IOC_GETBMAPX ioctl is just the glow-up version — it uses a bigger, more main-character struct:

struct getbmapx {
     __s64   bmv_offset;
     __s64   bmv_block;
     __s64   bmv_length;
     __s32   bmv_count;
     __s32   bmv_entries;
     __s32   bmv_iflags;
     __s32   bmv_oflags;
     __s32   bmv_unused1;
     __s32   bmv_unused2;
};

📏 Important vibe check: all sizes and offsets in the structure are in units of 512 bytes. don't forget it iykyk.

The first struct in the array is the header, and the rest of the structs in the array get filled with block map info when the call returns. The header is the one steering those iterative calls, so fill it out like this:

• bmv_offset — the file offset of the area of interest in the file.
• bmv_length — the length of the area of interest in the file. set it to -1 and the interesting area is just the rest of the file, easy peasy 🌈
• bmv_count — the number of elements in the array, including this header. minimum value is 2. that's the floor, bestie.
• bmv_entries — the number of entries actually filled in by the call. you don't need to fill this out before the call. it can be zero if no extents were found in the requested range, or if iterated calls have reached the end of the requested range.
• bmv_iflags — for the XFS_IOC_GETBMAPX function, this is a bitmask holding a combo of these flags:
  • BMV_IF_ATTRFORK — return information about the extended attribute fork.
  • BMV_IF_PREALLOC — return information about unwritten pre-allocated segments.
  • BMV_IF_DELALLOC — return information about delayed allocation reservation segments.
  • BMV_IF_NO_HOLES — do not return information about holes.

The other bmv_* fields in the header are just... ignored. literally nobody's looking at them 💀

When a call returns successfully, the offset and length values in the header get updated so you can reuse the command to grab more info — it's giving efficient, it's giving recycling ♻️. The remaining elements of the array get filled out by the call like so:

• bmv_offset — file offset of segment.
• bmv_block — physical starting block of segment. if this is -1, then the segment is a hole. (a hole!! 😭)
• bmv_length — length of segment.
• bmv_oflags — the XFS_IOC_GETBMAPX function fills this field with a combination of these flags:
  • BMV_OF_PREALLOC — the segment is an unwritten pre-allocation.
  • BMV_OF_DELALLOC — the segment is a delayed allocation reservation.
  • BMV_OF_LAST — this segment is the last in the file. the finale. the last one in the group chat 🫶
  • BMV_OF_SHARED — this segment shares blocks with other files.

The other bmv_* fields are unused in the array of output records. just vibing there. unused.

Oh and also 🎀: the XFS_IOC_GETBMAPA command is identical to XFS_IOC_GETBMAP except that information about the attribute fork of the file is returned. that's the whole difference, slay.

⭐ 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:

• EFAULT — the kernel was not able to copy into the userspace buffer. rude of it.
• EFSBADCRC — metadata checksum validation failed while performing the query.
• EFSCORRUPTED — metadata corruption was encountered while performing the query.
• EINVAL — one of the arguments was not valid.
• EIO — an I/O error was encountered while performing the query.
• ENOMEM — there was insufficient memory to perform the query.

lowkey if you see EFSBADCRC or EFSCORRUPTED, something is genuinely not okay with your metadata. not a vibe. 😭

💅 CONFORMING TO 💅

This API is specific to XFS filesystem on the Linux kernel. exclusive. it's giving XFS-only, no gatekeeping but also no other filesystems 💜

🔥 SEE ALSO 🔥

• ioctl(2)

okay that's the whole page bestie, you ate that 🫶 this was XFS, dated 2019-06-17 — go forth and map those blocks, mwah 💖✨