--- name: "ioctl_xfs_health_monitor" 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_health_monitor" --- # ioctl\_xfs\_health\_monitor(2) read filesystem health events from the kernel ## NAME ioctl\_xfs\_health\_monitor - read filesystem health events from the kernel ## SYNOPSIS **#include \** **int ioctl(int** *dest\_fd***, XFS\_IOC\_HEALTH\_MONITOR, struct xfs\_health\_monitor \****arg***);** ## DESCRIPTION This XFS ioctl asks the kernel driver to create a pseudo-file from which information about adverse filesystem health events can be read. This new file will be installed into the file descriptor table of the calling process as a read-only file, and will have the close-on-exec flag set. The specific behaviors of this health monitor file are requested via a structure of the following form: ``` struct xfs_health_monitor { __u64 flags; __u8 format; __u8 pad[23]; }; ``` The field *pad* must be zero. The field *format* controls the format of the event data that can be read: - **XFS\_HEALTH\_MONITOR\_FMT\_V0** Event data will be presented in discrete objects of type struct xfs\_health\_monitor\_event. See below for more information. The field *flags* control the behavior of the monitor. - **XFS\_HEALTH\_MONITOR\_VERBOSE** Return all health events, including affirmations of healthy metadata. ## RETURN VALUE On error, -1 is returned, and *errno* is set to indicate the error. Otherwise, the return value is a new file descriptor. ## ERRORS Error codes can be one of, but are not limited to, the following: - **EEXIST** Health monitoring is already active for this filesystem. - **EPERM** The caller does not have permission to open a health monitor. Calling programs must have administrative capability, run in the initial user namespace, and the *fd* passed to ioctl must be the root directory of an XFS filesystem. - **EINVAL** One or more of the arguments specified is invalid. - **EFAULT** The argument could not be copied into the kernel. - **ENOMEM** There was not sufficient memory to construct the health monitor. ## EVENT FORMAT Calling programs retrieve XFS health events by calling [**read**(2)](/read/2.md) on the returned file descriptor. The read buffer must be large enough to hold at least one event object. Partial objects will not be returned; instead, a short read will occur. Events will be returned in the following format: ``` struct xfs_health_monitor_event { __u32 domain; __u32 type; __u64 time_ns; union { struct xfs_health_monitor_lost lost; struct xfs_health_monitor_fs fs; struct xfs_health_monitor_group group; struct xfs_health_monitor_inode inode; struct xfs_health_monitor_shutdown shutdown; struct xfs_health_monitor_media media; struct xfs_health_monitor_filerange filerange; } e; __u64 pad[2]; }; ``` The field *time\_ns* records the timestamp at which the health event was generated, in units of nanoseconds since the Unix epoch. The field *pad* will be zero. The field *domain* indicates the scope of the filesystem affected by the event: - **XFS\_HEALTH\_MONITOR\_DOMAIN\_MOUNT** The entire filesystem is affected. - **XFS\_HEALTH\_MONITOR\_DOMAIN\_FS** Metadata concerning the entire filesystem is affected. Details are available through the *fs* field. - **XFS\_HEALTH\_MONITOR\_DOMAIN\_AG** Metadata concerning a specific allocation group is affected. Details are available through the *group* field. - **XFS\_HEALTH\_MONITOR\_DOMAIN\_RTGROUP** Metadata concerning a specific realtime allocation group is affected. Details are available through the *group* field. - **XFS\_HEALTH\_MONITOR\_DOMAIN\_INODE** File metadata is affected. Details are available through the *inode* field. - **XFS\_HEALTH\_MONITOR\_DOMAIN\_DATADEV** The main data volume is affected. Details are available through the *media* field. - **XFS\_HEALTH\_MONITOR\_DOMAIN\_RTDEV** The realtime volume is affected. Details are available through the *media* field. - **XFS\_HEALTH\_MONITOR\_DOMAIN\_LOGDEV** The external log is affected. Details are available through the *media* field. - **XFS\_HEALTH\_MONITOR\_DOMAIN\_FILERANGE** File data is affected. Details are available through the *filerange* field. The field *type* indicates what was affected by a health event: The following types apply to events from the **MOUNT** domain. - **XFS\_HEALTH\_MONITOR\_TYPE\_RUNNING** This filesystem health monitor is now running. - **XFS\_HEALTH\_MONITOR\_TYPE\_LOST** Health events were lost. Details are available through the *lost* field. - **XFS\_HEALTH\_MONITOR\_TYPE\_UNMOUNT** The filesystem is being unmounted. - **XFS\_HEALTH\_MONITOR\_TYPE\_SHUTDOWN** The filesystem has shut down due to problems. Details are available through the *shutdown* field. The following three types apply to events from the **FS**, **AG**, **RTGROUP**, and **INODE** domains. - **XFS\_HEALTH\_MONITOR\_TYPE\_SICK** Filesystem metadata has been scanned by online fsck and found to be corrupt. - **XFS\_HEALTH\_MONITOR\_TYPE\_CORRUPT** A metadata corruption problem was encountered during a filesystem operation outside of fsck. - **XFS\_HEALTH\_MONITOR\_TYPE\_HEALTHY** Filesystem metadata has either been scanned by online fsck and found to be in good condition, or it has been repaired to good condition. The following type applies to events from the **DATADEV**, **RTDEV**, and **LOGDEV** domains. - **XFS\_HEALTH\_MONITOR\_TYPE\_MEDIA\_ERROR** A media error has been observed on one of the storage devices that can be attached to an XFS filesystem. The following types apply to events from the **FILERANGE** domain. - **XFS\_HEALTH\_MONITOR\_TYPE\_BUFREAD** An attempt to read (or readahead) from a file failed with an I/O error. - **XFS\_HEALTH\_MONITOR\_TYPE\_BUFWRITE** An attempt to write dirty data to storage failed with an I/O error. - **XFS\_HEALTH\_MONITOR\_TYPE\_DIOREAD** A direct read of file data from storage failed with an I/O error. - **XFS\_HEALTH\_MONITOR\_TYPE\_DIOWRITE** A direct write of file data to storage failed with an I/O error. - **XFS\_HEALTH\_MONITOR\_TYPE\_DATALOST** A latent media error was discovered on the storage backing part of this file. The union *e* contains further details about the health event: The kernel will use no more than 32KiB of memory per monitoring file to queue health events. If this limit is exceeded, an event will be generated to describe how many events were lost: ``` struct xfs_health_monitor_lost { __u64 count; }; ``` The *count* field records the number of events lost. If whole-filesystem metadata experiences a health event, the exact type of that metadata is recorded as follows: ``` struct xfs_health_monitor_fs { __u32 mask; }; ``` The *mask* field will contain *XFS\_FSOP\_GEOM\_SICK\_\** flags that are documented in the [**ioctl\_xfs\_fsgeometry**(2)](/ioctl_xfs_fsgeometry/2.md) manual page. If an allocation group (realtime or data) experiences a health event, the exact type and location of the metadata is recorded as follows: ``` struct xfs_health_monitor_group { __u32 mask; __u32 gno; }; ``` The *mask* field will contain *XFS\_AG\_SICK\_\** flags that are documented in the [**ioctl\_xfs\_ag\_geometry**(2)](/ioctl_xfs_ag_geometry/2.md) manual page, or the *XFS\_RTGROUP\_SICK\_\** flags that are documented by the [**ioctl\_xfs\_rtgroup\_geometry**(2)](/ioctl_xfs_rtgroup_geometry/2.md) manual page. The *gno* field will contain the group number. If a file experiences a health event, the exact type and handle to the file is recorded as follows: ``` struct xfs_health_monitor_inode { __u32 mask; __u32 gen; __u64 ino; }; ``` The *mask* field will contain *XFS\_BS\_SICK\_\** flags that are documented by the [**ioctl\_xfs\_bulkstat**(2)](/ioctl_xfs_bulkstat/2.md) manual page. The *ino* and *gen* fields describe a handle to the affected file. If the filesystem shuts down abnormally, the exact reasons are recorded as follows: ``` struct xfs_health_monitor_shutdown { __u32 reasons; }; ``` The *reasons* field is a combination of the following values: - **XFS\_HEALTH\_SHUTDOWN\_META\_IO\_ERROR** Metadata I/O errors were encountered. - **XFS\_HEALTH\_SHUTDOWN\_LOG\_IO\_ERROR** Log I/O errors were encountered. - **XFS\_HEALTH\_SHUTDOWN\_FORCE\_UMOUNT** The filesystem was forcibly shut down by an administrator. - **XFS\_HEALTH\_SHUTDOWN\_CORRUPT\_INCORE** In-memory metadata are corrupt. - **XFS\_HEALTH\_SHUTDOWN\_CORRUPT\_ONDISK** On-disk metadata are corrupt. - **XFS\_HEALTH\_SHUTDOWN\_DEVICE\_REMOVED** Storage devices were removed. If a media error is discovered on the storage device, the exact location is recorded as follows: ``` struct xfs_health_monitor_media { __u64 daddr; __u64 bbcount; }; ``` The *daddr* and *bbcount* fields describe the range of the storage that were lost. Both are provided in units of 512-byte blocks. If a problem is discovered with regular file data, the handle of the file and the exact range of the file are recorded as follows: ``` struct xfs_health_monitor_filerange { __u64 pos; __u64 len; __u64 ino; __u32 gen; __u32 error; }; ``` The *ino* and *gen* fields describe a handle to the affected file. The *pos* and *len* fields describe the range of the file data that are affected. Both are provided in units of bytes. The *error* field describes the error that occurred. See the [**errno**(3)](/errno/3.md) manual page for more information. ## CONFORMING TO This API is specific to XFS filesystem on the Linux kernel. ## SEE ALSO [**ioctl\_xfs\_health\_fd\_on\_monitored\_fs**(2)](/ioctl_xfs_health_fd_on_monitored_fs/2.md)