Debian Codegraph @

upstream/debian-trixie/man2/ioctl_fsmap.2

raw
1 .\" Copyright 2017, Oracle. All rights reserved.
2 .\"
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .\"
5 .TH ioctl_fsmap 2 2024-06-13 "Linux man-pages 6.9.1"
6 .SH NAME
7 ioctl_fsmap,
8 FS_IOC_GETFSMAP
9 \-
10 retrieve the physical layout of the filesystem
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ", " \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#include <linux/fsmap.h> " "/* Definition of " FS_IOC_GETFSMAP ,
17 .BR " FM?_OF_*" ", and " *FMR_OWN_* " constants */"
18 .B #include <sys/ioctl.h>
19 .P
20 .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
21 .fi
22 .SH DESCRIPTION
23 This
24 .BR ioctl (2)
25 operation retrieves physical extent mappings for a filesystem.
26 This information can be used to discover which files are mapped to a physical
27 block, examine free space, or find known bad blocks, among other things.
28 .P
29 The sole argument to this operation should be a pointer to a single
30 .IR "struct fsmap_head" ":"
31 .P
32 .in +4n
33 .EX
34 struct fsmap {
35 __u32 fmr_device; /* Device ID */
36 __u32 fmr_flags; /* Mapping flags */
37 __u64 fmr_physical; /* Device offset of segment */
38 __u64 fmr_owner; /* Owner ID */
39 __u64 fmr_offset; /* File offset of segment */
40 __u64 fmr_length; /* Length of segment */
41 __u64 fmr_reserved[3]; /* Must be zero */
42 };
43 \&
44 struct fsmap_head {
45 __u32 fmh_iflags; /* Control flags */
46 __u32 fmh_oflags; /* Output flags */
47 __u32 fmh_count; /* # of entries in array incl. input */
48 __u32 fmh_entries; /* # of entries filled in (output) */
49 __u64 fmh_reserved[6]; /* Must be zero */
50 \&
51 struct fsmap fmh_keys[2]; /* Low and high keys for
52 the mapping search */
53 struct fsmap fmh_recs[]; /* Returned records */
54 };
55 .EE
56 .in
57 .P
58 The two
59 .I fmh_keys
60 array elements specify the lowest and highest reverse-mapping
61 key for which the application would like physical mapping
62 information.
63 A reverse mapping key consists of the tuple (device, block, owner, offset).
64 The owner and offset fields are part of the key because some filesystems
65 support sharing physical blocks between multiple files and
66 therefore may return multiple mappings for a given physical block.
67 .P
68 Filesystem mappings are copied into the
69 .I fmh_recs
70 array, which immediately follows the header data.
71 .\"
72 .SS Fields of struct fsmap_head
73 The
74 .I fmh_iflags
75 field is a bit mask passed to the kernel to alter the output.
76 No flags are currently defined, so the caller must set this value to zero.
77 .P
78 The
79 .I fmh_oflags
80 field is a bit mask of flags set by the kernel concerning the returned mappings.
81 If
82 .B FMH_OF_DEV_T
83 is set, then the
84 .I fmr_device
85 field represents a
86 .I dev_t
87 structure containing the major and minor numbers of the block device.
88 .P
89 The
90 .I fmh_count
91 field contains the number of elements in the array being passed to the
92 kernel.
93 If this value is 0,
94 .I fmh_entries
95 will be set to the number of records that would have been returned had
96 the array been large enough;
97 no mapping information will be returned.
98 .P
99 The
100 .I fmh_entries
101 field contains the number of elements in the
102 .I fmh_recs
103 array that contain useful information.
104 .P
105 The
106 .I fmh_reserved
107 fields must be set to zero.
108 .\"
109 .SS Keys
110 The two key records in
111 .I fsmap_head.fmh_keys
112 specify the lowest and highest extent records in the keyspace that the caller
113 wants returned.
114 A filesystem that can share blocks between files likely requires the tuple
115 .RI "(" "device" ", " "physical" ", " "owner" ", " "offset" ", " "flags" ")"
116 to uniquely index any filesystem mapping record.
117 Classic non-sharing filesystems might be able to identify any record with only
118 .RI "(" "device" ", " "physical" ", " "flags" ")."
119 For example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem will
120 only return records for extents starting at or above 36\ KiB on disk.
121 If the high key is set to (8:0, 1048576, 0, 0, 0),
122 only records below 1\ MiB will be returned.
123 The format of
124 .I fmr_device
125 in the keys must match the format of the same field in the output records,
126 as defined below.
127 By convention, the field
128 .I fsmap_head.fmh_keys[0]
129 must contain the low key and
130 .I fsmap_head.fmh_keys[1]
131 must contain the high key for the operation.
132 .P
133 For convenience, if
134 .I fmr_length
135 is set in the low key, it will be added to
136 .IR fmr_block " or " fmr_offset
137 as appropriate.
138 The caller can take advantage of this subtlety to set up subsequent calls
139 by copying
140 .I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1]
141 into the low key.
142 The function
143 .I fsmap_advance
144 (defined in
145 .IR linux/fsmap.h )
146 provides this functionality.
147 .\"
148 .SS Fields of struct fsmap
149 The
150 .I fmr_device
151 field uniquely identifies the underlying storage device.
152 If the
153 .B FMH_OF_DEV_T
154 flag is set in the header's
155 .I fmh_oflags
156 field, this field contains a
157 .I dev_t
158 from which major and minor numbers can be extracted.
159 If the flag is not set, this field contains a value that must be unique
160 for each unique storage device.
161 .P
162 The
163 .I fmr_physical
164 field contains the disk address of the extent in bytes.
165 .P
166 The
167 .I fmr_owner
168 field contains the owner of the extent.
169 This is an inode number unless
170 .B FMR_OF_SPECIAL_OWNER
171 is set in the
172 .I fmr_flags
173 field, in which case the value is determined by the filesystem.
174 See the section below about owner values for more details.
175 .P
176 The
177 .I fmr_offset
178 field contains the logical address in the mapping record in bytes.
179 This field has no meaning if the
180 .BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP
181 flags are set in
182 .IR fmr_flags "."
183 .P
184 The
185 .I fmr_length
186 field contains the length of the extent in bytes.
187 .P
188 The
189 .I fmr_flags
190 field is a bit mask of extent state flags.
191 The bits are:
192 .RS 0.4i
193 .TP
194 .B FMR_OF_PREALLOC
195 The extent is allocated but not yet written.
196 .TP
197 .B FMR_OF_ATTR_FORK
198 This extent contains extended attribute data.
199 .TP
200 .B FMR_OF_EXTENT_MAP
201 This extent contains extent map information for the owner.
202 .TP
203 .B FMR_OF_SHARED
204 Parts of this extent may be shared.
205 .TP
206 .B FMR_OF_SPECIAL_OWNER
207 The
208 .I fmr_owner
209 field contains a special value instead of an inode number.
210 .TP
211 .B FMR_OF_LAST
212 This is the last record in the data set.
213 .RE
214 .P
215 The
216 .I fmr_reserved
217 field will be set to zero.
218 .\"
219 .SS Owner values
220 Generally, the value of the
221 .I fmr_owner
222 field for non-metadata extents should be an inode number.
223 However, filesystems are under no obligation to report inode numbers;
224 they may instead report
225 .B FMR_OWN_UNKNOWN
226 if the inode number cannot easily be retrieved, if the caller lacks
227 sufficient privilege, if the filesystem does not support stable
228 inode numbers, or for any other reason.
229 If a filesystem wishes to condition the reporting of inode numbers based
230 on process capabilities, it is strongly urged that the
231 .B CAP_SYS_ADMIN
232 capability be used for this purpose.
233 .TP
234 The following special owner values are generic to all filesystems:
235 .RS 0.4i
236 .TP
237 .B FMR_OWN_FREE
238 Free space.
239 .TP
240 .B FMR_OWN_UNKNOWN
241 This extent is in use but its owner is not known or not easily retrieved.
242 .TP
243 .B FMR_OWN_METADATA
244 This extent is filesystem metadata.
245 .RE
246 .P
247 XFS can return the following special owner values:
248 .RS 0.4i
249 .TP
250 .B XFS_FMR_OWN_FREE
251 Free space.
252 .TP
253 .B XFS_FMR_OWN_UNKNOWN
254 This extent is in use but its owner is not known or not easily retrieved.
255 .TP
256 .B XFS_FMR_OWN_FS
257 Static filesystem metadata which exists at a fixed address.
258 These are the AG superblock, the AGF, the AGFL, and the AGI headers.
259 .TP
260 .B XFS_FMR_OWN_LOG
261 The filesystem journal.
262 .TP
263 .B XFS_FMR_OWN_AG
264 Allocation group metadata, such as the free space btrees and the
265 reverse mapping btrees.
266 .TP
267 .B XFS_FMR_OWN_INOBT
268 The inode and free inode btrees.
269 .TP
270 .B XFS_FMR_OWN_INODES
271 Inode records.
272 .TP
273 .B XFS_FMR_OWN_REFC
274 Reference count information.
275 .TP
276 .B XFS_FMR_OWN_COW
277 This extent is being used to stage a copy-on-write.
278 .TP
279 .B XFS_FMR_OWN_DEFECTIVE:
280 This extent has been marked defective either by the filesystem or the
281 underlying device.
282 .RE
283 .P
284 ext4 can return the following special owner values:
285 .RS 0.4i
286 .TP
287 .B EXT4_FMR_OWN_FREE
288 Free space.
289 .TP
290 .B EXT4_FMR_OWN_UNKNOWN
291 This extent is in use but its owner is not known or not easily retrieved.
292 .TP
293 .B EXT4_FMR_OWN_FS
294 Static filesystem metadata which exists at a fixed address.
295 This is the superblock and the group descriptors.
296 .TP
297 .B EXT4_FMR_OWN_LOG
298 The filesystem journal.
299 .TP
300 .B EXT4_FMR_OWN_INODES
301 Inode records.
302 .TP
303 .B EXT4_FMR_OWN_BLKBM
304 Block bit map.
305 .TP
306 .B EXT4_FMR_OWN_INOBM
307 Inode bit map.
308 .RE
309 .SH RETURN VALUE
310 On error, \-1 is returned, and
311 .I errno
312 is set to indicate the error.
313 .SH ERRORS
314 The error placed in
315 .I errno
316 can be one of, but is not limited to, the following:
317 .TP
318 .B EBADF
319 .I fd
320 is not open for reading.
321 .TP
322 .B EBADMSG
323 The filesystem has detected a checksum error in the metadata.
324 .TP
325 .B EFAULT
326 The pointer passed in was not mapped to a valid memory address.
327 .TP
328 .B EINVAL
329 The array is not long enough, the keys do not point to a valid part of
330 the filesystem, the low key points to a higher point in the filesystem's
331 physical storage address space than the high key, or a nonzero value
332 was passed in one of the fields that must be zero.
333 .TP
334 .B ENOMEM
335 Insufficient memory to process the operation.
336 .TP
337 .B EOPNOTSUPP
338 The filesystem does not support this operation.
339 .TP
340 .B EUCLEAN
341 The filesystem metadata is corrupt and needs repair.
342 .SH STANDARDS
343 Linux.
344 .P
345 Not all filesystems support it.
346 .SH HISTORY
347 Linux 4.12.
348 .SH EXAMPLES
349 See
350 .I io/fsmap.c
351 in the
352 .I xfsprogs
353 distribution for a sample program.
354 .SH SEE ALSO
355 .BR ioctl (2)