# ioctl_fsmap

## NAME



           ioctl_fsmap, FS_IOC_GETFSMAP - retrieve the physical layout of the
           filesystem
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <linux/fsmap.h>  **/* Definition of **FS_IOC_GETFSMAP** ,
                                        **FM?_OF_*** , and ***FMR_OWN_*** constants */
           **#include <sys/ioctl.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 highest
           reverse-mapping key for which the application would like physical
           mapping information.  A reverse mapping key consists 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.
    
           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 kernel
           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 mapping 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 lowest 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_ , _offset_ , _flags_) 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 filesystem 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 operation.
    
           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**
           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 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 privilege, if the filesystem does not
           support stable inode numbers, 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.
    
           The following special owner values are generic to all filesystems:
    
               **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.
    
               **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.
    
           **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 operation.
    
           **EOPNOTSUPP**
                  The filesystem does not support this operation.
    
           **EUCLEAN**
                  The filesystem metadata is corrupt and needs repair.
    


## STANDARDS



           Linux.
    
           Not all filesystems support it.
    


## EXAMPLES



           See _io/fsmap.c_ in the _xfsprogs_ distribution for a sample program.
    


* * *