IOCTL-XFS-FSGEOMETRY(2)

💖 ioctl_xfs_fsgeometry(2) — the XFS filesystem vibe report 💖

okay bestie, welcome to the ioctl_xfs_fsgeometry page from the System Calls Manual 💅 this is the one where you ask the kernel "so... what's actually going on with this XFS filesystem of mine?" and it spills ALL the tea.

---

✨ NAME ✨

ioctl_xfs_fsgeometry — report XFS filesystem layout and features 🦋

---

🌸 SYNOPSIS 🌸

#include <xfs/xfs_fs.h>

int ioctl(int fd, XFS_IOC_FSGEOMETRY, struct xfs_fsop_geom *arg);
int ioctl(int fd, XFS_IOC_FSGEOMETRY_V4, struct xfs_fsop_geom_v4 *arg);
int ioctl(int fd, XFS_IOC_FSGEOMETRY_V1, struct xfs_fsop_geom_v1 *arg);

---

👑 DESCRIPTION 👑

So like. You want the details of an XFS filesystem — the layout, the features, all the other descriptive little items. The kernel hands it over in a struct that looks exactly like this, no cap:

struct xfs_fsop_geom {
     __u32         blocksize;
     __u32         rtextsize;
     __u32         agblocks;
     __u32         agcount;
     __u32         logblocks;
     __u32         sectsize;
     __u32         inodesize;
     __u32         imaxpct;
     __u64         datablocks;
     __u64         rtblocks;
     __u64         rtextents;
     __u64         logstart;
     unsigned char uuid[16];
     __u32         sunit;
     __u32         swidth;
     __s32         version;
     __u32         flags;
     __u32         logsectsize;
     __u32         rtsectsize;
     __u32         dirblocksize;
     /* struct xfs_fsop_geom_v1 stops here. */

     __u32         logsunit;
     /* struct xfs_fsop_geom_v4 stops here. */

     __u32         sick;
     __u32         checked;
     __u64         rgextents;
     __u64         rtstart;
     __u64         rtreserved;
     __u64         reserved[14];
};

okay now let's go field by field, i gotchu 🫶

• blocksize — the size of a fundamental filesystem block, in bytes.
• rtextsize — the size of an extent on the realtime volume, in bytes.
• agblocks — the size of an allocation group, measured in filesystem blocks.
• agcount — how many allocation groups the filesystem has.
• logblocks — the size of the log, in units of filesystem blocks.
• sectsize — the smallest amount of data that can be written to the data device atomically, in bytes.
• inodesize — the size of an inode record, in bytes.
• imaxpct — the max percentage of the filesystem that can be handed over to inode record blocks.
• datablocks — the size of the data device, in units of filesystem blocks.
• rtblocks — the size of the realtime device, in units of filesystem blocks.
• rtextents — the number of extents that can be allocated on the realtime device.
• logstart — the start of the log, in units of filesystem blocks. 💫 heads up: if the filesystem has an external log, this will be 0.
• uuid — the universal unique identifier of the filesystem ✨ (yes, the whole personality).
• sunit — what the filesystem has been told is the size of a RAID stripe unit on the underlying data device, in filesystem blocks.
• swidth — what the filesystem has been told is the width of a RAID stripe on the underlying data device, in units of RAID stripe units.
• version — the version of this structure. This value will be XFS_FSOP_GEOM_VERSION.
• flags — tells you which features are enabled on the filesystem. Go look at the FILESYSTEM FEATURE FLAGS section below for the whole rundown on each feature. 👀
• logsectsize — the smallest amount of data that can be written to the log device atomically, in bytes.
• rtsectsize — the smallest amount of data that can be written to the realtime device atomically, in bytes.
• dirblocksize — the size of directory blocks, in bytes.
• logsunit — what the filesystem has been told is the size of a RAID stripe unit on the underlying log device, in filesystem blocks. lowkey important: this field is meaningful only if the flag XFS_FSOP_GEOM_FLAGS_LOGV2 is set.
• sick and checked — these two are giving health check 💀 they indicate the relative health of various whole-filesystem metadata. see the XFS METADATA HEALTH REPORTING section for more details.
• rgextents — Is the number of RT extents in each rtgroup.
• rtstart — Start of the internal RT device in fsblocks. 0 if an external RT device is used. This field is meaningful only if the flag XFS_FSOP_GEOM_FLAGS_ZONED is set.
• rtreserved — The amount of space in the realtime section that is reserved for internal use by garbage collection and reorganization algorithms in fsblocks. This field is meaningful only if the flag XFS_FSOP_GEOM_FLAGS_ZONED is set.
• reserved — is set to zero. that's it. that's the whole job. zero.

---

🌈 FILESYSTEM FEATURE FLAGS 🌈

All the filesystem features get reported to userspace as a combination of the following flags. collect them like stickers 🎀

