docs: filesystems: convert fiemap.txt to ReST

.. SPDX-License-Identifier: GPL-2.0

============

Fiemap Ioctl

============

Request Basics

--------------

A fiemap request is encoded within struct fiemap:

A fiemap request is encoded within struct fiemap::

  struct fiemap {

	__u64	fm_start;	 /* logical offset (inclusive) at

The following flags can be set in fm_flags:

* FIEMAP_FLAG_SYNC

FIEMAP_FLAG_SYNC

  If this flag is set, the kernel will sync the file before mapping extents.

* FIEMAP_FLAG_XATTR

FIEMAP_FLAG_XATTR

  If this flag is set, the extents returned will describe the inodes

  extended attribute lookup tree, instead of its data tree.

flag set (see the next section on extent flags).

Each extent is described by a single fiemap_extent structure as

returned in fm_extents.

returned in fm_extents::

    struct fiemap_extent {

	    __u64	fe_logical;  /* logical offset in bytes for the start of

data. Note that the opposite is not true - it would be valid for

FIEMAP_EXTENT_NOT_ALIGNED to appear alone.

* FIEMAP_EXTENT_LAST

FIEMAP_EXTENT_LAST

  This is generally the last extent in the file. A mapping attempt past

  this extent may return nothing. Some implementations set this flag to

  indicate this extent is the last one in the range queried by the user

  (via fiemap->fm_length).

* FIEMAP_EXTENT_UNKNOWN

FIEMAP_EXTENT_UNKNOWN

  The location of this extent is currently unknown. This may indicate

  the data is stored on an inaccessible volume or that no storage has

  been allocated for the file yet.

* FIEMAP_EXTENT_DELALLOC

  - This will also set FIEMAP_EXTENT_UNKNOWN.

FIEMAP_EXTENT_DELALLOC

  This will also set FIEMAP_EXTENT_UNKNOWN.

  Delayed allocation - while there is data for this extent, its

  physical location has not been allocated yet.

* FIEMAP_EXTENT_ENCODED

FIEMAP_EXTENT_ENCODED

  This extent does not consist of plain filesystem blocks but is

  encoded (e.g. encrypted or compressed).  Reading the data in this

  extent via I/O to the block device will have undefined results.

clear; user applications must not try reading or writing to the

filesystem via the block device under any other circumstances.

* FIEMAP_EXTENT_DATA_ENCRYPTED

  - This will also set FIEMAP_EXTENT_ENCODED

FIEMAP_EXTENT_DATA_ENCRYPTED

  This will also set FIEMAP_EXTENT_ENCODED

  The data in this extent has been encrypted by the file system.

* FIEMAP_EXTENT_NOT_ALIGNED

FIEMAP_EXTENT_NOT_ALIGNED

  Extent offsets and length are not guaranteed to be block aligned.

* FIEMAP_EXTENT_DATA_INLINE

FIEMAP_EXTENT_DATA_INLINE

  This will also set FIEMAP_EXTENT_NOT_ALIGNED

  Data is located within a meta data block.

* FIEMAP_EXTENT_DATA_TAIL

FIEMAP_EXTENT_DATA_TAIL

  This will also set FIEMAP_EXTENT_NOT_ALIGNED

  Data is packed into a block with data from other files.

* FIEMAP_EXTENT_UNWRITTEN

FIEMAP_EXTENT_UNWRITTEN

  Unwritten extent - the extent is allocated but its data has not been

  initialized.  This indicates the extent's data will be all zero if read

  through the filesystem but the contents are undefined if read directly from

  the device.

* FIEMAP_EXTENT_MERGED

FIEMAP_EXTENT_MERGED

  This will be set when a file does not support extents, i.e., it uses a block

  based addressing scheme.  Since returning an extent for each block back to

  userspace would be highly inefficient, the kernel will try to merge most

File systems wishing to support fiemap must implement a ->fiemap callback on

their inode_operations structure. The fs ->fiemap call is responsible for

defining its set of supported fiemap flags, and calling a helper function on

each discovered extent:

each discovered extent::

  struct inode_operations {

       ...

                     u64 len);

->fiemap is passed struct fiemap_extent_info which describes the

fiemap request:

fiemap request::

  struct fiemap_extent_info {

	unsigned int fi_flags;		/* Flags as passed from user */

Flag checking should be done at the beginning of the ->fiemap callback via the

fiemap_check_flags() helper:

fiemap_check_flags() helper::

  int fiemap_check_flags(struct fiemap_extent_info *fieinfo, u32 fs_flags);

For each extent in the request range, the file system should call

the helper function, fiemap_fill_next_extent():

the helper function, fiemap_fill_next_extent()::

  int fiemap_fill_next_extent(struct fiemap_extent_info *info, u64 logical,

			      u64 phys, u64 len, u32 flags, u32 dev);

   directory-locking

   devpts

   dnotify

   fiemap

   automount-support