---
name: "ioctl_xfs_ag_geometry"
section: "2"
platform: "linux"
package: "xfsprogs"
version: "7.2.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ioctl_xfs_ag_geometry"
---

# ioctl\_xfs\_ag\_geometry(2)

query XFS allocation group geometry information

## NAME

ioctl\_xfs\_ag\_geometry - query XFS allocation group geometry information

## 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. 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];
};
```

- *ag\_number*

  The caller must set this field to the index of the allocation group that the caller wishes to learn about.

- *ag\_length*

  The length of the allocation group is returned in this field, in units of filesystem blocks.

- *ag\_freeblks*

  The number of free blocks in the allocation group is returned in this field, in units of filesystem blocks.

- *ag\_icount*

  The number of inode records allocated in this allocation group is returned in this field.

- *ag\_ifree*

  The number of unused inode records (of the space allocated) in this allocation group is returned in this field.

- *ag\_flags*

  The caller can set this field to change the operational behavior of the ioctl. Currently no flags are defined, so this field must be zero.

- *ag\_reserved*

  All reserved fields will be set to zero on return.

The fields *ag\_sick* and *ag\_checked* indicate the relative health of various allocation group 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*.

- •

  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.

- •

  If a given sick flag is not set in *ag\_checked*, then no conclusion can be made.

The following flags 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.

## ERRORS

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

- **EFSBADCRC**

  Metadata checksum validation failed while performing the query.

- **EFSCORRUPTED**

  Metadata corruption was encountered while performing the query.

- **EINVAL**

  The specified allocation group number is not valid for this filesystem.

- **EIO**

  An I/O error was encountered while performing the query.

## CONFORMING TO

This API is specific to XFS filesystem on the Linux kernel.

## SEE ALSO

[**ioctl**(2)](/ioctl/2.md)