XFSCTL(3)

🎀 NAME 🎀

okay so bestie, meet xfsctl — that's the section 3 girlie from the Library Functions Manual, and her whole job is literally controlling XFS filesystems and individual files. that's it. that's the gig. 💅

🌸 C SYNOPSIS 🌸

like, this is how you call her:

#include <xfs/xfs.h>

int xfsctl(const char *path, int fd, int cmd, void *ptr);

int platform_test_xfs_fd(int fd);
int platform_test_xfs_path(const char *path);

✨ DESCRIPTION ✨

so some functionality that's specific to the XFS filesystem is accessible to applications through platform-specific system call interfaces. these operations split into two sections — the ones that operate on individual files, and the ones that operate on the filesystem itself.

bestie, be careful out here. when you're issuing xfsctl() calls, make sure the target path and the file descriptor (yes, you have to supply BOTH) actually do represent a file from an XFS filesystem. 🫶

the statfs(2) and fstatfs(2) system calls can be used to figure out whether or not some arbitrary path or file descriptor belongs to an XFS filesystem. the thing is, they're not portable though — so the routines platform_test_xfs_fd() and platform_test_xfs_path() give you a platform-independent mechanism instead. slay. ✨

💖 File Operations 💖

to effect an operation on an individual file, the pathname and descriptor arguments you pass to xfsctl identify the file being operated on. the final argument described below refers to the final argument of xfsctl. all of the data structures and macros mentioned below are defined in the <xfs/xfs_fs.h> header file.

• XFS_IOC_ALLOCSP, XFS_IOC_ALLOCSP64, XFS_IOC_FREESP, XFS_IOC_FREESP64 — alter the storage space associated with a section of the ordinary file specified. the section is specified by a variable of type xfs_flock64_t, pointed to by the final argument. the data type xfs_flock64_t contains these members: l_whence is 0, 1, or 2 to indicate that the relative offset l_start will be measured from the start of the file, the current position, or the end of the file, respectively (i.e., l_start is the offset from the position specified in l_whence). if the offset specified is before the current end of file, any data previously written into this section is no longer accessible. if the offset specified is beyond the current end of file, the file is grown and filled with zeroes. the l_len field is currently ignored, and should be set to zero.

XFS_IOC_ALLOCSP, XFS_IOC_ALLOCSP64, XFS_IOC_FREESP and XFS_IOC_FREESP64 operations are all identical.

🚨 these ioctls are no longer supported as of Linux 5.17.

• XFS_IOC_FSSETDM — set the di_dmevmask and di_dmstate fields in an XFS on-disk inode. the only legitimate values for these fields are the ones previously returned in the bs_dmevmask and bs_dmstate fields of the bulkstat structure. the data referred to by the final argument is a struct fsdmidata. this structure's members are fsd_dmevmask and fsd_dmstate. the di_dmevmask field gets set to the value in fsd_dmevmask, and the di_dmstate field gets set to the value in fsd_dmstate. this command is restricted to root or to processes with device management capabilities. its sole purpose is to let backup and restore programs restore those critical on-disk inode fields, iykyk.

🚨 this ioctl is not supported as of Linux 5.5.

