Debian Codegraph @

upstream/debian-unstable/man2/ioctl_fsmap.2

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