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. |  |
NAME |SYNOPSIS |DESCRIPTION |XFS INODE FLAGS |RETURN VALUE |ERRORS |CONFORMING TO |SEE ALSO |COLOPHON | |
IOCTL-XFS-FSGETXATTR(2) System Calls ManualIOCTL-XFS-FSGETXATTR(2)ioctl_xfs_fsgetxattr - query information for an open file
#include <linux/fs.h>int ioctl(intfd, XFS_IOC_FSGETXATTR, struct fsxattr *arg);int ioctl(intfd, XFS_IOC_FSGETXATTRA, struct fsxattr *arg);int ioctl(intfd, XFS_IOC_FSSETXATTR, struct fsxattr *arg);
Query or set additional attributes associated with files in various file systems. The attributes are conveyed in a structure of the form: struct fsxattr { __u32 fsx_xflags; __u32 fsx_extsize; __u32 fsx_nextents; __u32 fsx_projid; __u32 fsx_cowextsize; unsigned char fsx_pad[8]; };fsx_xflags are extended flags that apply to this file. Refer to the sectionXFS INODE FLAGSbelow for more information.fsx_extsize is the preferred extent allocation size for data blocks mapped to this file, in units of bytes. If this value is zero, the filesystem will choose a default option, which is currently zero. IfXFS_IOC_FSSETXATTRis called withXFS_XFLAG_EXTSIZEset infsx_xflags and this field set to zero, the XFLAG will also be cleared.fsx_nextents is the number of data extents in this file. IfXFS_IOC_FSGETXATTRAwas used, then this is the number of extended attribute extents in the file.fsx_projid is the project ID of this file.fsx_cowextsize is the preferred extent allocation size for copy on write operations targeting this file, in units of bytes. If this field is zero, the filesystem will choose a default option, which is currently 32 filesystem blocks. IfXFS_IOC_FSSETXATTRis called withXFS_XFLAG_COWEXTSIZEset infsx_xflags and this field set to zero, the XFLAG will also be cleared.fsx_pad must be zeroed.This field can be a combination of the following:XFS_XFLAG_REALTIME The file is a realtime file. This bit can only be changed on a file when it has no allocated extents.XFS_XFLAG_PREALLOC The file has preallocated space.XFS_XFLAG_IMMUTABLE The file is immutable - it cannot be modified, deleted or renamed, no link can be created to this file and no data can be written to the file. Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE capability can set or clear this flag. If this flag is set before aXFS_IOC_FSSETXATTRcall and would not be cleared by the call, then no other attributes can be changed andEPERM will be returned.XFS_XFLAG_APPEND The file is append-only - it can only be opened in append mode for writing. For directories, this means that files cannot be unlinked from this directory. Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE capability can set or clear this flag.XFS_XFLAG_SYNC All writes to the file are synchronous. If set on a directory and the/proc/sys/fs/xfs/inherit_synctunable is set to 1, new files and subdirectories created in the directory will also have the flag set.XFS_XFLAG_NOATIME When the file is accessed, its atime record is not modified. If set on a directory and the/proc/sys/fs/xfs/inherit_noatimetunable is set to 1, new files and subdirectories created in the directory will also have the flag set.XFS_XFLAG_NODUMP The file should be skipped by backup utilities. If set on a directory and the/proc/sys/fs/xfs/inherit_nodumptunable is set to 1, new files and subdirectories created in the directory will also have the flag set.XFS_XFLAG_RTINHERIT Realtime inheritance bit - new files created in the directory will be automatically created as realtime files. If set on a directory, new subdirectories created in the directory will also have the inheritance flag set.XFS_XFLAG_PROJINHERIT Project inheritance bit - new files and directories created in this directory will inherit the project ID of this directory. If set on a directory, new subdirectories created in the directory will also have the inheritance flag set.XFS_XFLAG_NOSYMLINKS Disallows creation of symbolic links in the directory. This flag can only be set on a directory. If set on a directory and the/proc/sys/fs/xfs/inherit_nosymlinks tunable is set to 1, new files and subdirectories created in the directory will also have the flag set.XFS_XFLAG_EXTSIZE Extent size bit - if a basic extent size value is set on the file then the allocator will allocate in multiples of the set size for this file (seefsx_extsizebelow). The extent size can only be changed on a file when it has no allocated extents.XFS_XFLAG_EXTSZINHERIT Extent size inheritance bit - new files and directories created in the directory will inherit the extent size value (seefsx_extsizebelow) of the parent directory. New subdirectories created in the directory will inherit the extent size inheritance bit.XFS_XFLAG_NODEFRAG No defragment file bit - the file should be skipped during a defragmentation operation. If set on a directory and the/proc/sys/fs/xfs/inherit_nodefragtunable is set to 1, new files and subdirectories created in the directory will also have the flag set.XFS_XFLAG_FILESTREAM Filestream allocator bit - allows a directory to reserve an allocation group for exclusive use by files created within that directory. Files being written in other directories will not use the same allocation group and so files within different directories will not interleave extents on disk. The reservation is only active while files are being created and written into the directory. If set on a directory, new files and subdirectories created in the directory will also have the flag set.XFS_XFLAG_DAX If the filesystem lives on directly accessible persistent memory, reads and writes to this file will go straight to the persistent memory, bypassing the page cache. If set on a directory, new files and subdirectories created in the directory will also have the flag set. This flag cannot be set on filesystems which have the reflink feature enabled.XFS_XFLAG_COWEXTSIZE Copy on Write Extent size bit - if a CoW extent size value is set on the file, the allocator will allocate extents for staging a copy on write operation in multiples of the set size for this file (seefsx_cowextsizebelow). If set on a directory, new files and subdirectories created in the directory will have both the flag and the CoW extent size value set.XFS_XFLAG_HASATTR The file has extended attributes associated with it.
On error, -1 is returned, anderrno is set to indicate the error.
Error codes can be one of, but are not limited to, the following:EACCESS Caller does not have sufficient access to change the attributes.EFAULTThe 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.EINVALOne of the arguments was not valid.EIOAn I/O error was encountered while performing the query.ENOMEMThere was insufficient memory to perform the query.EPERMCaller did not have permission to change the attributes.
This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the Linux kernel. Not all fields may be understood by filesystems other than xfs.
ioctl(2),ioctl_iflags(2)
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.orgXFS 2019-06-17IOCTL-XFS-FSGETXATTR(2)Pages that refer to this page:ioctl_xfs_bulkstat(2), ioctl_xfs_fsbulkstat(2), xfsctl(3), xfs_io(8)
Copyright and license for this manual page
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. | |