1IOCTL-XFS-FSGETXATTR(2) System Calls Manual IOCTL-XFS-FSGETXATTR(2)
2
6 ioctl_xfs_fsgetxattr - query information for an open file
7
9 #include <linux/fs.h>
10 int ioctl(int fd, XFS_IOC_FSGETXATTR, struct fsxattr *arg);
12 int ioctl(int fd, XFS_IOC_FSGETXATTRA, struct fsxattr *arg);
13 int ioctl(int fd, XFS_IOC_FSSETXATTR, struct fsxattr *arg);
14
16 Query or set additional attributes associated with files in various
17 file systems. The attributes are conveyed in a structure of the form:
18 struct fsxattr {
20 __u32 fsx_xflags;
21 __u32 fsx_extsize;
22 __u32 fsx_nextents;
23 __u32 fsx_projid;
24 __u32 fsx_cowextsize;
25 unsigned char fsx_pad[8];
26 };
27 fsx_xflags are extended flags that apply to this file. Refer to the
29 section XFS INODE FLAGS below for more information.
30 fsx_extsize is the preferred extent allocation size for data blocks
33 mapped to this file, in units of filesystem blocks. If this value is
34 zero, the filesystem will choose a default option, which is currently
35 zero. If XFS_IOC_FSSETXATTR is called with XFS_XFLAG_EXTSIZE set in
36 fsx_xflags and this field set to zero, the XFLAG will also be cleared.
37 fsx_nextents is the number of data extents in this file. If
39 XFS_IOC_FSGETXATTRA was used, then this is the number of extended at‐
40 tribute extents in the file.
41 fsx_projid is the project ID of this file.
43 fsx_cowextsize is the preferred extent allocation size for copy on
45 write operations targeting this file, in units of filesystem blocks.
46 If this field is zero, the filesystem will choose a default option,
47 which is currently 128 filesystem blocks. If XFS_IOC_FSSETXATTR is
48 called with XFS_XFLAG_COWEXTSIZE set in fsx_xflags and this field set
49 to zero, the XFLAG will also be cleared.
50 fsx_pad must be zeroed.
53
56 This field can be a combination of the following:
57 XFS_XFLAG_REALTIME
60 The file is a realtime file. This bit can only be changed on a
61 file when it has no allocated extents.
62 XFS_XFLAG_PREALLOC
64 The file has preallocated space.
65 XFS_XFLAG_IMMUTABLE
67 The file is immutable - it cannot be modified, deleted or re‐
68 named, no link can be created to this file and no data can be
69 written to the file. Only the superuser or a process possessing
70 the CAP_LINUX_IMMUTABLE capability can set or clear this flag.
71 If this flag is set before a XFS_IOC_FSSETXATTR call and would
72 not be cleared by the call, then no other attributes can be
73 changed and EPERM will be returned.
74 XFS_XFLAG_APPEND
76 The file is append-only - it can only be opened in append mode
77 for writing. For directories, this means that files cannot be
78 unlinked from this directory. Only the superuser or a process
79 possessing the CAP_LINUX_IMMUTABLE capability can set or clear
80 this flag.
81 XFS_XFLAG_SYNC
83 All writes to the file are synchronous. If set on a directory
84 and the /proc/sys/fs/xfs/inherit_sync tunable is set to 1, new
85 files and subdirectories created in the directory will also have
86 the flag set.
87 XFS_XFLAG_NOATIME
89 When the file is accessed, its atime record is not modified. If
90 set on a directory and the /proc/sys/fs/xfs/inherit_noatime tun‐
91 able is set to 1, new files and subdirectories created in the
92 directory will also have the flag set.
93 XFS_XFLAG_NODUMP
95 The file should be skipped by backup utilities. If set on a di‐
96 rectory and the /proc/sys/fs/xfs/inherit_nodump tunable is set
97 to 1, new files and subdirectories created in the directory will
98 also have the flag set.
99 XFS_XFLAG_RTINHERIT
101 Realtime inheritance bit - new files created in the directory
102 will be automatically created as realtime files. If set on a
103 directory, new subdirectories created in the directory will also
104 have the inheritance flag set.
105 XFS_XFLAG_PROJINHERIT
107 Project inheritance bit - new files and directories created in
108 this directory will inherit the project ID of this directory.
109 If set on a directory, new subdirectories created in the direc‐
110 tory will also have the inheritance flag set.
111 XFS_XFLAG_NOSYMLINKS
113 Disallows creation of symbolic links in the directory. This
114 flag can only be set on a directory. If set on a directory and
115 the /proc/sys/fs/xfs/inherit_nosymlinks tunable is set to 1, new
116 files and subdirectories created in the directory will also have
117 the flag set.
118 XFS_XFLAG_EXTSIZE
120 Extent size bit - if a basic extent size value is set on the
121 file then the allocator will allocate in multiples of the set
122 size for this file (see fsx_extsize below). The extent size can
123 only be changed on a file when it has no allocated extents.
124 XFS_XFLAG_EXTSZINHERIT
126 Extent size inheritance bit - new files and directories created
127 in the directory will inherit the extent size value (see
128 fsx_extsize below) of the parent directory. New subdirectories
129 created in the directory will inherit the extent size inheri‐
130 tance bit.
131 XFS_XFLAG_NODEFRAG
133 No defragment file bit - the file should be skipped during a de‐
134 fragmentation operation. If set on a directory and the
135 /proc/sys/fs/xfs/inherit_nodefrag tunable is set to 1, new files
136 and subdirectories created in the directory will also have the
137 flag set.
138 XFS_XFLAG_FILESTREAM
140 Filestream allocator bit - allows a directory to reserve an al‐
141 location group for exclusive use by files created within that
142 directory. Files being written in other directories will not
143 use the same allocation group and so files within different di‐
144 rectories will not interleave extents on disk. The reservation
145 is only active while files are being created and written into
146 the directory. If set on a directory, new files and subdirecto‐
147 ries created in the directory will also have the flag set.
148 XFS_XFLAG_DAX
150 If the filesystem lives on directly accessible persistent mem‐
151 ory, reads and writes to this file will go straight to the per‐
152 sistent memory, bypassing the page cache. If set on a direc‐
153 tory, new files and subdirectories created in the directory will
154 also have the flag set. This flag cannot be set on filesystems
155 which have the reflink feature enabled.
156 XFS_XFLAG_COWEXTSIZE
158 Copy on Write Extent size bit - if a CoW extent size value is
159 set on the file, the allocator will allocate extents for staging
160 a copy on write operation in multiples of the set size for this
161 file (see fsx_cowextsize below). If set on a directory, new
162 files and subdirectories created in the directory will have both
163 the flag and the CoW extent size value set.
164 XFS_XFLAG_HASATTR
166 The file has extended attributes associated with it.
167
170 On error, -1 is returned, and errno is set to indicate the error.
171
173 Error codes can be one of, but are not limited to, the following:
174 EACCESS
176 Caller does not have sufficient access to change the attributes.
177 EFAULT The kernel was not able to copy into the userspace buffer.
179 EFSBADCRC
181 Metadata checksum validation failed while performing the query.
182 EFSCORRUPTED
184 Metadata corruption was encountered while performing the query.
185 EINVAL One of the arguments was not valid.
187 EIO An I/O error was encountered while performing the query.
189 ENOMEM There was insufficient memory to perform the query.
191 EPERM Caller did not have permission to change the attributes.
193
195 This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems
196 on the Linux kernel. Not all fields may be understood by filesystems
197 other than xfs.
198
200 ioctl(2), ioctl_iflags(2)
201XFS 2019-06-17 IOCTL-XFS-FSGETXATTR(2)