mirror of https://github.com/mkerrisk/man-pages
369 lines
10 KiB
Groff
369 lines
10 KiB
Groff
.\" 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)
|