1IOCTL_GETFSMAP(2) Linux Programmer's Manual IOCTL_GETFSMAP(2)
2
6 ioctl_getfsmap - retrieve the physical layout of the filesystem
7
9 #include <sys/ioctl.h>
10 #include <linux/fs.h>
11 #include <linux/fsmap.h>
12 int ioctl(int fd, FS_IOC_GETFSMAP, struct fsmap_head * arg);
14
16 This ioctl(2) operation retrieves physical extent mappings for a
17 filesystem. This information can be used to discover which files are
18 mapped to a physical block, examine free space, or find known bad
19 blocks, among other things.
20 The sole argument to this operation should be a pointer to a single
22 struct fsmap_head:
23 struct fsmap {
25 __u32 fmr_device; /* Device ID */
26 __u32 fmr_flags; /* Mapping flags */
27 __u64 fmr_physical; /* Device offset of segment */
28 __u64 fmr_owner; /* Owner ID */
29 __u64 fmr_offset; /* File offset of segment */
30 __u64 fmr_length; /* Length of segment */
31 __u64 fmr_reserved[3]; /* Must be zero */
32 };
33 struct fsmap_head {
35 __u32 fmh_iflags; /* Control flags */
36 __u32 fmh_oflags; /* Output flags */
37 __u32 fmh_count; /* # of entries in array incl. input */
38 __u32 fmh_entries; /* # of entries filled in (output) */
39 __u64 fmh_reserved[6]; /* Must be zero */
40 struct fsmap fmh_keys[2]; /* Low and high keys for
42 the mapping search */
43 struct fsmap fmh_recs[]; /* Returned records */
44 };
45 The two fmh_keys array elements specify the lowest and highest reverse-
47 mapping key for which the application would like physical mapping
48 information. A reverse mapping key consists of the tuple (device,
49 block, owner, offset). The owner and offset fields are part of the key
50 because some filesystems support sharing physical blocks between multi‐
51 ple files and therefore may return multiple mappings for a given physi‐
52 cal block.
53 Filesystem mappings are copied into the fmh_recs array, which immedi‐
55 ately follows the header data.
56 Fields of struct fsmap_head
58 The fmh_iflags field is a bit mask passed to the kernel to alter the
59 output. No flags are currently defined, so the caller must set this
60 value to zero.
61 The fmh_oflags field is a bit mask of flags set by the kernel concern‐
63 ing the returned mappings. If FMH_OF_DEV_T is set, then the fmr_device
64 field represents a dev_t structure containing the major and minor num‐
65 bers of the block device.
66 The fmh_count field contains the number of elements in the array being
68 passed to the kernel. If this value is 0, fmh_entries will be set to
69 the number of records that would have been returned had the array been
70 large enough; no mapping information will be returned.
71 The fmh_entries field contains the number of elements in the fmh_recs
73 array that contain useful information.
74 The fmh_reserved fields must be set to zero.
76 Keys
78 The two key records in fsmap_head.fmh_keys specify the lowest and high‐
79 est extent records in the keyspace that the caller wants returned. A
80 filesystem that can share blocks between files likely requires the
81 tuple (device, physical, owner, offset, flags) to uniquely index any
82 filesystem mapping record. Classic non-sharing filesystems might be
83 able to identify any record with only (device, physical, flags). For
84 example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem
85 will only return records for extents starting at or above 36 KiB on
86 disk. If the high key is set to (8:0, 1048576, 0, 0, 0), only records
87 below 1 MiB will be returned. The format of fmr_device in the keys
88 must match the format of the same field in the output records, as
89 defined below. By convention, the field fsmap_head.fmh_keys[0] must
90 contain the low key and fsmap_head.fmh_keys[1] must contain the high
91 key for the request.
92 For convenience, if fmr_length is set in the low key, it will be added
94 to fmr_block or fmr_offset as appropriate. The caller can take advan‐
95 tage of this subtlety to set up subsequent calls by copying
96 fsmap_head.fmh_recs[fsmap_head.fmh_entries - 1] into the low key. The
97 function fsmap_advance (defined in linux/fsmap.h) provides this func‐
98 tionality.
99 Fields of struct fsmap
101 The fmr_device field uniquely identifies the underlying storage device.
102 If the FMH_OF_DEV_T flag is set in the header's fmh_oflags field, this
103 field contains a dev_t from which major and minor numbers can be
104 extracted. If the flag is not set, this field contains a value that
105 must be unique for each unique storage device.
106 The fmr_physical field contains the disk address of the extent in
108 bytes.
109 The fmr_owner field contains the owner of the extent. This is an inode
111 number unless FMR_OF_SPECIAL_OWNER is set in the fmr_flags field, in
112 which case the value is determined by the filesystem. See the section
113 below about owner values for more details.
114 The fmr_offset field contains the logical address in the mapping record
116 in bytes. This field has no meaning if the FMR_OF_SPECIAL_OWNER or
117 FMR_OF_EXTENT_MAP flags are set in fmr_flags.
118 The fmr_length field contains the length of the extent in bytes.
120 The fmr_flags field is a bit mask of extent state flags. The bits are:
122 FMR_OF_PREALLOC
124 The extent is allocated but not yet written.
125 FMR_OF_ATTR_FORK
127 This extent contains extended attribute data.
128 FMR_OF_EXTENT_MAP
130 This extent contains extent map information for the owner.
131 FMR_OF_SHARED
133 Parts of this extent may be shared.
134 FMR_OF_SPECIAL_OWNER
136 The fmr_owner field contains a special value instead of an
137 inode number.
138 FMR_OF_LAST
140 This is the last record in the data set.
141 The fmr_reserved field will be set to zero.
143 Owner values
145 Generally, the value of the fmr_owner field for non-metadata extents
146 should be an inode number. However, filesystems are under no obliga‐
147 tion to report inode numbers; they may instead report FMR_OWN_UNKNOWN
148 if the inode number cannot easily be retrieved, if the caller lacks
149 sufficient privilege, if the filesystem does not support stable inode
150 numbers, or for any other reason. If a filesystem wishes to condition
151 the reporting of inode numbers based on process capabilities, it is
152 strongly urged that the CAP_SYS_ADMIN capability be used for this pur‐
153 pose.
154 The following special owner values are generic to all filesystems:
156 FMR_OWN_FREE
158 Free space.
159 FMR_OWN_UNKNOWN
161 This extent is in use but its owner is not known or not eas‐
162 ily retrieved.
163 FMR_OWN_METADATA
165 This extent is filesystem metadata.
166 XFS can return the following special owner values:
168 XFS_FMR_OWN_FREE
170 Free space.
171 XFS_FMR_OWN_UNKNOWN
173 This extent is in use but its owner is not known or not eas‐
174 ily retrieved.
175 XFS_FMR_OWN_FS
177 Static filesystem metadata which exists at a fixed address.
178 These are the AG superblock, the AGF, the AGFL, and the AGI
179 headers.
180 XFS_FMR_OWN_LOG
182 The filesystem journal.
183 XFS_FMR_OWN_AG
185 Allocation group metadata, such as the free space btrees and
186 the reverse mapping btrees.
187 XFS_FMR_OWN_INOBT
189 The inode and free inode btrees.
190 XFS_FMR_OWN_INODES
192 Inode records.
193 XFS_FMR_OWN_REFC
195 Reference count information.
196 XFS_FMR_OWN_COW
198 This extent is being used to stage a copy-on-write.
199 XFS_FMR_OWN_DEFECTIVE:
201 This extent has been marked defective either by the filesys‐
202 tem or the underlying device.
203 ext4 can return the following special owner values:
205 EXT4_FMR_OWN_FREE
207 Free space.
208 EXT4_FMR_OWN_UNKNOWN
210 This extent is in use but its owner is not known or not eas‐
211 ily retrieved.
212 EXT4_FMR_OWN_FS
214 Static filesystem metadata which exists at a fixed address.
215 This is the superblock and the group descriptors.
216 EXT4_FMR_OWN_LOG
218 The filesystem journal.
219 EXT4_FMR_OWN_INODES
221 Inode records.
222 EXT4_FMR_OWN_BLKBM
224 Block bit map.
225 EXT4_FMR_OWN_INOBM
227 Inode bit map.
228
230 On error, -1 is returned, and errno is set to indicate the error.
231
233 The error placed in errno can be one of, but is not limited to, the
234 following:
235 EBADF fd is not open for reading.
237 EBADMSG
239 The filesystem has detected a checksum error in the metadata.
240 EFAULT The pointer passed in was not mapped to a valid memory address.
242 EINVAL The array is not long enough, the keys do not point to a valid
244 part of the filesystem, the low key points to a higher point in
245 the filesystem's physical storage address space than the high
246 key, or a nonzero value was passed in one of the fields that
247 must be zero.
248 ENOMEM Insufficient memory to process the request.
250 EOPNOTSUPP
252 The filesystem does not support this command.
253 EUCLEAN
255 The filesystem metadata is corrupt and needs repair.
256
258 The FS_IOC_GETFSMAP operation first appeared in Linux 4.12.
259
261 This API is Linux-specific. Not all filesystems support it.
262
264 See io/fsmap.c in the xfsprogs distribution for a sample program.
265
267 ioctl(2)
268
270 This page is part of release 5.07 of the Linux man-pages project. A
271 description of the project, information about reporting bugs, and the
272 latest version of this page, can be found at
273 https://www.kernel.org/doc/man-pages/.
274Linux 2020-06-09 IOCTL_GETFSMAP(2)