IOCTL-XFS-FSGETXATTR(2)

✨ IOCTL-XFS-FSGETXATTR ✨

okay bestie, come SIT. this one lives in the System Calls Manual section (section 2, iykyk) and it's literally called ioctl_xfs_fsgetxattr — the whole vibe is querying info about an open file. 💅

---

🦋 NAME 🦋

ioctl_xfs_fsgetxattr — query information for an open file 👑

---

🌸 SYNOPSIS 🌸

#include <linux/fs.h>

int ioctl(int fd, XFS_IOC_FSGETXATTR, struct fsxattr *arg);
int ioctl(int fd, XFS_IOC_FSGETXATTRA, struct fsxattr *arg);
int ioctl(int fd, XFS_IOC_FSSETXATTR, struct fsxattr *arg);

---

💖 DESCRIPTION 💖

so basically you can query or set extra attributes hanging off files in a bunch of different filesystems. and the way it works is all these attributes get carried around in a struct that looks exactly like this:

struct fsxattr {
     __u32         fsx_xflags;
     __u32         fsx_extsize;
     __u32         fsx_nextents;
     __u32         fsx_projid;
     __u32         fsx_cowextsize;
     unsigned char fsx_pad[8];
};

okay let's go field by field, no skipping, we're not doing that here 🫶

• fsx_xflags — these are the extended flags that apply to this file. they get their own whole section below, scroll down for the tea. ⬇️
• fsx_extsize — the preferred extent allocation size for data blocks mapped to this file, measured in bytes. if it's zero, the filesystem just picks a default for itself, and right now that default is also zero. heads up tho: if you call XFS_IOC_FSSETXATTR with XFS_XFLAG_EXTSIZE set inside fsx_xflags and this field is zero, the XFLAG gets cleared too. bye flag 💀
• fsx_nextents — the number of data extents in this file. but wait — if XFS_IOC_FSGETXATTRA was the one you used, then this is the number of extended attribute extents in the file instead. plot twist 🌈
• fsx_projid — the project ID of this file. simple, iconic.
• fsx_cowextsize — the preferred extent allocation size for copy-on-write operations targeting this file, in bytes. if it's zero, the filesystem picks a default, which is currently 32 filesystem blocks. and same deal as before: if XFS_IOC_FSSETXATTR is called with XFS_XFLAG_COWEXTSIZE set in fsx_xflags and this field is zero, that XFLAG gets cleared too. 🙈
• fsx_pad — must be zeroed. that's it. that's the whole job. zero it. ⭐

---

👑 XFS INODE FLAGS 👑

this field can be a combination of any of these:

• XFS_XFLAG_REALTIME — the file is a realtime file. this bit can only be changed on a file when it has no allocated extents. careful bestie.
• 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. and listen — if this flag is set before a XFS_IOC_FSSETXATTR call and wouldn't be cleared by that call, then no other attributes can be changed and EPERM gets returned. it's giving locked down 🔒
• XFS_XFLAG_APPEND — the file is append-only: it can only be opened in append mode for writing. for directories, this means 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_sync tunable 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_noatime tunable 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_nodump tunable 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 automatically be 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 (peep fsx_extsize below). 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 (peep fsx_extsize below) 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_nodefrag tunable is set to 1, new files and subdirectories created in the directory will also have the flag set.
• XFS_XFLAG_FILESTREAM — filestream allocator bit: lets a directory 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, 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 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 (peep fsx_cowextsize below). 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. 💫

---

💀 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:

• EACCESS — caller does not have sufficient access to change the attributes.
• EFAULT — the 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.
• EINVAL — one of the arguments was not valid.
• EIO — an I/O error was encountered while performing the query.
• ENOMEM — there was insufficient memory to perform the query.
• EPERM — caller did not have permission to change the attributes.

---

🌈 CONFORMING TO 🌈

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, so don't assume everyone speaks the same language bestie.

---

🧚 CAVEATS 🧚

the XFS_IOC_FSGETXATTR and XFS_IOC_FSSETXATTR ioctl(2) operations require the user to open the file, but this may not be possible or may lead to side effects on special files such as FIFOs, sockets, block devices, character devices, and symlinks. yeah. careful with those. 😭

for a pathname-based interface, peep the file_getattr(2) and file_setattr(2) syscalls instead. 🫶

---

⭐ SEE ALSO ⭐

ioctl(2), ioctl_iflags(2), file_getattr(2), file_setattr(2)

---

and that's the whole page, bestie, you ate it 💅 this was the XFS manual, dated 2019-06-17, and it came to you straight from the IOCTL-XFS-FSGETXATTR(2) corner of the universe. go query some files. periodt. 🎀✨