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