fiemap.rst 9.8 KB

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