1IOCTL-XFS-FSGETXATTR(2)       System Calls Manual      IOCTL-XFS-FSGETXATTR(2)
2
3
4

NAME

6       ioctl_xfs_fsgetxattr - query information for an open file
7

SYNOPSIS

9       #include <linux/fs.h>
10
11       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

DESCRIPTION

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
19           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
28       fsx_xflags are extended flags that apply to this file.   Refer  to  the
29       section XFS INODE FLAGS below for more information.
30
31
32       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
38       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
42       fsx_projid is the project ID of this file.
43
44       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
51
52       fsx_pad must be zeroed.
53
54

XFS INODE FLAGS

56       This field can be a combination of the following:
57
58
59       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
63       XFS_XFLAG_PREALLOC
64              The file has preallocated space.
65
66       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
75       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
82       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
88       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
94       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
100       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
106       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
112       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
119       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
125       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
132       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
139       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
149       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
157       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
165       XFS_XFLAG_HASATTR
166              The file has extended attributes associated with it.
167
168

RETURN VALUE

170       On error, -1 is returned, and errno is set to indicate the error.
171

ERRORS

173       Error codes can be one of, but are not limited to, the following:
174
175       EACCESS
176              Caller does not have sufficient access to change the attributes.
177
178       EFAULT The kernel was not able to copy into the userspace buffer.
179
180       EFSBADCRC
181              Metadata checksum validation failed while performing the query.
182
183       EFSCORRUPTED
184              Metadata corruption was encountered while performing the query.
185
186       EINVAL One of the arguments was not valid.
187
188       EIO    An I/O error was encountered while performing the query.
189
190       ENOMEM There was insufficient memory to perform the query.
191
192       EPERM  Caller did not have permission to change the attributes.
193

CONFORMING TO

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

SEE ALSO

200       ioctl(2), ioctl_iflags(2)
201
202
203
204XFS                               2019-06-17           IOCTL-XFS-FSGETXATTR(2)
Impressum