1 .\" Copyright (c) 2017, Oracle. All rights reserved.
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" The GNU General Public License's references to "object code"
10 .\" and "executables" are to be interpreted as the output of any
11 .\" document formatting or typesetting system, including
12 .\" intermediate and printed output.
14 .\" This manual is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 .\" GNU General Public License for more details.
19 .\" You should have received a copy of the GNU General Public
20 .\" License along with this manual; if not, see
21 .\" <http://www.gnu.org/licenses/>.
23 .TH IOCTL_GETFSMAP 2 2017-07-13 "Linux" "Linux Programmer's Manual"
25 ioctl_getfsmap \- retrieve the physical layout of the filesystem
28 .B #include <sys/ioctl.h>
30 .B #include <linux/fs.h>
32 .B #include <linux/fsmap.h>
34 .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
38 operation retrieves physical extent mappings for a filesystem.
39 This information can be used to discover which files are mapped to a physical
40 block, examine free space, or find known bad blocks, among other things.
42 The sole argument to this operation should be a pointer to a single
43 .IR "struct fsmap_head" ":"
48 __u32 fmr_device; /* Device ID */
49 __u32 fmr_flags; /* Mapping flags */
50 __u64 fmr_physical; /* Device offset of segment */
51 __u64 fmr_owner; /* Owner ID */
52 __u64 fmr_offset; /* File offset of segment */
53 __u64 fmr_length; /* Length of segment */
54 __u64 fmr_reserved[3]; /* Must be zero */
58 __u32 fmh_iflags; /* Control flags */
59 __u32 fmh_oflags; /* Output flags */
60 __u32 fmh_count; /* # of entries in array incl. input */
61 __u32 fmh_entries; /* # of entries filled in (output) */
62 __u64 fmh_reserved[6]; /* Must be zero */
64 struct fsmap fmh_keys[2]; /* Low and high keys for
66 struct fsmap fmh_recs[]; /* Returned records */
73 array elements specify the lowest and highest reverse-mapping
74 key for which the application would like physical mapping
76 A reverse mapping key consists of the tuple (device, block, owner, offset).
77 The owner and offset fields are part of the key because some filesystems
78 support sharing physical blocks between multiple files and
79 therefore may return multiple mappings for a given physical block.
81 Filesystem mappings are copied into the
83 array, which immediately follows the header data.
85 .SS Fields of struct fsmap_head
89 field is a bit mask passed to the kernel to alter the output.
90 No flags are currently defined, so the caller must set this value to zero.
94 field is a bit mask of flags set by the kernel concerning the returned mappings.
101 structure containing the major and minor numbers of the block device.
105 field contains the number of elements in the array being passed to the
109 will be set to the number of records that would have been returned had
110 the array been large enough;
111 no mapping information will be returned.
115 field contains the number of elements in the
117 array that contain useful information.
121 fields must be set to zero.
125 The two key records in
126 .I fsmap_head.fmh_keys
127 specify the lowest and highest extent records in the keyspace that the caller
129 A filesystem that can share blocks between files likely requires the tuple
130 .RI "(" "device" ", " "physical" ", " "owner" ", " "offset" ", " "flags" ")"
131 to uniquely index any filesystem mapping record.
132 Classic non-sharing filesystems might be able to identify any record with only
133 .RI "(" "device" ", " "physical" ", " "flags" ")."
134 For example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem will
135 only return records for extents starting at or above 36KiB on disk.
136 If the high key is set to (8:0, 1048576, 0, 0, 0), only records below 1MiB will
140 in the keys must match the format of the same field in the output records,
142 By convention, the field
143 .I fsmap_head.fmh_keys[0]
144 must contain the low key and
145 .I fsmap_head.fmh_keys[1]
146 must contain the high key for the request.
150 is set in the low key, it will be added to
151 .IR fmr_block " or " fmr_offset
153 The caller can take advantage of this subtlety to set up subsequent calls
155 .I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1]
161 provides this functionality.
163 .SS Fields of struct fsmap
167 field uniquely identifies the underlying storage device.
170 flag is set in the header's
172 field, this field contains a
174 from which major and minor numbers can be extracted.
175 If the flag is not set, this field contains a value that must be unique
176 for each unique storage device.
180 field contains the disk address of the extent in bytes.
184 field contains the owner of the extent.
185 This is an inode number unless
186 .B FMR_OF_SPECIAL_OWNER
189 field, in which case the value is determined by the filesystem.
190 See the section below about owner values for more details.
194 field contains the logical address in the mapping record in bytes.
195 This field has no meaning if the
196 .BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP
202 field contains the length of the extent in bytes.
206 field is a bit mask of extent state flags.
211 The extent is allocated but not yet written.
214 This extent contains extended attribute data.
217 This extent contains extent map information for the owner.
220 Parts of this extent may be shared.
222 .B FMR_OF_SPECIAL_OWNER
225 field contains a special value instead of an inode number.
228 This is the last record in the filesystem.
233 field will be set to zero.
236 Generally, the value of the
238 field for non-metadata extents should be an inode number.
239 However, filesystems are under no obligation to report inode numbers;
240 they may instead report
242 if the inode number cannot easily be retrieved, if the caller lacks
243 sufficient privilege, if the filesystem does not support stable
244 inode numbers, or for any other reason.
245 If a filesystem wishes to condition the reporting of inode numbers based
246 on process capabilities, it is strongly urged that the
248 capability be used for this purpose.
250 The following special owner values are generic to all filesystems:
257 This extent is in use but its owner is not known or not easily retrieved.
260 This extent is filesystem metadata.
263 XFS can return the following special owner values:
269 .B XFS_FMR_OWN_UNKNOWN
270 This extent is in use but its owner is not known or not easily retrieved.
273 Static filesystem metadata which exists at a fixed address.
274 These are the AG superblock, the AGF, the AGFL, and the AGI headers.
277 The filesystem journal.
280 Allocation group metadata, such as the free space btrees and the
281 reverse mapping btrees.
284 The inode and free inode btrees.
286 .B XFS_FMR_OWN_INODES
290 Reference count information.
293 This extent is being used to stage a copy-on-write.
295 .B XFS_FMR_OWN_DEFECTIVE:
296 This extent has been marked defective either by the filesystem or the
300 ext4 can return the following special owner values:
306 .B EXT4_FMR_OWN_UNKNOWN
307 This extent is in use but its owner is not known or not easily retrieved.
310 Static filesystem metadata which exists at a fixed address.
311 This is the superblock and the group descriptors.
314 The filesystem journal.
316 .B EXT4_FMR_OWN_INODES
319 .B EXT4_FMR_OWN_BLKBM
322 .B EXT4_FMR_OWN_INOBM
326 On error, \-1 is returned, and
328 is set to indicate the error.
333 can be one of, but is not limited to, the following:
337 is not open for reading.
340 The filesystem has detected a checksum error in the metadata.
343 The pointer passed in was not mapped to a valid memory address.
346 The array is not long enough, the keys do not point to a valid part of
347 the filesystem, the low key points to a higher point in the filesystem's
348 physical storage address space than the high key, or a non-zero value
349 was passed in one of the fields that must be zero.
352 Insufficient memory to process the request.
355 The filesystem does not support this command.
358 The filesystem metadata is corrupt and needs repair.
362 operation first appeared in Linux 4.12.
364 This API is Linux-specific.
365 Not all filesystems support it.
371 distribution for a sample program.