Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_fsgetxattr.2

raw
1 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
2 .\" SPDX-License-Identifier: GPL-2.0+
3 .\" %%%LICENSE_END
4 .TH IOCTL-XFS-FSGETXATTR 2 2019-06-17 "XFS"
5 .SH NAME
6 ioctl_xfs_fsgetxattr \- query information for an open file
7 .SH SYNOPSIS
8 .br
9 .B #include <linux/fs.h>
10 .PP
11 .BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTR, struct fsxattr *" arg );
12 .br
13 .BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTRA, struct fsxattr *" arg );
14 .br
15 .BI "int ioctl(int " fd ", XFS_IOC_FSSETXATTR, struct fsxattr *" arg );
16 .SH DESCRIPTION
17 Query or set additional attributes associated with files in various file
18 systems.
19 The attributes are conveyed in a structure of the form:
20 .PP
21 .in +4n
22 .nf
23 struct fsxattr {
24 __u32 fsx_xflags;
25 __u32 fsx_extsize;
26 __u32 fsx_nextents;
27 __u32 fsx_projid;
28 __u32 fsx_cowextsize;
29 unsigned char fsx_pad[8];
30 };
31 .fi
32 .in
33 .PP
34 .I fsx_xflags
35 are extended flags that apply to this file.
36 Refer to the section
37 .B XFS INODE FLAGS
38 below for more information.
39
40 .PP
41 .I fsx_extsize
42 is the preferred extent allocation size for data blocks mapped to this file,
43 in units of bytes.
44 If this value is zero, the filesystem will choose a default option, which
45 is currently zero.
46 If
47 .B XFS_IOC_FSSETXATTR
48 is called with
49 .B XFS_XFLAG_EXTSIZE
50 set in
51 .I fsx_xflags
52 and this field set to zero, the XFLAG will also be cleared.
53 .PP
54 .I fsx_nextents
55 is the number of data extents in this file.
56 If
57 .B XFS_IOC_FSGETXATTRA
58 was used, then this is the number of extended attribute extents in the file.
59 .PP
60 .I fsx_projid
61 is the project ID of this file.
62 .PP
63 .I fsx_cowextsize
64 is the preferred extent allocation size for copy on write operations
65 targeting this file, in units of bytes.
66 If this field is zero, the filesystem will choose a default option,
67 which is currently 32 filesystem blocks.
68 If
69 .B XFS_IOC_FSSETXATTR
70 is called with
71 .B XFS_XFLAG_COWEXTSIZE
72 set in
73 .I fsx_xflags
74 and this field set to zero, the XFLAG will also be cleared.
75
76 .PP
77 .I fsx_pad
78 must be zeroed.
79
80 .SH XFS INODE FLAGS
81 This field can be a combination of the following:
82
83 .TP
84 .B XFS_XFLAG_REALTIME
85 The file is a realtime file.
86 This bit can only be changed on a file when it has no allocated extents.
87 .TP
88 .B XFS_XFLAG_PREALLOC
89 The file has preallocated space.
90 .TP
91 .B XFS_XFLAG_IMMUTABLE
92 The file is immutable - it cannot be modified, deleted or renamed,
93 no link can be created to this file and no data can be written to the
94 file.
95 Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
96 capability can set or clear this flag.
97 If this flag is set before a
98 .B XFS_IOC_FSSETXATTR
99 call and would not be cleared by the call, then no other attributes can be
100 changed and
101 .B EPERM
102 will be returned.
103 .TP
104 .B XFS_XFLAG_APPEND
105 The file is append-only - it can only be opened in append mode for
106 writing.
107 For directories, this means that files cannot be unlinked from this directory.
108 Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
109 capability can set or clear this flag.
110 .TP
111 .B XFS_XFLAG_SYNC
112 All writes to the file are synchronous.
113 If set on a directory and the
114 .B /proc/sys/fs/xfs/inherit_sync
115 tunable is set to 1, new files and subdirectories created in the directory
116 will also have the flag set.
117 .TP
118 .B XFS_XFLAG_NOATIME
119 When the file is accessed, its atime record is not modified.
120 If set on a directory and the
121 .B /proc/sys/fs/xfs/inherit_noatime
122 tunable is set to 1, new files and subdirectories created in the directory
123 will also have the flag set.
124 .TP
125 .B XFS_XFLAG_NODUMP
126 The file should be skipped by backup utilities.
127 If set on a directory and the
128 .B /proc/sys/fs/xfs/inherit_nodump
129 tunable is set to 1, new files and subdirectories created in the directory
130 will also have the flag set.
131 .TP
132 .B XFS_XFLAG_RTINHERIT
133 Realtime inheritance bit - new files created in the directory
134 will be automatically created as realtime files.
135 If set on a directory, new subdirectories created in the directory will also
136 have the inheritance flag set.
137 .TP
138 .B XFS_XFLAG_PROJINHERIT
139 Project inheritance bit - new files and directories created in
140 this directory will inherit the project ID of this directory.
141 If set on a directory, new subdirectories created in the directory will also
142 have the inheritance flag set.
143 .TP
144 .B XFS_XFLAG_NOSYMLINKS
145 Disallows creation of symbolic links in the directory.
146 This flag can only be set on a directory.
147 If set on a directory and the
148 .B /proc/sys/fs/xfs/inherit_nosymlinks
149 tunable is set to 1, new files and subdirectories created in the directory
150 will also have the flag set.
151 .TP
152 .B XFS_XFLAG_EXTSIZE
153 Extent size bit - if a basic extent size value is set on the file
154 then the allocator will allocate in multiples of the set size for
155 this file (see
156 .B fsx_extsize
157 below).
158 The extent size can only be changed on a file when it has no allocated extents.
159 .TP
160 .B XFS_XFLAG_EXTSZINHERIT
161 Extent size inheritance bit - new files and directories created in
162 the directory will inherit the extent size value (see
163 .B fsx_extsize
164 below) of the parent directory.
165 New subdirectories created in the directory will inherit the extent size
166 inheritance bit.
167 .TP
168 .B XFS_XFLAG_NODEFRAG
169 No defragment file bit - the file should be skipped during a defragmentation
170 operation.
171 If set on a directory and the
172 .B /proc/sys/fs/xfs/inherit_nodefrag
173 tunable is set to 1, new files and subdirectories created in the directory
174 will also have the flag set.
175 .TP
176 .B XFS_XFLAG_FILESTREAM
177 Filestream allocator bit - allows a directory to reserve an allocation group
178 for exclusive use by files created within that directory.
179 Files being written in other directories will not use the same allocation group
180 and so files within different directories will not interleave extents on disk.
181 The reservation is only active while files are being created and written into
182 the directory.
183 If set on a directory, new files and subdirectories created in the directory
184 will also have the flag set.
185 .TP
186 .B XFS_XFLAG_DAX
187 If the filesystem lives on directly accessible persistent memory, reads and
188 writes to this file will go straight to the persistent memory, bypassing the
189 page cache.
190 If set on a directory, new files and subdirectories created in the directory
191 will also have the flag set.
192 This flag cannot be set on filesystems which have the reflink feature enabled.
193 .TP
194 .B XFS_XFLAG_COWEXTSIZE
195 Copy on Write Extent size bit - if a CoW extent size value is set on the file,
196 the allocator will allocate extents for staging a copy on write operation
197 in multiples of the set size for this file (see
198 .B fsx_cowextsize
199 below).
200 If set on a directory, new files and subdirectories created in the directory
201 will have both the flag and the CoW extent size value set.
202 .TP
203 .B XFS_XFLAG_HASATTR
204 The file has extended attributes associated with it.
205
206 .SH RETURN VALUE
207 On error, \-1 is returned, and
208 .I errno
209 is set to indicate the error.
210 .PP
211 .SH ERRORS
212 Error codes can be one of, but are not limited to, the following:
213 .TP
214 .B EACCESS
215 Caller does not have sufficient access to change the attributes.
216 .TP
217 .B EFAULT
218 The kernel was not able to copy into the userspace buffer.
219 .TP
220 .B EFSBADCRC
221 Metadata checksum validation failed while performing the query.
222 .TP
223 .B EFSCORRUPTED
224 Metadata corruption was encountered while performing the query.
225 .TP
226 .B EINVAL
227 One of the arguments was not valid.
228 .TP
229 .B EIO
230 An I/O error was encountered while performing the query.
231 .TP
232 .B ENOMEM
233 There was insufficient memory to perform the query.
234 .TP
235 .B EPERM
236 Caller did not have permission to change the attributes.
237 .SH CONFORMING TO
238 This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
239 Linux kernel.
240 Not all fields may be understood by filesystems other than xfs.
241 .SH SEE ALSO
242 .BR ioctl (2),
243 .BR ioctl_iflags (2)