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
40 attribute 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
68 renamed, 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. Only the superuser or a process possessing the
78 CAP_LINUX_IMMUTABLE capability can set or clear this flag.
79 XFS_XFLAG_SYNC
81 All writes to the file are synchronous. If set on a directory
82 and the /proc/sys/fs/xfs/inherit_sync tunable is set to 1, new
83 files and subdirectories created in the directory will also have
84 the flag set.
85 XFS_XFLAG_NOATIME
87 When the file is accessed, its atime record is not modified. If
88 set on a directory and the /proc/sys/fs/xfs/inherit_noatime tun‐
89 able is set to 1, new files and subdirectories created in the
90 directory will also have the flag set.
91 XFS_XFLAG_NODUMP
93 The file should be skipped by backup utilities. If set on a
94 directory and the /proc/sys/fs/xfs/inherit_nodump tunable is set
95 to 1, new files and subdirectories created in the directory will
96 also have the flag set.
97 XFS_XFLAG_RTINHERIT
99 Realtime inheritance bit - new files created in the directory
100 will be automatically created as realtime files. If set on a
101 directory, new subdirectories created in the directory will also
102 have the inheritance flag set.
103 XFS_XFLAG_PROJINHERIT
105 Project inheritance bit - new files and directories created in
106 this directory will inherit the project ID of this directory.
107 If set on a directory, new subdirectories created in the direc‐
108 tory will also have the inheritance flag set.
109 XFS_XFLAG_NOSYMLINKS
111 Disallows creation of symbolic links in the directory. This
112 flag can only be set on a directory. If set on a directory and
113 the /proc/sys/fs/xfs/inherit_nosymlinks tunable is set to 1, new
114 files and subdirectories created in the directory will also have
115 the flag set.
116 XFS_XFLAG_EXTSIZE
118 Extent size bit - if a basic extent size value is set on the
119 file then the allocator will allocate in multiples of the set
120 size for this file (see fsx_extsize below). The extent size can
121 only be changed on a file when it has no allocated extents.
122 XFS_XFLAG_EXTSZINHERIT
124 Extent size inheritance bit - new files and directories created
125 in the directory will inherit the extent size value (see
126 fsx_extsize below) of the parent directory. New subdirectories
127 created in the directory will inherit the extent size inheri‐
128 tance bit.
129 XFS_XFLAG_NODEFRAG
131 No defragment file bit - the file should be skipped during a
132 defragmentation operation. If set on a directory and the
133 /proc/sys/fs/xfs/inherit_nodefrag tunable is set to 1, new files
134 and subdirectories created in the directory will also have the
135 flag set.
136 XFS_XFLAG_FILESTREAM
138 Filestream allocator bit - allows a directory to reserve an
139 allocation group for exclusive use by files created within that
140 directory. Files being written in other directories will not
141 use the same allocation group and so files within different
142 directories will not interleave extents on disk. The reserva‐
143 tion is only active while files are being created and written
144 into the directory. If set on a directory, new files and subdi‐
145 rectories created in the directory will also have the flag set.
146 XFS_XFLAG_DAX
148 If the filesystem lives on directly accessible persistent mem‐
149 ory, reads and writes to this file will go straight to the per‐
150 sistent memory, bypassing the page cache. If set on a direc‐
151 tory, new files and subdirectories created in the directory will
152 also have the flag set. This flag cannot be set on filesystems
153 which have the reflink feature enabled.
154 XFS_XFLAG_COWEXTSIZE
156 Copy on Write Extent size bit - if a CoW extent size value is
157 set on the file, the allocator will allocate extents for staging
158 a copy on write operation in multiples of the set size for this
159 file (see fsx_cowextsize below). If set on a directory, new
160 files and subdirectories created in the directory will have both
161 the flag and the CoW extent size value set.
162 XFS_XFLAG_HASATTR
164 The file has extended attributes associated with it.
165
168 On error, -1 is returned, and errno is set to indicate the error.
169
171 Error codes can be one of, but are not limited to, the following:
172 EACCESS
174 Caller does not have sufficient access to change the attributes.
175 EFAULT The kernel was not able to copy into the userspace buffer.
177 EFSBADCRC
179 Metadata checksum validation failed while performing the query.
180 EFSCORRUPTED
182 Metadata corruption was encountered while performing the query.
183 EINVAL One of the arguments was not valid.
185 EIO An I/O error was encountered while performing the query.
187 ENOMEM There was insufficient memory to perform the query.
189 EPERM Caller did not have permission to change the attributes.
191
193 This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems
194 on the Linux kernel. Not all fields may be understood by filesystems
195 other than xfs.
196
198 ioctl(2), ioctl_iflags(2)
199XFS 2019-06-17 IOCTL-XFS-FSGETXATTR(2)