IOCTL-XFS-AG-GEOMETRY(2)

💖 ioctl_xfs_ag_geometry — bestie, let's go snooping on your XFS allocation groups 💖

okay so this is a page from the System Calls Manual, section 2 — that's the IOCTL-XFS-AG-GEOMETRY(2) one, iykyk 🦋

✨ NAME ✨

ioctl_xfs_ag_geometry — query XFS allocation group geometry information

like. it literally just asks your filesystem "hey girl, tell me everything about this one allocation group" and the filesystem is like "say less 💅"

🌸 SYNOPSIS 🌸

#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_AG_GEOMETRY, struct xfs_ag_geometry *arg);

🎀 DESCRIPTION 🎀

This XFS ioctl retrieves the geometry information for a given allocation group. Not me pulling up receipts on your AG's whole life story 💖

The geometry information is conveyed in a structure of the following form:

struct xfs_ag_geometry {
     uint32_t  ag_number;
     uint32_t  ag_length;
     uint32_t  ag_freeblks;
     uint32_t  ag_icount;
     uint32_t  ag_ifree;
     uint32_t  ag_sick;
     uint32_t  ag_checked;
     uint32_t  ag_flags;
     uint64_t  ag_reserved[12];
};

okay now let's meet the fields one by one, they're all main characters 🫶

• ag_number — bestie you have to set this one yourself. Put in the index of the allocation group you wanna learn about. It's giving "you must choose your fighter" ⭐
• ag_length — the length of the allocation group comes back here, measured in units of filesystem blocks.
• ag_freeblks — how many free blocks are chillin' in this allocation group. Also in units of filesystem blocks.
• ag_icount — the number of inode records allocated in this allocation group. comes back here ✨
• ag_ifree — the number of unused inode records (of the space allocated) in this allocation group. returned right here, no cap.
• ag_flags — you can set this field to change the operational behavior of the ioctl. but… currently no flags are defined, so this field must be zero. literally zero. don't try it 💀
• ag_reserved — all reserved fields will be set to zero on return. every single one. periodt.

🌈 health check time: ag_sick and ag_checked 🌈

The fields ag_sick and ag_checked indicate the relative health of various allocation group metadata. it's basically a vibe check for your metadata 🩺

• If a given sick flag is set in ag_sick, then that piece of metadata has been observed to be damaged. The same bit will be set in ag_checked. she's hurt, fr fr 😭
• If a given sick flag is set in ag_checked and is not set in ag_sick, then that piece of metadata has been checked and is not faulty. she's fine, she ate 🔥
• If a given sick flag is not set in ag_checked, then no conclusion can be made. we simply do not know. shrug 🙈

👑 the flags that apply to these fields 👑

• XFS_AG_GEOM_SICK_SB — Allocation group superblock.
• XFS_AG_GEOM_SICK_AGF — Free space header.
• XFS_AG_GEOM_SICK_AGFL — Free space reserve list.
• XFS_AG_GEOM_SICK_AGI — Inode header.
• XFS_AG_GEOM_SICK_BNOBT or XFS_AG_GEOM_SICK_CNTBT — Free space btrees.
• XFS_AG_GEOM_SICK_INOBT or XFS_AG_GEOM_SICK_FINOBT — Inode btrees.
• XFS_AG_GEOM_SICK_RMAPBT — Reverse mapping btree.
• XFS_AG_GEOM_SICK_REFCNTBT — Reference count btree.

💫 RETURN VALUE 💫

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

like yeah. it's -1. the classic "we have a problem" number 💀

🚨 ERRORS 🚨

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

• EFSBADCRC — Metadata checksum validation failed while performing the query. the checksum said "not today" 😭
• EFSCORRUPTED — Metadata corruption was encountered while performing the query. uh oh. something's broken in there 🩹
• EINVAL — The specified allocation group number is not valid for this filesystem. bestie that AG does not exist, stop it 🙈
• EIO — An I/O error was encountered while performing the query. the disk is being dramatic 🫠

lowkey note: these are the ones listed but the list is "not limited to" these, so other error codes can show up too. just so you're not blindsided 💅

🌟 CONFORMING TO 🌟

This API is specific to XFS filesystem on the Linux kernel. it's an XFS-exclusive, no gatekeeping, but also no portability 🌸

🦋 SEE ALSO 🦋

• ioctl(2)

okay that's the whole page, you're officially an XFS allocation group gossip now 💜

this was the XFS manual, dated 2019-08-30 — mwah, bye bestie, go query responsibly 🎀✨🫶