.\" Copyright (c) 2017, Oracle.  All rights reserved.
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.TH IOCTL_GETFSMAP 2 2020-06-09 "Linux" "Linux Programmer's Manual"
.SH NAME
ioctl_getfsmap \- retrieve the physical layout of the filesystem
.SH SYNOPSIS
.B #include <sys/ioctl.h>
.br
.B #include <linux/fs.h>
.br
.B #include <linux/fsmap.h>
.PP
.BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
.SH DESCRIPTION
This
.BR 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.
.PP
The sole argument to this operation should be a pointer to a single
.IR "struct fsmap_head" ":"
.PP
.in +4n
.EX
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 */
};
.EE
.in
.PP
The two
.I 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.
.PP
Filesystem mappings are copied into the
.I fmh_recs
array, which immediately follows the header data.
.\"
.SS Fields of struct fsmap_head
The
.I 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.
.PP
The
.I fmh_oflags
field is a bit mask of flags set by the kernel concerning the returned mappings.
If
.B FMH_OF_DEV_T
is set, then the
.I fmr_device
field represents a
.I dev_t
structure containing the major and minor numbers of the block device.
.PP
The
.I fmh_count
field contains the number of elements in the array being passed to the
kernel.
If this value is 0,
.I 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.
.PP
The
.I fmh_entries
field contains the number of elements in the
.I fmh_recs
array that contain useful information.
.PP
The
.I fmh_reserved
fields must be set to zero.
.\"
.SS Keys
The two key records in
.I 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
.RI "(" "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
.RI "(" "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
.I fmr_device
in the keys must match the format of the same field in the output records,
as defined below.
By convention, the field
.I fsmap_head.fmh_keys[0]
must contain the low key and
.I fsmap_head.fmh_keys[1]
must contain the high key for the request.
.PP
For convenience, if
.I fmr_length
is set in the low key, it will be added to
.IR fmr_block " or " fmr_offset
as appropriate.
The caller can take advantage of this subtlety to set up subsequent calls
by copying
.I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1]
into the low key.
The function
.I fsmap_advance
(defined in
.IR linux/fsmap.h )
provides this functionality.
.\"
.SS Fields of struct fsmap
The
.I fmr_device
field uniquely identifies the underlying storage device.
If the
.B FMH_OF_DEV_T
flag is set in the header's
.I fmh_oflags
field, this field contains a
.I 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.
.PP
The
.I fmr_physical
field contains the disk address of the extent in bytes.
.PP
The
.I fmr_owner
field contains the owner of the extent.
This is an inode number unless
.B FMR_OF_SPECIAL_OWNER
is set in the
.I fmr_flags
field, in which case the value is determined by the filesystem.
See the section below about owner values for more details.
.PP
The
.I fmr_offset
field contains the logical address in the mapping record in bytes.
This field has no meaning if the
.BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP
flags are set in
.IR fmr_flags "."
.PP
The
.I fmr_length
field contains the length of the extent in bytes.
.PP
The
.I fmr_flags
field is a bit mask of extent state flags.
The bits are:
.RS 0.4i
.TP
.B FMR_OF_PREALLOC
The extent is allocated but not yet written.
.TP
.B FMR_OF_ATTR_FORK
This extent contains extended attribute data.
.TP
.B FMR_OF_EXTENT_MAP
This extent contains extent map information for the owner.
.TP
.B FMR_OF_SHARED
Parts of this extent may be shared.
.TP
.B FMR_OF_SPECIAL_OWNER
The
.I fmr_owner
field contains a special value instead of an inode number.
.TP
.B FMR_OF_LAST
This is the last record in the data set.
.RE
.PP
The
.I fmr_reserved
field will be set to zero.
.\"
.SS Owner values
Generally, the value of the
.I 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
.B 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
.B CAP_SYS_ADMIN
capability be used for this purpose.
.TP
The following special owner values are generic to all filesystems:
.RS 0.4i
.TP
.B FMR_OWN_FREE
Free space.
.TP
.B FMR_OWN_UNKNOWN
This extent is in use but its owner is not known or not easily retrieved.
.TP
.B FMR_OWN_METADATA
This extent is filesystem metadata.
.RE
.PP
XFS can return the following special owner values:
.RS 0.4i
.TP
.B XFS_FMR_OWN_FREE
Free space.
.TP
.B XFS_FMR_OWN_UNKNOWN
This extent is in use but its owner is not known or not easily retrieved.
.TP
.B 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.
.TP
.B XFS_FMR_OWN_LOG
The filesystem journal.
.TP
.B XFS_FMR_OWN_AG
Allocation group metadata, such as the free space btrees and the
reverse mapping btrees.
.TP
.B XFS_FMR_OWN_INOBT
The inode and free inode btrees.
.TP
.B XFS_FMR_OWN_INODES
Inode records.
.TP
.B XFS_FMR_OWN_REFC
Reference count information.
.TP
.B XFS_FMR_OWN_COW
This extent is being used to stage a copy-on-write.
.TP
.B XFS_FMR_OWN_DEFECTIVE:
This extent has been marked defective either by the filesystem or the
underlying device.
.RE
.PP
ext4 can return the following special owner values:
.RS 0.4i
.TP
.B EXT4_FMR_OWN_FREE
Free space.
.TP
.B EXT4_FMR_OWN_UNKNOWN
This extent is in use but its owner is not known or not easily retrieved.
.TP
.B EXT4_FMR_OWN_FS
Static filesystem metadata which exists at a fixed address.
This is the superblock and the group descriptors.
.TP
.B EXT4_FMR_OWN_LOG
The filesystem journal.
.TP
.B EXT4_FMR_OWN_INODES
Inode records.
.TP
.B EXT4_FMR_OWN_BLKBM
Block bit map.
.TP
.B EXT4_FMR_OWN_INOBM
Inode bit map.
.RE
.SH RETURN VALUE
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
The error placed in
.I errno
can be one of, but is not limited to, the following:
.TP
.B EBADF
.IR fd
is not open for reading.
.TP
.B EBADMSG
The filesystem has detected a checksum error in the metadata.
.TP
.B EFAULT
The pointer passed in was not mapped to a valid memory address.
.TP
.B 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.
.TP
.B ENOMEM
Insufficient memory to process the request.
.TP
.B EOPNOTSUPP
The filesystem does not support this command.
.TP
.B EUCLEAN
The filesystem metadata is corrupt and needs repair.
.SH VERSIONS
The
.B FS_IOC_GETFSMAP
operation first appeared in Linux 4.12.
.SH CONFORMING TO
This API is Linux-specific.
Not all filesystems support it.
.SH EXAMPLES
See
.I io/fsmap.c
in the
.I xfsprogs
distribution for a sample program.
.SH SEE ALSO
.BR ioctl (2)
.SH COLOPHON
This page is part of release 5.10 of the Linux
.I 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/.