Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_fsgeometry.2

raw
1 .\" Copyright (c) 2019, Oracle. All rights reserved.
2 .\"
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" SPDX-License-Identifier: GPL-2.0+
5 .\" %%%LICENSE_END
6 .TH IOCTL-XFS-FSGEOMETRY 2 2019-06-17 "XFS"
7 .SH NAME
8 ioctl_xfs_fsgeometry \- report XFS filesystem layout and features
9 .SH SYNOPSIS
10 .br
11 .B #include <xfs/xfs_fs.h>
12 .PP
13 .BI "int ioctl(int " fd ", XFS_IOC_FSGEOMETRY, struct xfs_fsop_geom *" arg );
14 .br
15 .BI "int ioctl(int " fd ", XFS_IOC_FSGEOMETRY_V4, struct xfs_fsop_geom_v4 *" arg );
16 .br
17 .BI "int ioctl(int " fd ", XFS_IOC_FSGEOMETRY_V1, struct xfs_fsop_geom_v1 *" arg );
18 .SH DESCRIPTION
19 Report the details of an XFS filesystem layout, features, and other descriptive items.
20 This information is conveyed in a structure of the following form:
21 .PP
22 .in +4n
23 .nf
24 struct xfs_fsop_geom {
25 __u32 blocksize;
26 __u32 rtextsize;
27 __u32 agblocks;
28 __u32 agcount;
29 __u32 logblocks;
30 __u32 sectsize;
31 __u32 inodesize;
32 __u32 imaxpct;
33 __u64 datablocks;
34 __u64 rtblocks;
35 __u64 rtextents;
36 __u64 logstart;
37 unsigned char uuid[16];
38 __u32 sunit;
39 __u32 swidth;
40 __s32 version;
41 __u32 flags;
42 __u32 logsectsize;
43 __u32 rtsectsize;
44 __u32 dirblocksize;
45 /* struct xfs_fsop_geom_v1 stops here. */
46
47 __u32 logsunit;
48 /* struct xfs_fsop_geom_v4 stops here. */
49
50 __u32 sick;
51 __u32 checked;
52 __u64 rgextents;
53 __u64 rtstart;
54 __u64 rtreserved;
55 __u64 reserved[14];
56 };
57 .fi
58 .in
59 .PP
60 .I blocksize
61 is the size of a fundamental filesystem block, in bytes.
62 .PP
63 .I rtextsize
64 is the size of an extent on the realtime volume, in bytes.
65 .PP
66 .I agblocks
67 is the size of an allocation group, in units of filesystem blocks.
68 .PP
69 .I agcount
70 is the number of allocation groups in the filesystem.
71 .PP
72 .I logblocks
73 is the size of the log, in units of filesystem blocks.
74 .PP
75 .I sectsize
76 is the smallest amount of data that can be written to the data device
77 atomically, in bytes.
78 .PP
79 .I inodesize
80 is the size of an inode record, in bytes.
81 .PP
82 .I imaxpct
83 is the maximum percentage of the filesystem that can be allocated to inode
84 record blocks.
85 .PP
86 .I datablocks
87 is the size of the data device, in units of filesystem blocks.
88 .PP
89 .I rtblocks
90 is the size of the realtime device, in units of filesystem blocks.
91 .PP
92 .I rtextents
93 is the number of extents that can be allocated on the realtime device.
94 .PP
95 .I logstart
96 is the start of the log, in units of filesystem blocks.
97 If the filesystem has an external log, this will be zero.
98 .PP
99 .I uuid
100 is the universal unique identifier of the filesystem.
101 .PP
102 .I sunit
103 is what the filesystem has been told is the size of a RAID stripe unit on the
104 underlying data device, in filesystem blocks.
105 .PP
106 .I swidth
107 is what the filesystem has been told is the width of a RAID stripe on the
108 underlying data device, in units of RAID stripe units.
109 .PP
110 .I version
111 is the version of this structure.
112 This value will be XFS_FSOP_GEOM_VERSION.
113 .PP
114 .I flags
115 tell us what features are enabled on the filesystem.
116 Refer to the section
117 .B FILESYSTEM FEATURE FLAGS
118 below for more information about each feature.
119 .PP
120 .I logsectsize
121 is the smallest amount of data that can be written to the log device atomically,
122 in bytes.
123 .PP
124 .I rtsectsize
125 is the smallest amount of data that can be written to the realtime device
126 atomically, in bytes.
127 .PP
128 .I dirblocksize
129 is the size of directory blocks, in bytes.
130 .PP
131 .I logsunit
132 is what the filesystem has been told is the size of a RAID stripe unit on the
133 underlying log device, in filesystem blocks.
134 This field is meaningful only if the flag
135 .B XFS_FSOP_GEOM_FLAGS_LOGV2
136 is set.
137 .PP
138 The fields
139 .IR sick " and " checked
140 indicate the relative health of various whole-filesystem metadata.
141 Please see the section
142 .B XFS METADATA HEALTH REPORTING
143 for more details.
144 .PP
145 .I rgextents
146 Is the number of RT extents in each rtgroup.
147 .PP
148 .I rtstart
149 Start of the internal RT device in fsblocks. 0 if an external RT device
150 is used.
151 This field is meaningful only if the flag
152 .B XFS_FSOP_GEOM_FLAGS_ZONED
153 is set.
154 .PP
155 .I rtreserved
156 The amount of space in the realtime section that is reserved for internal use
157 by garbage collection and reorganization algorithms in fsblocks.
158 This field is meaningful only if the flag
159 .B XFS_FSOP_GEOM_FLAGS_ZONED
160 is set.
161 .PP
162 .I reserved
163 is set to zero.
164 .SH FILESYSTEM FEATURE FLAGS
165 Filesystem features are reported to userspace as a combination the following
166 flags:
167 .TP
168 .B XFS_FSOP_GEOM_FLAGS_ATTR
169 Extended attributes are present.
170 .TP
171 .B XFS_FSOP_GEOM_FLAGS_NLINK
172 Files on this filesystem support up to 2^32 hard links.
173 If this flag is not set, files on this filesystem support only up to 2^16
174 hard links.
175 .TP
176 .B XFS_FSOP_GEOM_FLAGS_QUOTA
177 Quotas are enabled.
178 .TP
179 .B XFS_FSOP_GEOM_FLAGS_IALIGN
180 Inodes are aligned for better performance.
181 .TP
182 .B XFS_FSOP_GEOM_FLAGS_DALIGN
183 Filesystem tries to align data block allocations to RAID stripe units for
184 better performance.
185 .TP
186 .B XFS_FSOP_GEOM_FLAGS_SHARED
187 Unused.
188 .TP
189 .B XFS_FSOP_GEOM_FLAGS_EXTFLG
190 Filesystem supports unwritten extents.
191 .TP
192 .B XFS_FSOP_GEOM_FLAGS_DIRV2
193 Directories are in version 2 format and maintain free space data for better
194 performance.
195 Version 1 format directories are no longer supported.
196 .TP
197 .B XFS_FSOP_GEOM_FLAGS_LOGV2
198 Log uses the V2 format.
199 .TP
200 .B XFS_FSOP_GEOM_FLAGS_SECTOR
201 The log device has a sector size larger than 512 bytes.
202 .TP
203 .B XFS_FSOP_GEOM_FLAGS_ATTR2
204 Filesystem contains V2 extended attributes.
205 .TP
206 .B XFS_FSOP_GEOM_FLAGS_PROJID32
207 Project IDs can be as large as 2^32.
208 If this flag is not set, the filesystem supports only 2^16 project IDs.
209 .TP
210 .B XFS_FSOP_GEOM_FLAGS_DIRV2CI
211 Case-insensitive lookups are supported on directories.
212 .TP
213 .B XFS_FSOP_GEOM_FLAGS_LAZYSB
214 On-disk superblock counters are updated only at unmount time.
215 .TP
216 .B XFS_FSOP_GEOM_FLAGS_V5SB
217 Metadata blocks are self describing and contain checksums.
218 .TP
219 .B XFS_FSOP_GEOM_FLAGS_FTYPE
220 Directories contain inode types in directory entries.
221 .TP
222 .B XFS_FSOP_GEOM_FLAGS_FINOBT
223 Filesystem maintains an index of free inodes.
224 .TP
225 .B XFS_FSOP_GEOM_FLAGS_SPINODES
226 Filesystem may allocate discontiguous inode chunks when free space is
227 fragmented.
228 .TP
229 .B XFS_FSOP_GEOM_FLAGS_RMAPBT
230 Filesystem stores reverse mappings of blocks to owners.
231 .TP
232 .B XFS_FSOP_GEOM_FLAGS_REFLINK
233 Filesystem supports sharing blocks between files.
234 .TP
235 .B XFS_FSOP_GEOM_FLAGS_EXCHANGE_RANGE
236 Filesystem can exchange file contents atomically via XFS_IOC_EXCHANGE_RANGE.
237 .TP
238 .B XFS_FSOP_GEOM_FLAGS_METADIR
239 Filesystem contains a metadata directory tree.
240 .TP
241 .B XFS_FSOP_GEOM_FLAGS_ZONED
242 Filesystem uses the zoned allocator for the RT device.
243 .RE
244 .SH XFS METADATA HEALTH REPORTING
245 .PP
246 The online filesystem checking utility scans metadata and records what it
247 finds in the kernel incore state.
248 The following scheme is used for userspace to read the incore health status
249 of the filesystem:
250
251 .IP \[bu] 2
252 If a given sick flag is set in
253 .IR sick ,
254 then that piece of metadata has been observed to be damaged.
255 The same bit should be set in
256 .IR checked .
257 .IP \[bu]
258 If a given sick flag is set in
259 .I checked
260 but is not set in
261 .IR sick ,
262 then that piece of metadata has been checked and is not faulty.
263 .IP \[bu]
264 If a given sick flag is not set in
265 .IR checked ,
266 then no conclusion can be made.
267 .PP
268 The following flags apply to these fields:
269 .RS 0.4i
270 .TP
271 .B XFS_FSOP_GEOM_SICK_COUNTERS
272 Inode and space summary counters.
273 .TP
274 .B XFS_FSOP_GEOM_SICK_UQUOTA
275 User quota information.
276 .TP
277 .B XFS_FSOP_GEOM_SICK_GQUOTA
278 Group quota information.
279 .TP
280 .B XFS_FSOP_GEOM_SICK_PQUOTA
281 Project quota information.
282 .TP
283 .B XFS_FSOP_GEOM_SICK_RT_BITMAP
284 Free space bitmap for the realtime device.
285 .TP
286 .B XFS_FSOP_GEOM_SICK_RT_SUMMARY
287 Free space summary for the realtime device.
288 .TP
289 .B XFS_FSOP_GEOM_SICK_QUOTACHECK
290 Quota resource usage counters.
291 .RE
292
293 .SH RETURN VALUE
294 On error, \-1 is returned, and
295 .I errno
296 is set to indicate the error.
297 .PP
298 .SH ERRORS
299 Error codes can be one of, but are not limited to, the following:
300 .TP
301 .B EFAULT
302 The kernel was not able to copy into the userspace buffer.
303 .TP
304 .B EFSBADCRC
305 Metadata checksum validation failed while performing the query.
306 .TP
307 .B EFSCORRUPTED
308 Metadata corruption was encountered while performing the query.
309 .TP
310 .B EIO
311 An I/O error was encountered while performing the query.
312 .SH CONFORMING TO
313 This API is specific to XFS filesystem on the Linux kernel.
314 .SH SEE ALSO
315 .BR ioctl (2)