• XFS_FSOP_GEOM_FLAGS_ATTR — Extended attributes are present.
• XFS_FSOP_GEOM_FLAGS_NLINK — Files on this filesystem support up to 2^32 hard links. If this flag is not set, files on this filesystem support only up to 2^16 hard links.
• XFS_FSOP_GEOM_FLAGS_QUOTA — Quotas are enabled.
• XFS_FSOP_GEOM_FLAGS_IALIGN — Inodes are aligned for better performance.
• XFS_FSOP_GEOM_FLAGS_DALIGN — Filesystem tries to align data block allocations to RAID stripe units for better performance.
• XFS_FSOP_GEOM_FLAGS_SHARED — Unused.
• XFS_FSOP_GEOM_FLAGS_EXTFLG — Filesystem supports unwritten extents.
• XFS_FSOP_GEOM_FLAGS_DIRV2 — Directories are in version 2 format and maintain free space data for better performance. Version 1 format directories are no longer supported. (rip v1, you had a good run 🙈)
• XFS_FSOP_GEOM_FLAGS_LOGV2 — Log uses the V2 format.
• XFS_FSOP_GEOM_FLAGS_SECTOR — The log device has a sector size larger than 512 bytes.
• XFS_FSOP_GEOM_FLAGS_ATTR2 — Filesystem contains V2 extended attributes.
• XFS_FSOP_GEOM_FLAGS_PROJID32 — Project IDs can be as large as 2^32. If this flag is not set, the filesystem supports only 2^16 project IDs.
• XFS_FSOP_GEOM_FLAGS_DIRV2CI — Case-insensitive lookups are supported on directories.
• XFS_FSOP_GEOM_FLAGS_LAZYSB — On-disk superblock counters are updated only at unmount time.
• XFS_FSOP_GEOM_FLAGS_V5SB — Metadata blocks are self describing and contain checksums.
• XFS_FSOP_GEOM_FLAGS_FTYPE — Directories contain inode types in directory entries.
• XFS_FSOP_GEOM_FLAGS_FINOBT — Filesystem maintains an index of free inodes.
• XFS_FSOP_GEOM_FLAGS_SPINODES — Filesystem may allocate discontiguous inode chunks when free space is fragmented.
• XFS_FSOP_GEOM_FLAGS_RMAPBT — Filesystem stores reverse mappings of blocks to owners.
• XFS_FSOP_GEOM_FLAGS_REFLINK — Filesystem supports sharing blocks between files.
• XFS_FSOP_GEOM_FLAGS_EXCHANGE_RANGE — Filesystem can exchange file contents atomically via XFS_IOC_EXCHANGE_RANGE.
• XFS_FSOP_GEOM_FLAGS_METADIR — Filesystem contains a metadata directory tree.
• XFS_FSOP_GEOM_FLAGS_ZONED — Filesystem uses the zoned allocator for the RT device.

---

🩺 XFS METADATA HEALTH REPORTING 🩺

The online filesystem checking utility scans metadata and records what it finds in the kernel incore state. So how does userspace read the incore health status of the filesystem? bestie, it's this scheme right here:

• If a given sick flag is set in sick, then that piece of metadata has been observed to be damaged. The same bit should be set in checked.
• If a given sick flag is set in checked but is not set in sick, then that piece of metadata has been checked and is not faulty.
• If a given sick flag is not set in checked, then no conclusion can be made.

and these are the flags that apply to those fields 🧚

• XFS_FSOP_GEOM_SICK_COUNTERS — Inode and space summary counters.
• XFS_FSOP_GEOM_SICK_UQUOTA — User quota information.
• XFS_FSOP_GEOM_SICK_GQUOTA — Group quota information.
• XFS_FSOP_GEOM_SICK_PQUOTA — Project quota information.
• XFS_FSOP_GEOM_SICK_RT_BITMAP — Free space bitmap for the realtime device.
• XFS_FSOP_GEOM_SICK_RT_SUMMARY — Free space summary for the realtime device.
• XFS_FSOP_GEOM_SICK_QUOTACHECK — Quota resource usage counters.

---

⭐ RETURN VALUE ⭐

On error, -1 is returned, and errno is set to indicate the error. that's the whole deal 💀

---

🔥 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.
• EFSBADCRC — Metadata checksum validation failed while performing the query.
• EFSCORRUPTED — Metadata corruption was encountered while performing the query.
• EIO — An I/O error was encountered while performing the query.

---

💜 CONFORMING TO 💜

This API is specific to XFS filesystem on the Linux kernel. it's giving ✨exclusive✨

---

🦋 SEE ALSO 🦋

• ioctl(2)

---

and that's the page, bestie, you ate it 💅 ngl this one was written by XFS, version dated 2019-06-17 — iconic behavior from 2019 fr fr, and it's still the moment. periodt. 🎀✨👑