1 .. SPDX-License-Identifier: GPL-2.0
2
3 ============
4 Fiemap Ioctl
5 ============
6
7 The fiemap ioctl is an efficient method for us
8 extent mappings. Instead of block-by-block map
9 returns a list of extents.
10
11
12 Request Basics
13 --------------
14
15 A fiemap request is encoded within struct fiem
16
17 struct fiemap {
18 __u64 fm_start; /* logical of
19 * which to s
20 __u64 fm_length; /* logical le
21 * userspace
22 __u32 fm_flags; /* FIEMAP_FLA
23 __u32 fm_mapped_extents; /* number o
24 * mapped (
25 __u32 fm_extent_count; /* size of fm
26 __u32 fm_reserved;
27 struct fiemap_extent fm_extents[0]; /*
28 };
29
30
31 fm_start, and fm_length specify the logical ra
32 which the process would like mappings for. Ext
33 those on disk - that is, the logical offset of
34 may start before fm_start, and the range cover
35 extent may end after fm_length. All offsets an
36
37 Certain flags to modify the way in which mappi
38 set in fm_flags. If the kernel doesn't underst
39 flags, it will return EBADR and the contents o
40 the set of flags which caused the error. If th
41 with all flags passed, the contents of fm_flag
42 It is up to userspace to determine whether rej
43 flag is fatal to its operation. This scheme is
44 fiemap interface to grow in the future but wit
45 compatibility with old software.
46
47 fm_extent_count specifies the number of elemen
48 that can be used to return extents. If fm_ext
49 fm_extents[] array is ignored (no extents will
50 fm_mapped_extents count will hold the number o
51 fm_extents[] to hold the file's current mappin
52 nothing to prevent the file from changing betw
53
54 The following flags can be set in fm_flags:
55
56 FIEMAP_FLAG_SYNC
57 If this flag is set, the kernel will sync th
58
59 FIEMAP_FLAG_XATTR
60 If this flag is set, the extents returned wi
61 extended attribute lookup tree, instead of i
62
63
64 Extent Mapping
65 --------------
66
67 Extent information is returned within the embe
68 which userspace must allocate along with the f
69 number of elements in the fiemap_extents[] arr
70 fm_extent_count. The number of extents mapped
71 returned via fm_mapped_extents. If the number
72 allocated is less than would be required to ma
73 the maximum number of extents that can be mapp
74 array will be returned and fm_mapped_extents w
75 fm_extent_count. In that case, the last extent
76 complete the requested range and will not have
77 flag set (see the next section on extent flags
78
79 Each extent is described by a single fiemap_ex
80 returned in fm_extents::
81
82 struct fiemap_extent {
83 __u64 fe_logical; /* logica
84 * the extent *
85 __u64 fe_physical; /* physic
86 * of the exten
87 __u64 fe_length; /* length
88 __u64 fe_reserved64[2];
89 __u32 fe_flags; /* FIEMAP
90 __u32 fe_reserved[3];
91 };
92
93 All offsets and lengths are in bytes and mirro
94 for an extents logical offset to start before
95 length to extend past the request. Unless FIE
96 returned, fe_logical, fe_physical, and fe_leng
97 block size of the file system. With the excep
98 FIEMAP_EXTENT_MERGED, adjacent extents will no
99
100 The fe_flags field contains flags which descri
101 A special flag, FIEMAP_EXTENT_LAST is always s
102 the file so that the process making fiemap cal
103 more extents are available, without having to
104
105 Some flags are intentionally vague and will al
106 presence of other more specific flags. This wa
107 a general property does not have to know all e
108 which imply that property.
109
110 For example, if FIEMAP_EXTENT_DATA_INLINE or F
111 are set, FIEMAP_EXTENT_NOT_ALIGNED will also b
112 for inline or tail-packed data can key on the
113 which simply cares not to try operating on non
114 however, can just key on FIEMAP_EXTENT_NOT_ALI
115 worry about all present and future flags which
116 data. Note that the opposite is not true - it
117 FIEMAP_EXTENT_NOT_ALIGNED to appear alone.
118
119 FIEMAP_EXTENT_LAST
120 This is generally the last extent in the fil
121 this extent may return nothing. Some impleme
122 indicate this extent is the last one in the
123 (via fiemap->fm_length).
124
125 FIEMAP_EXTENT_UNKNOWN
126 The location of this extent is currently unk
127 the data is stored on an inaccessible volume
128 been allocated for the file yet.
129
130 FIEMAP_EXTENT_DELALLOC
131 This will also set FIEMAP_EXTENT_UNKNOWN.
132
133 Delayed allocation - while there is data for
134 physical location has not been allocated yet
135
136 FIEMAP_EXTENT_ENCODED
137 This extent does not consist of plain filesy
138 encoded (e.g. encrypted or compressed). Rea
139 extent via I/O to the block device will have
140
141 Note that it is *always* undefined to try to u
142 in-place by writing to the indicated location
143 assistance of the filesystem, or to access the
144 information returned by the FIEMAP interface w
145 is mounted. In other words, user applications
146 extent data via I/O to the block device while
147 unmounted, and then only if the FIEMAP_EXTENT_
148 clear; user applications must not try reading
149 filesystem via the block device under any othe
150
151 FIEMAP_EXTENT_DATA_ENCRYPTED
152 This will also set FIEMAP_EXTENT_ENCODED
153 The data in this extent has been encrypted b
154
155 FIEMAP_EXTENT_NOT_ALIGNED
156 Extent offsets and length are not guaranteed
157
158 FIEMAP_EXTENT_DATA_INLINE
159 This will also set FIEMAP_EXTENT_NOT_ALIGNED
160 Data is located within a meta data block.
161
162 FIEMAP_EXTENT_DATA_TAIL
163 This will also set FIEMAP_EXTENT_NOT_ALIGNED
164 Data is packed into a block with data from o
165
166 FIEMAP_EXTENT_UNWRITTEN
167 Unwritten extent - the extent is allocated b
168 initialized. This indicates the extent's da
169 through the filesystem but the contents are
170 the device.
171
172 FIEMAP_EXTENT_MERGED
173 This will be set when a file does not suppor
174 based addressing scheme. Since returning an
175 userspace would be highly inefficient, the k
176 adjacent blocks into 'extents'.
177
178
179 VFS -> File System Implementation
180 ---------------------------------
181
182 File systems wishing to support fiemap must im
183 their inode_operations structure. The fs ->fie
184 defining its set of supported fiemap flags, an
185 each discovered extent::
186
187 struct inode_operations {
188 ...
189
190 int (*fiemap)(struct inode *, struct fi
191 u64 len);
192
193 ->fiemap is passed struct fiemap_extent_info w
194 fiemap request::
195
196 struct fiemap_extent_info {
197 unsigned int fi_flags; /* Fla
198 unsigned int fi_extents_mapped; /* Num
199 unsigned int fi_extents_max; /* Siz
200 struct fiemap_extent *fi_extents_start
201 };
202
203 It is intended that the file system should not
204 structure directly. Filesystem handlers should
205 EINTR once fatal signal received.
206
207
208 Flag checking should be done at the beginning
209 fiemap_prep() helper::
210
211 int fiemap_prep(struct inode *inode, struct
212 u64 start, u64 *len, u32 sup
213
214 The struct fieinfo should be passed in as rece
215 set of fiemap flags which the fs understands s
216 fiemap_prep finds invalid user flags, it will
217 fieinfo->fi_flags and return -EBADR. If the fi
218 fiemap_prep(), it should immediately exit, ret
219 ioctl_fiemap(). Additionally the range is val
220 maximum file size.
221
222
223 For each extent in the request range, the file
224 the helper function, fiemap_fill_next_extent()
225
226 int fiemap_fill_next_extent(struct fiemap_ex
227 u64 phys, u64 le
228
229 fiemap_fill_next_extent() will use the passed
230 next free extent in the fm_extents array. 'Gen
231 automatically be set from specific flags on be
232 system so that the userspace API is not broken
233
234 fiemap_fill_next_extent() returns 0 on success
235 user-supplied fm_extents array is full. If an
236 while copying the extent to user memory, -EFAU
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.