fiemap.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3============
  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
 15A fiemap request is encoded within struct fiemap:
 16
 17.. kernel-doc:: include/uapi/linux/fiemap.h
 18   :identifiers: fiemap
 19
 20fm_start, and fm_length specify the logical range within the file
 21which the process would like mappings for. Extents returned mirror
 22those on disk - that is, the logical offset of the 1st returned extent
 23may start before fm_start, and the range covered by the last returned
 24extent may end after fm_length. All offsets and lengths are in bytes.
 25
 26Certain flags to modify the way in which mappings are looked up can be
 27set in fm_flags. If the kernel doesn't understand some particular
 28flags, it will return EBADR and the contents of fm_flags will contain
 29the set of flags which caused the error. If the kernel is compatible
 30with all flags passed, the contents of fm_flags will be unmodified.
 31It is up to userspace to determine whether rejection of a particular
 32flag is fatal to its operation. This scheme is intended to allow the
 33fiemap interface to grow in the future but without losing
 34compatibility with old software.
 35
 36fm_extent_count specifies the number of elements in the fm_extents[] array
 37that can be used to return extents.  If fm_extent_count is zero, then the
 38fm_extents[] array is ignored (no extents will be returned), and the
 39fm_mapped_extents count will hold the number of extents needed in
 40fm_extents[] to hold the file's current mapping.  Note that there is
 41nothing to prevent the file from changing between calls to FIEMAP.
 42
 43The following flags can be set in fm_flags:
 44
 45FIEMAP_FLAG_SYNC
 46  If this flag is set, the kernel will sync the file before mapping extents.
 47
 48FIEMAP_FLAG_XATTR
 49  If this flag is set, the extents returned will describe the inodes
 50  extended attribute lookup tree, instead of its data tree.
 51
 52FIEMAP_FLAG_CACHE
 53  This flag requests caching of the extents.
 54
 55Extent Mapping
 56--------------
 57
 58Extent information is returned within the embedded fm_extents array
 59which userspace must allocate along with the fiemap structure. The
 60number of elements in the fiemap_extents[] array should be passed via
 61fm_extent_count. The number of extents mapped by kernel will be
 62returned via fm_mapped_extents. If the number of fiemap_extents
 63allocated is less than would be required to map the requested range,
 64the maximum number of extents that can be mapped in the fm_extent[]
 65array will be returned and fm_mapped_extents will be equal to
 66fm_extent_count. In that case, the last extent in the array will not
 67complete the requested range and will not have the FIEMAP_EXTENT_LAST
 68flag set (see the next section on extent flags).
 69
 70Each extent is described by a single fiemap_extent structure as
 71returned in fm_extents:
 72
 73.. kernel-doc:: include/uapi/linux/fiemap.h
 74    :identifiers: fiemap_extent
 75
 76All offsets and lengths are in bytes and mirror those on disk.  It is valid
 77for an extents logical offset to start before the request or its logical
 78length to extend past the request.  Unless FIEMAP_EXTENT_NOT_ALIGNED is
 79returned, fe_logical, fe_physical, and fe_length will be aligned to the
 80block size of the file system.  With the exception of extents flagged as
 81FIEMAP_EXTENT_MERGED, adjacent extents will not be merged.
 82
 83The fe_flags field contains flags which describe the extent returned.
 84A special flag, FIEMAP_EXTENT_LAST is always set on the last extent in
 85the file so that the process making fiemap calls can determine when no
 86more extents are available, without having to call the ioctl again.
 87
 88Some flags are intentionally vague and will always be set in the
 89presence of other more specific flags. This way a program looking for
 90a general property does not have to know all existing and future flags
 91which imply that property.
 92
 93For example, if FIEMAP_EXTENT_DATA_INLINE or FIEMAP_EXTENT_DATA_TAIL
 94are set, FIEMAP_EXTENT_NOT_ALIGNED will also be set. A program looking
 95for inline or tail-packed data can key on the specific flag. Software
 96which simply cares not to try operating on non-aligned extents
 97however, can just key on FIEMAP_EXTENT_NOT_ALIGNED, and not have to
 98worry about all present and future flags which might imply unaligned
 99data. Note that the opposite is not true - it would be valid for
