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