IOCTL_GETFSMAP(2)         (2020-06-09)          IOCTL_GETFSMAP(2)

     NAME
          ioctl_getfsmap - retrieve the physical layout of the
          filesystem

     SYNOPSIS
          #include <sys/ioctl.h>
          #include <linux/fs.h>
          #include <linux/fsmap.h>

          int ioctl(int fd, FS_IOC_GETFSMAP, struct fsmap_head * arg);

     DESCRIPTION
          This ioctl(2) operation retrieves physical extent mappings
          for a filesystem.  This information can be used to discover
          which files are mapped to a physical block, examine free
          space, or find known bad blocks, among other things.

          The sole argument to this operation should be a pointer to a
          single struct fsmap_head:

              struct fsmap {
                  __u32 fmr_device;      /* Device ID */
                  __u32 fmr_flags;       /* Mapping flags */
                  __u64 fmr_physical;    /* Device offset of segment */
                  __u64 fmr_owner;       /* Owner ID */
                  __u64 fmr_offset;      /* File offset of segment */
                  __u64 fmr_length;      /* Length of segment */
                  __u64 fmr_reserved[3]; /* Must be zero */
              };

              struct fsmap_head {
                  __u32 fmh_iflags;       /* Control flags */
                  __u32 fmh_oflags;       /* Output flags */
                  __u32 fmh_count;        /* # of entries in array incl. input */
                  __u32 fmh_entries;      /* # of entries filled in (output) */
                  __u64 fmh_reserved[6];  /* Must be zero */

                  struct fsmap fmh_keys[2];  /* Low and high keys for
                                                the mapping search */
                  struct fsmap fmh_recs[];   /* Returned records */
              };

          The two fmh_keys array elements specify the lowest and high-
          est reverse-mapping key for which the application would like
          physical mapping information.  A reverse mapping key con-
          sists of the tuple (device, block, owner, offset).  The
          owner and offset fields are part of the key because some
          filesystems support sharing physical blocks between multiple
          files and therefore may return multiple mappings for a given
          physical block.

     Page 1                        Linux             (printed 5/24/22)

     IOCTL_GETFSMAP(2)         (2020-06-09)          IOCTL_GETFSMAP(2)

          Filesystem mappings are copied into the fmh_recs array,
          which immediately follows the header data.

        Fields of struct fsmap_head
          The fmh_iflags field is a bit mask passed to the kernel to
          alter the output.  No flags are currently defined, so the
          caller must set this value to zero.

          The fmh_oflags field is a bit mask of flags set by the ker-
          nel concerning the returned mappings.  If FMH_OF_DEV_T is
          set, then the fmr_device field represents a dev_t structure
          containing the major and minor numbers of the block device.

          The fmh_count field contains the number of elements in the
          array being passed to the kernel.  If this value is 0,
          fmh_entries will be set to the number of records that would
          have been returned had the array been large enough; no map-
          ping information will be returned.

          The fmh_entries field contains the number of elements in the
          fmh_recs array that contain useful information.

          The fmh_reserved fields must be set to zero.

        Keys
          The two key records in fsmap_head.fmh_keys specify the low-
          est and highest extent records in the keyspace that the
          caller wants returned.  A filesystem that can share blocks
          between files likely requires the tuple (device, physical,
          owner to uniquely index any filesystem mapping record.
          Classic non-sharing filesystems might be able to identify
          any record with only (device, physical, flags For example,
          if the low key is set to (8:0, 36864, 0, 0, 0), the filesys-
          tem will only return records for extents starting at or
          above 36 KiB on disk.  If the high key is set to (8:0,
          1048576, 0, 0, 0), only records below 1 MiB will be
          returned.  The format of fmr_device in the keys must match
          the format of the same field in the output records, as
          defined below.  By convention, the field
          fsmap_head.fmh_keys[0] must contain the low key and
          fsmap_head.fmh_keys[1] must contain the high key for the
          request.

          For convenience, if fmr_length is set in the low key, it
          will be added to fmr_block or fmr_offset as appropriate.
          The caller can take advantage of this subtlety to set up
          subsequent calls by copying
          fsmap_head.fmh_recs[fsmap_head.fmh_entries - 1] into the low
          key.  The function fsmap_advance (defined in linux/fsmap.h)
          provides this functionality.

        Fields of struct fsmap

     Page 2                        Linux             (printed 5/24/22)

     IOCTL_GETFSMAP(2)         (2020-06-09)          IOCTL_GETFSMAP(2)

          The fmr_device field uniquely identifies the underlying
          storage device.  If the FMH_OF_DEV_T flag is set in the
          header's fmh_oflags field, this field contains a dev_t from
          which major and minor numbers can be extracted.  If the flag
          is not set, this field contains a value that must be unique
          for each unique storage device.

          The fmr_physical field contains the disk address of the
          extent in bytes.

          The fmr_owner field contains the owner of the extent.  This
          is an inode number unless FMR_OF_SPECIAL_OWNER is set in the
          fmr_flags field, in which case the value is determined by
          the filesystem.  See the section below about owner values
          for more details.

          The fmr_offset field contains the logical address in the
          mapping record in bytes.  This field has no meaning if the
          FMR_OF_SPECIAL_OWNER or FMR_OF_EXTENT_MAP flags are set in
          fmr_flags.

          The fmr_length field contains the length of the extent in
          bytes.

          The fmr_flags field is a bit mask of extent state flags.
          The bits are:

              FMR_OF_PREALLOC
                   The extent is allocated but not yet written.

              FMR_OF_ATTR_FORK
                   This extent contains extended attribute data.

              FMR_OF_EXTENT_MAP
                   This extent contains extent map information for the
                   owner.

              FMR_OF_SHARED
                   Parts of this extent may be shared.

              FMR_OF_SPECIAL_OWNER
                   The fmr_owner field contains a special value
                   instead of an inode number.

              FMR_OF_LAST
                   This is the last record in the data set.

          The fmr_reserved field will be set to zero.

        Owner values
          Generally, the value of the fmr_owner field for non-metadata
          extents should be an inode number.  However, filesystems are

     Page 3                        Linux             (printed 5/24/22)

     IOCTL_GETFSMAP(2)         (2020-06-09)          IOCTL_GETFSMAP(2)

          under no obligation to report inode numbers; they may
          instead report FMR_OWN_UNKNOWN if the inode number cannot
          easily be retrieved, if the caller lacks sufficient privi-
          lege, if the filesystem does not support stable inode num-
          bers, or for any other reason.  If a filesystem wishes to
          condition the reporting of inode numbers based on process
          capabilities, it is strongly urged that the CAP_SYS_ADMIN
          capability be used for this purpose.

     tems:
          The following special owner values are generic to all filesys-

              FMR_OWN_FREE
                   Free space.

              FMR_OWN_UNKNOWN
                   This extent is in use but its owner is not known or
                   not easily retrieved.

              FMR_OWN_METADATA
                   This extent is filesystem metadata.

          XFS can return the following special owner values:

              XFS_FMR_OWN_FREE
                   Free space.

              XFS_FMR_OWN_UNKNOWN
                   This extent is in use but its owner is not known or
                   not easily retrieved.

              XFS_FMR_OWN_FS
                   Static filesystem metadata which exists at a fixed
                   address.  These are the AG superblock, the AGF, the
                   AGFL, and the AGI headers.

              XFS_FMR_OWN_LOG
                   The filesystem journal.

              XFS_FMR_OWN_AG
                   Allocation group metadata, such as the free space
                   btrees and the reverse mapping btrees.

              XFS_FMR_OWN_INOBT
                   The inode and free inode btrees.

              XFS_FMR_OWN_INODES
                   Inode records.

              XFS_FMR_OWN_REFC
                   Reference count information.

     Page 4                        Linux             (printed 5/24/22)

     IOCTL_GETFSMAP(2)         (2020-06-09)          IOCTL_GETFSMAP(2)

              XFS_FMR_OWN_COW
                   This extent is being used to stage a copy-on-write.

              XFS_FMR_OWN_DEFECTIVE:
                   This extent has been marked defective either by the
                   filesystem or the underlying device.

          ext4 can return the following special owner values:

              EXT4_FMR_OWN_FREE
                   Free space.

              EXT4_FMR_OWN_UNKNOWN
                   This extent is in use but its owner is not known or
                   not easily retrieved.

              EXT4_FMR_OWN_FS
                   Static filesystem metadata which exists at a fixed
                   address.  This is the superblock and the group
                   descriptors.

              EXT4_FMR_OWN_LOG
                   The filesystem journal.

              EXT4_FMR_OWN_INODES
                   Inode records.

              EXT4_FMR_OWN_BLKBM
                   Block bit map.

              EXT4_FMR_OWN_INOBM
                   Inode bit map.

     RETURN VALUE
          On error, -1 is returned, and errno is set to indicate the
          error.

     ERRORS
          The error placed in errno can be one of, but is not limited
          to, the following:

          EBADF
               fd is not open for reading.

          EBADMSG
               The filesystem has detected a checksum error in the
               metadata.

          EFAULT
               The pointer passed in was not mapped to a valid memory
               address.

     Page 5                        Linux             (printed 5/24/22)

     IOCTL_GETFSMAP(2)         (2020-06-09)          IOCTL_GETFSMAP(2)

          EINVAL
               The array is not long enough, the keys do not point to
               a valid part of the filesystem, the low key points to a
               higher point in the filesystem's physical storage
               address space than the high key, or a nonzero value was
               passed in one of the fields that must be zero.

          ENOMEM
               Insufficient memory to process the request.

          EOPNOTSUPP
               The filesystem does not support this command.

          EUCLEAN
               The filesystem metadata is corrupt and needs repair.

     VERSIONS
          The FS_IOC_GETFSMAP operation first appeared in Linux 4.12.

     CONFORMING TO
          This API is Linux-specific.  Not all filesystems support it.

     EXAMPLES
          See io/fsmap.c in the xfsprogs distribution for a sample
          program.

     SEE ALSO
          ioctl(2)

     COLOPHON
          This page is part of release 5.10 of the Linux man-pages
          project.  A description of the project, information about
          reporting bugs, and the latest version of this page, can be
          found at https://www.kernel.org/doc/man-pages/.

     Page 6                        Linux             (printed 5/24/22)