100FIEMAP_EXTENT_NOT_ALIGNED to appear alone.
101
102FIEMAP_EXTENT_LAST
103  This is generally the last extent in the file. A mapping attempt past
104  this extent may return nothing. Some implementations set this flag to
105  indicate this extent is the last one in the range queried by the user
106  (via fiemap->fm_length).
107
108FIEMAP_EXTENT_UNKNOWN
109  The location of this extent is currently unknown. This may indicate
110  the data is stored on an inaccessible volume or that no storage has
111  been allocated for the file yet.
112
113FIEMAP_EXTENT_DELALLOC
114  This will also set FIEMAP_EXTENT_UNKNOWN.
115
116  Delayed allocation - while there is data for this extent, its
117  physical location has not been allocated yet.
118
119FIEMAP_EXTENT_ENCODED
120  This extent does not consist of plain filesystem blocks but is
121  encoded (e.g. encrypted or compressed).  Reading the data in this
122  extent via I/O to the block device will have undefined results.
123
124Note that it is *always* undefined to try to update the data
125in-place by writing to the indicated location without the
126assistance of the filesystem, or to access the data using the
127information returned by the FIEMAP interface while the filesystem
128is mounted.  In other words, user applications may only read the
129extent data via I/O to the block device while the filesystem is
130unmounted, and then only if the FIEMAP_EXTENT_ENCODED flag is
131clear; user applications must not try reading or writing to the
132filesystem via the block device under any other circumstances.
133
134FIEMAP_EXTENT_DATA_ENCRYPTED
135  This will also set FIEMAP_EXTENT_ENCODED
136  The data in this extent has been encrypted by the file system.
137
138FIEMAP_EXTENT_NOT_ALIGNED
139  Extent offsets and length are not guaranteed to be block aligned.
140
141FIEMAP_EXTENT_DATA_INLINE
142  This will also set FIEMAP_EXTENT_NOT_ALIGNED
143  Data is located within a meta data block.
144
145FIEMAP_EXTENT_DATA_TAIL
146  This will also set FIEMAP_EXTENT_NOT_ALIGNED
147  Data is packed into a block with data from other files.
148
149FIEMAP_EXTENT_UNWRITTEN
150  Unwritten extent - the extent is allocated but its data has not been
151  initialized.  This indicates the extent's data will be all zero if read
152  through the filesystem but the contents are undefined if read directly from
153  the device.
154
155FIEMAP_EXTENT_MERGED
156  This will be set when a file does not support extents, i.e., it uses a block
157  based addressing scheme.  Since returning an extent for each block back to
158  userspace would be highly inefficient, the kernel will try to merge most
159  adjacent blocks into 'extents'.
160
161FIEMAP_EXTENT_SHARED
162  This flag is set to request that space be shared with other files.
163
164VFS -> File System Implementation
165---------------------------------
166
167File systems wishing to support fiemap must implement a ->fiemap callback on
168their inode_operations structure. The fs ->fiemap call is responsible for
169defining its set of supported fiemap flags, and calling a helper function on
170each discovered extent::
171
172  struct inode_operations {
173       ...
174
175       int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start,
176                     u64 len);
177
178->fiemap is passed struct fiemap_extent_info which describes the
179fiemap request:
180
181.. kernel-doc:: include/linux/fiemap.h
182    :identifiers: fiemap_extent_info
183
184It is intended that the file system should not need to access any of this
185structure directly. Filesystem handlers should be tolerant to signals and return
186EINTR once fatal signal received.
187
188
189Flag checking should be done at the beginning of the ->fiemap callback via the
190fiemap_prep() helper::
191
192  int fiemap_prep(struct inode *inode, struct fiemap_extent_info *fieinfo,
193		  u64 start, u64 *len, u32 supported_flags);
194
195The struct fieinfo should be passed in as received from ioctl_fiemap(). The
196set of fiemap flags which the fs understands should be passed via fs_flags. If
197fiemap_prep finds invalid user flags, it will place the bad values in
198fieinfo->fi_flags and return -EBADR. If the file system gets -EBADR, from
199fiemap_prep(), it should immediately exit, returning that error back to
200ioctl_fiemap().  Additionally the range is validate against the supported
201maximum file size.
202
203
204For each extent in the request range, the file system should call
205the helper function, fiemap_fill_next_extent()::
206
207  int fiemap_fill_next_extent(struct fiemap_extent_info *info, u64 logical,
208			      u64 phys, u64 len, u32 flags, u32 dev);
209
210fiemap_fill_next_extent() will use the passed values to populate the
211next free extent in the fm_extents array. 'General' extent flags will
212automatically be set from specific flags on behalf of the calling file
213system so that the userspace API is not broken.
214
215fiemap_fill_next_extent() returns 0 on success, and 1 when the
216user-supplied fm_extents array is full. If an error is encountered
217while copying the extent to user memory, -EFAULT will be returned.