HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
XFSCTL(3) Library Functions ManualXFSCTL(3)xfsctl - control XFS filesystems and individual files
#include <xfs/xfs.h>int xfsctl(const char *path, intfd, intcmd, void *ptr);int platform_test_xfs_fd(intfd);int platform_test_xfs_path(const char *path);
Some functionality specific to the XFS filesystem is accessible to applications through platform-specific system call interfaces. These operations can be divided into two sections - operations that operate on individual files, and operations that operate on the filesystem itself. Care should be taken when issuingxfsctl() calls to ensure the target path and file descriptor (both must be supplied) do indeed represent a file from an XFS filesystem. Thestatfs(2) andfstatfs(2) system calls can be used to determine whether or not an arbitrary path or file descriptor belong to an XFS filesystem. These are not portable however, so the routinesplatform_test_xfs_fd() andplatform_test_xfs_path() provide a platform-independent mechanism.File Operations In order to effect an operation on an individual file, the pathname and descriptor arguments passed toxfsctlidentifies the file being operated on. The final argument described below refers to the final argument ofxfsctl. All of the data structures and macros mentioned below are defined in the <xfs/xfs_fs.h> header file.XFS_IOC_ALLOCSPXFS_IOC_ALLOCSP64XFS_IOC_FREESPXFS_IOC_FREESP64 Alter storage space associated with a section of the ordinary file specified. The section is specified by a variable of typexfs_flock64_t, pointed to by the final argument. The data typexfs_flock64_tcontains the following members:l_whenceis 0, 1, or 2 to indicate that the relative offsetl_startwill be measured from the start of the file, the current position, or the end of the file, respectively (i.e.,l_startis the offset from the position specified inl_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. Thel_lenfield is currently ignored, and should be set to zero.XFS_IOC_ALLOCSP,XFS_IOC_ALLOCSP64,XFS_IOC_FREESPandXFS_IOC_FREESP64operations 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 those previously returned in thebs_dmevmaskandbs_dmstate fields of the bulkstat structure. The data referred to by the final argument is astruct fsdmidata. This structure's members arefsd_dmevmaskandfsd_dmstate. The di_dmevmask field is set to the value infsd_dmevmask. The di_dmstate field is set to the value infsd_dmstate. This command is restricted to root or to processes with device management capabilities. Its sole purpose is to allow backup and restore programs to restore the aforementioned critical on- disk inode fields. This ioctl is not supported as of Linux 5.5.XFS_IOC_DIOINFO Get information 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 must conform to the same type of constraints as required for accessing a raw disk partition. The final argument points to a variable of typestructdioattr, which contains the following members:d_memis the memory alignment requirement of the user's data buffer.d_minioszspecifies 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_maxioszis the maximum I/O request size which can be performed on the file descriptor. If an I/O request does not meet these constraints, theread(2) orwrite(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_FSGETXATTRXFS_IOC_FSGETXATTRAXFS_IOC_FSSETXATTR Seeioctl_xfs_fsgetxattr(2) for more information.XFS_IOC_GETBMAPXFS_IOC_GETBMAPAXFS_IOC_GETBMAPX Seeioctl_getbmap(2) for more information.XFS_IOC_RESVSPXFS_IOC_RESVSP64 This command is used to allocate space to a file. A range of bytes is specified using a pointer to a variable of typexfs_flock64_tin 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. Ifxfs_info(8) reports unwritten=1, then the filesystem was made to flag unwritten extents.XFS_IOC_UNRESVSPXFS_IOC_UNRESVSP64 This command is used to free space from a file. A range of bytes is specified using a pointer to a variable of typexfs_flock64_tin 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 is used to convert a range of a file to zeros without issuing data IO. A range of bytes is specified using a pointer to a variable of typexfs_flock64_tin 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. Ifxfs_info(8) reports unwritten=1, then the filesystem was made to flag unwritten extents.XFS_IOC_PATH_TO_HANDLEXFS_IOC_PATH_TO_FSHANDLEXFS_IOC_FD_TO_HANDLEXFS_IOC_OPEN_BY_HANDLEXFS_IOC_READLINK_BY_HANDLEXFS_IOC_ATTR_LIST_BY_HANDLEXFS_IOC_ATTR_MULTI_BY_HANDLEXFS_IOC_FSSETDM_BY_HANDLE These are all interfaces that are used to implement variouslibhandle functions (seeopen_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 In order to effect one of the following operations, the pathname and descriptor arguments passed toxfsctl() can be any open file in the XFS filesystem in question.XFS_IOC_FSINUMBERS Seeioctl_xfs_fsinumbers(2) for more information.XFS_IOC_FSGEOMETRY Seeioctl_xfs_fsgeometry(2) for more information.XFS_IOC_AG_GEOMETRY Seeioctl_xfs_ag_geometry(2) for more information.XFS_IOC_FSBULKSTATorXFS_IOC_FSBULKSTAT_SINGLE Seeioctl_xfs_fsbulkstat(2) for more information.XFS_IOC_SCRUB_METADATA Seeioctl_xfs_scrub_metadata(2) for more information.XFS_IOC_FSCOUNTS Seeioctl_xfs_fscounts(2) for more information.XFS_IOC_GET_RESBLKSXFS_IOC_SET_RESBLKS Seeioctl_xfs_getresblks(2) for more information. Save yourself a lot of frustration and avoid these ioctls.XFS_IOC_GOINGDOWN Seeioctl_xfs_goingdown(2) for more information.XFS_IOC_THAWXFS_IOC_FREEZEXFS_IOC_FSGROWFSDATAXFS_IOC_FSGROWFSLOGXFS_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.
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).
This page is part of thexfsprogs (utilities for XFS filesystems) project. Information about the project can be found at ⟨http://xfs.org/⟩. If you have a bug report for this manual page, send it to linux-xfs@vger.kernel.org. This page was obtained from the project's upstream Git repository ⟨https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-06-23.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgXFSCTL(3)Pages that refer to this page:open(2), handle(3), projects(5), projid(5), xfs(5), xfs_io(8)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |