blob: 93fc96f760aa6636f46c2b3c46621f510e988151 [file] [log] [blame]
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +02001.. SPDX-License-Identifier: GPL-2.0
2
Mark Fashehc4b929b2008-10-08 19:44:18 -04003============
4Fiemap Ioctl
5============
6
7The fiemap ioctl is an efficient method for userspace to get file
8extent mappings. Instead of block-by-block mapping (such as bmap), fiemap
9returns a list of extents.
10
11
12Request Basics
13--------------
14
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +020015A fiemap request is encoded within struct fiemap::
Mark Fashehc4b929b2008-10-08 19:44:18 -040016
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +020017 struct fiemap {
Mark Fashehc4b929b2008-10-08 19:44:18 -040018 __u64 fm_start; /* logical offset (inclusive) at
19 * which to start mapping (in) */
20 __u64 fm_length; /* logical length of mapping which
21 * userspace cares about (in) */
22 __u32 fm_flags; /* FIEMAP_FLAG_* flags for request (in/out) */
23 __u32 fm_mapped_extents; /* number of extents that were
24 * mapped (out) */
25 __u32 fm_extent_count; /* size of fm_extents array (in) */
26 __u32 fm_reserved;
27 struct fiemap_extent fm_extents[0]; /* array of mapped extents (out) */
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +020028 };
Mark Fashehc4b929b2008-10-08 19:44:18 -040029
30
31fm_start, and fm_length specify the logical range within the file
32which the process would like mappings for. Extents returned mirror
33those on disk - that is, the logical offset of the 1st returned extent
34may start before fm_start, and the range covered by the last returned
35extent may end after fm_length. All offsets and lengths are in bytes.
36
37Certain flags to modify the way in which mappings are looked up can be
38set in fm_flags. If the kernel doesn't understand some particular
39flags, it will return EBADR and the contents of fm_flags will contain
40the set of flags which caused the error. If the kernel is compatible
41with all flags passed, the contents of fm_flags will be unmodified.
42It is up to userspace to determine whether rejection of a particular
Francis Galieguea33f3222010-04-23 00:08:02 +020043flag is fatal to its operation. This scheme is intended to allow the
Mark Fashehc4b929b2008-10-08 19:44:18 -040044fiemap interface to grow in the future but without losing
45compatibility with old software.
46
47fm_extent_count specifies the number of elements in the fm_extents[] array
48that can be used to return extents. If fm_extent_count is zero, then the
49fm_extents[] array is ignored (no extents will be returned), and the
50fm_mapped_extents count will hold the number of extents needed in
51fm_extents[] to hold the file's current mapping. Note that there is
52nothing to prevent the file from changing between calls to FIEMAP.
53
54The following flags can be set in fm_flags:
55
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +020056FIEMAP_FLAG_SYNC
57 If this flag is set, the kernel will sync the file before mapping extents.
Mark Fashehc4b929b2008-10-08 19:44:18 -040058
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +020059FIEMAP_FLAG_XATTR
60 If this flag is set, the extents returned will describe the inodes
61 extended attribute lookup tree, instead of its data tree.
Mark Fashehc4b929b2008-10-08 19:44:18 -040062
63
64Extent Mapping
65--------------
66
67Extent information is returned within the embedded fm_extents array
68which userspace must allocate along with the fiemap structure. The
69number of elements in the fiemap_extents[] array should be passed via
70fm_extent_count. The number of extents mapped by kernel will be
71returned via fm_mapped_extents. If the number of fiemap_extents
72allocated is less than would be required to map the requested range,
73the maximum number of extents that can be mapped in the fm_extent[]
74array will be returned and fm_mapped_extents will be equal to
75fm_extent_count. In that case, the last extent in the array will not
76complete the requested range and will not have the FIEMAP_EXTENT_LAST
77flag set (see the next section on extent flags).
78
79Each extent is described by a single fiemap_extent structure as
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +020080returned in fm_extents::
Mark Fashehc4b929b2008-10-08 19:44:18 -040081
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +020082 struct fiemap_extent {
83 __u64 fe_logical; /* logical offset in bytes for the start of
84 * the extent */
85 __u64 fe_physical; /* physical offset in bytes for the start
86 * of the extent */
87 __u64 fe_length; /* length in bytes for the extent */
88 __u64 fe_reserved64[2];
89 __u32 fe_flags; /* FIEMAP_EXTENT_* flags for this extent */
90 __u32 fe_reserved[3];
91 };
Mark Fashehc4b929b2008-10-08 19:44:18 -040092
93All offsets and lengths are in bytes and mirror those on disk. It is valid
Francis Galieguea33f3222010-04-23 00:08:02 +020094for an extents logical offset to start before the request or its logical
Mark Fashehc4b929b2008-10-08 19:44:18 -040095length to extend past the request. Unless FIEMAP_EXTENT_NOT_ALIGNED is
96returned, fe_logical, fe_physical, and fe_length will be aligned to the
97block size of the file system. With the exception of extents flagged as
98FIEMAP_EXTENT_MERGED, adjacent extents will not be merged.
99
100The fe_flags field contains flags which describe the extent returned.
101A special flag, FIEMAP_EXTENT_LAST is always set on the last extent in
102the file so that the process making fiemap calls can determine when no
103more extents are available, without having to call the ioctl again.
104
105Some flags are intentionally vague and will always be set in the
106presence of other more specific flags. This way a program looking for
107a general property does not have to know all existing and future flags
108which imply that property.
109
110For example, if FIEMAP_EXTENT_DATA_INLINE or FIEMAP_EXTENT_DATA_TAIL
111are set, FIEMAP_EXTENT_NOT_ALIGNED will also be set. A program looking
112for inline or tail-packed data can key on the specific flag. Software
113which simply cares not to try operating on non-aligned extents
114however, can just key on FIEMAP_EXTENT_NOT_ALIGNED, and not have to
115worry about all present and future flags which might imply unaligned
116data. Note that the opposite is not true - it would be valid for
117FIEMAP_EXTENT_NOT_ALIGNED to appear alone.
118
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200119FIEMAP_EXTENT_LAST
120 This is generally the last extent in the file. A mapping attempt past
121 this extent may return nothing. Some implementations set this flag to
122 indicate this extent is the last one in the range queried by the user
123 (via fiemap->fm_length).
Mark Fashehc4b929b2008-10-08 19:44:18 -0400124
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200125FIEMAP_EXTENT_UNKNOWN
126 The location of this extent is currently unknown. This may indicate
127 the data is stored on an inaccessible volume or that no storage has
128 been allocated for the file yet.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400129
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200130FIEMAP_EXTENT_DELALLOC
131 This will also set FIEMAP_EXTENT_UNKNOWN.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400132
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200133 Delayed allocation - while there is data for this extent, its
134 physical location has not been allocated yet.
135
136FIEMAP_EXTENT_ENCODED
137 This extent does not consist of plain filesystem blocks but is
138 encoded (e.g. encrypted or compressed). Reading the data in this
139 extent via I/O to the block device will have undefined results.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400140
141Note that it is *always* undefined to try to update the data
142in-place by writing to the indicated location without the
143assistance of the filesystem, or to access the data using the
144information returned by the FIEMAP interface while the filesystem
145is mounted. In other words, user applications may only read the
146extent data via I/O to the block device while the filesystem is
147unmounted, and then only if the FIEMAP_EXTENT_ENCODED flag is
148clear; user applications must not try reading or writing to the
149filesystem via the block device under any other circumstances.
150
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200151FIEMAP_EXTENT_DATA_ENCRYPTED
152 This will also set FIEMAP_EXTENT_ENCODED
153 The data in this extent has been encrypted by the file system.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400154
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200155FIEMAP_EXTENT_NOT_ALIGNED
156 Extent offsets and length are not guaranteed to be block aligned.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400157
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200158FIEMAP_EXTENT_DATA_INLINE
Mark Fashehc4b929b2008-10-08 19:44:18 -0400159 This will also set FIEMAP_EXTENT_NOT_ALIGNED
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200160 Data is located within a meta data block.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400161
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200162FIEMAP_EXTENT_DATA_TAIL
Mark Fashehc4b929b2008-10-08 19:44:18 -0400163 This will also set FIEMAP_EXTENT_NOT_ALIGNED
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200164 Data is packed into a block with data from other files.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400165
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200166FIEMAP_EXTENT_UNWRITTEN
167 Unwritten extent - the extent is allocated but its data has not been
168 initialized. This indicates the extent's data will be all zero if read
169 through the filesystem but the contents are undefined if read directly from
170 the device.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400171
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200172FIEMAP_EXTENT_MERGED
173 This will be set when a file does not support extents, i.e., it uses a block
174 based addressing scheme. Since returning an extent for each block back to
175 userspace would be highly inefficient, the kernel will try to merge most
176 adjacent blocks into 'extents'.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400177
178
179VFS -> File System Implementation
180---------------------------------
181
182File systems wishing to support fiemap must implement a ->fiemap callback on
183their inode_operations structure. The fs ->fiemap call is responsible for
Francis Galieguea33f3222010-04-23 00:08:02 +0200184defining its set of supported fiemap flags, and calling a helper function on
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200185each discovered extent::
Mark Fashehc4b929b2008-10-08 19:44:18 -0400186
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200187 struct inode_operations {
Mark Fashehc4b929b2008-10-08 19:44:18 -0400188 ...
189
190 int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start,
191 u64 len);
192
193->fiemap is passed struct fiemap_extent_info which describes the
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200194fiemap request::
Mark Fashehc4b929b2008-10-08 19:44:18 -0400195
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200196 struct fiemap_extent_info {
Mark Fashehc4b929b2008-10-08 19:44:18 -0400197 unsigned int fi_flags; /* Flags as passed from user */
198 unsigned int fi_extents_mapped; /* Number of mapped extents */
199 unsigned int fi_extents_max; /* Size of fiemap_extent array */
200 struct fiemap_extent *fi_extents_start; /* Start of fiemap_extent array */
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200201 };
Mark Fashehc4b929b2008-10-08 19:44:18 -0400202
203It is intended that the file system should not need to access any of this
Dmitry Monakhov913e0272015-02-10 14:09:29 -0800204structure directly. Filesystem handlers should be tolerant to signals and return
205EINTR once fatal signal received.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400206
207
208Flag checking should be done at the beginning of the ->fiemap callback via the
Linus Torvalds0b166a52020-06-05 16:19:28 -0700209fiemap_prep() helper::
Mark Fashehc4b929b2008-10-08 19:44:18 -0400210
Linus Torvalds0b166a52020-06-05 16:19:28 -0700211 int fiemap_prep(struct inode *inode, struct fiemap_extent_info *fieinfo,
212 u64 start, u64 *len, u32 supported_flags);
Mark Fashehc4b929b2008-10-08 19:44:18 -0400213
Matt LaPlante19f59462009-04-27 15:06:31 +0200214The struct fieinfo should be passed in as received from ioctl_fiemap(). The
Mark Fashehc4b929b2008-10-08 19:44:18 -0400215set of fiemap flags which the fs understands should be passed via fs_flags. If
Linus Torvalds0b166a52020-06-05 16:19:28 -0700216fiemap_prep finds invalid user flags, it will place the bad values in
Mark Fashehc4b929b2008-10-08 19:44:18 -0400217fieinfo->fi_flags and return -EBADR. If the file system gets -EBADR, from
Linus Torvalds0b166a52020-06-05 16:19:28 -0700218fiemap_prep(), it should immediately exit, returning that error back to
219ioctl_fiemap(). Additionally the range is validate against the supported
220maximum file size.
Mark Fashehc4b929b2008-10-08 19:44:18 -0400221
222
223For each extent in the request range, the file system should call
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200224the helper function, fiemap_fill_next_extent()::
Mark Fashehc4b929b2008-10-08 19:44:18 -0400225
Mauro Carvalho Chehabe6f7df72020-04-27 23:17:04 +0200226 int fiemap_fill_next_extent(struct fiemap_extent_info *info, u64 logical,
227 u64 phys, u64 len, u32 flags, u32 dev);
Mark Fashehc4b929b2008-10-08 19:44:18 -0400228
229fiemap_fill_next_extent() will use the passed values to populate the
230next free extent in the fm_extents array. 'General' extent flags will
231automatically be set from specific flags on behalf of the calling file
232system so that the userspace API is not broken.
233
234fiemap_fill_next_extent() returns 0 on success, and 1 when the
235user-supplied fm_extents array is full. If an error is encountered
236while copying the extent to user memory, -EFAULT will be returned.