• XFS_IOC_DIOINFO — get the info required to perform direct I/O on the specified file descriptor. direct I/O is performed directly to and from a user's data buffer. since the kernel's buffer cache is no longer between the two, the user's data buffer has to conform to the same type of constraints as required for accessing a raw disk partition. the final argument points to a variable of type struct dioattr, which contains these members: d_mem is the memory alignment requirement of the user's data buffer. d_miniosz specifies block size, minimum I/O request size, and I/O alignment — the size of all I/O requests must be a multiple of this amount, and the value of the seek pointer at the time of the I/O request must also be an integer multiple of this amount. d_maxiosz is the maximum I/O request size which can be performed on the file descriptor. if an I/O request does not meet these constraints, the read(2) or write(2) will fail with EINVAL. 💀 all I/O requests are kept consistent with any data brought into the cache with an access through a non-direct I/O file descriptor.
• XFS_IOC_FSGETXATTR, XFS_IOC_FSGETXATTRA, XFS_IOC_FSSETXATTR — see ioctl_xfs_fsgetxattr(2) for more information. ✨
• XFS_IOC_GETBMAP, XFS_IOC_GETBMAPA, XFS_IOC_GETBMAPX — see ioctl_getbmap(2) for more information. ✨
• XFS_IOC_RESVSP, XFS_IOC_RESVSP64 — this command allocates space to a file. a range of bytes is specified using a pointer to a variable of type xfs_flock64_t in the final argument. the blocks are allocated, but not zeroed, and the file size does not change. if the XFS filesystem is configured to flag unwritten file extents, performance will be negatively affected when writing to preallocated space, since extra filesystem transactions are required to convert extent flags on the range of the file written. if xfs_info(8) reports unwritten=1, then the filesystem was made to flag unwritten extents.
• XFS_IOC_UNRESVSP, XFS_IOC_UNRESVSP64 — this command frees space from a file. a range of bytes is specified using a pointer to a variable of type xfs_flock64_t in the final argument. partial filesystem blocks are zeroed, and whole filesystem blocks are removed from the file. the file size does not change. 🧚
• XFS_IOC_ZERO_RANGE — this command converts a range of a file to zeros without issuing data IO. a range of bytes is specified using a pointer to a variable of type xfs_flock64_t in the final argument. blocks are preallocated for regions that span holes in the file, and the entire range is converted to unwritten extents. this operation is a fast method of overwriting any from the range specified with zeros without removing any blocks or having to write zeros to disk. any subsequent read in the given range will return zeros until new data is written. this functionality requires filesystems to support unwritten extents. if xfs_info(8) reports unwritten=1, then the filesystem was made to flag unwritten extents.
• XFS_IOC_PATH_TO_HANDLE, XFS_IOC_PATH_TO_FSHANDLE, XFS_IOC_FD_TO_HANDLE, XFS_IOC_OPEN_BY_HANDLE, XFS_IOC_READLINK_BY_HANDLE, XFS_IOC_ATTR_LIST_BY_HANDLE, XFS_IOC_ATTR_MULTI_BY_HANDLE, XFS_IOC_FSSETDM_BY_HANDLE — these are all interfaces that are used to implement various libhandle functions (see open_by_handle(3)). they are all subject to change and should not be called directly by applications.

🚨 XFS_IOC_FSSETDM_BY_HANDLE is not supported as of Linux 5.5.

🦋 Filesystem Operations 🦋

to effect one of the following operations, the pathname and descriptor arguments passed to xfsctl() can be any open file in the XFS filesystem in question. easy. 😌

• XFS_IOC_FSINUMBERS — see ioctl_xfs_fsinumbers(2) for more information.
• XFS_IOC_FSGEOMETRY — see ioctl_xfs_fsgeometry(2) for more information.
• XFS_IOC_AG_GEOMETRY — see ioctl_xfs_ag_geometry(2) for more information.
• XFS_IOC_FSBULKSTAT or XFS_IOC_FSBULKSTAT_SINGLE — see ioctl_xfs_fsbulkstat(2) for more information.
• XFS_IOC_SCRUB_METADATA — see ioctl_xfs_scrub_metadata(2) for more information.
• XFS_IOC_FSCOUNTS — see ioctl_xfs_fscounts(2) for more information.
• XFS_IOC_GET_RESBLKS, XFS_IOC_SET_RESBLKS — see ioctl_xfs_getresblks(2) for more information. bestie, save yourself a lot of frustration and avoid these ioctls. genuinely. 🙈
• XFS_IOC_GOINGDOWN — see ioctl_xfs_goingdown(2) for more information.
• XFS_IOC_THAW, XFS_IOC_FREEZE, XFS_IOC_FSGROWFSDATA, XFS_IOC_FSGROWFSLOG, XFS_IOC_FSGROWFSRT — these interfaces are used to implement various filesystem internal operations on XFS filesystems. the remainder of these operations will not be described further as they are not of general use to applications. moving on 💅

🌈 SEE ALSO 🌈

ioctl_xfs_fsgetxattr(2), ioctl_xfs_fsgeometry(2), ioctl_xfs_fsbulkstat(2), ioctl_xfs_scrub_metadata(2), ioctl_xfs_fsinumbers(2), ioctl_xfs_fscounts(2), ioctl_xfs_getresblks(2), ioctl_xfs_getbmap(2), ioctl_xfs_goingdown(2), fstatfs(2), statfs(2), xfs(5), xfs_info(8).

and that's a wrap, bestie 🫶 this one lives in the Library Functions Manual and signs off at the bottom with just XFSCTL(3) — no extra date, no version drama, just the name and the number. iconic behavior, honestly. go forth and xfsctl responsibly 💖✨