mirror of https://github.com/mkerrisk/man-pages
376 lines
9.8 KiB
Groff
376 lines
9.8 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 2017-02-10 "Linux" "Linux Programmer's Manual"
|
||
|
.SH NAME
|
||
|
ioctl_getfsmap \- retrieve the physical layout of the filesystem
|
||
|
.SH SYNOPSIS
|
||
|
.br
|
||
|
.B #include <sys/ioctl.h>
|
||
|
.br
|
||
|
.B #include <linux/fs.h>
|
||
|
.br
|
||
|
.B #include <linux/fsmap.h>
|
||
|
.sp
|
||
|
.BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
|
||
|
.SH DESCRIPTION
|
||
|
This
|
||
|
.BR ioctl (2)
|
||
|
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 ioctl should be a pointer to a single
|
||
|
.BR "struct fsmap_head" ":"
|
||
|
.in +4n
|
||
|
.nf
|
||
|
|
||
|
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 */
|
||
|
};
|
||
|
|
||
|
.fi
|
||
|
.in
|
||
|
The two
|
||
|
.I fmh_keys
|
||
|
array elements specify the lowest and highest reverse-mapping
|
||
|
keys, respectively, for which userspace 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
|
||
|
.PP
|
||
|
The
|
||
|
.I fmh_iflags
|
||
|
field is a bitmask passed to the kernel to alter the output.
|
||
|
There are no flags defined, so callers must set this value to zero.
|
||
|
|
||
|
.PP
|
||
|
The
|
||
|
.I fmh_oflags
|
||
|
field is a bitmask 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
|
||
|
.B 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
|
||
|
.PP
|
||
|
The two key records in
|
||
|
.B 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 36KiB on disk.
|
||
|
If the high key is set to (8:0, 1048576, 0, 0, 0), only records below 1MiB will
|
||
|
be returned.
|
||
|
The format of
|
||
|
.B fmr_device
|
||
|
in the keys must match the format of the same field in the output records,
|
||
|
as defined below.
|
||
|
By convention, the field
|
||
|
.B fsmap_head.fmh_keys[0]
|
||
|
must contain the low key and
|
||
|
.B fsmap_head.fmh_keys[1]
|
||
|
must contain the high key for the request.
|
||
|
.PP
|
||
|
For convenience, if
|
||
|
.B 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
|
||
|
.B fsmap_head.fmh_recs[fsmap_head.fmh_entries - 1]
|
||
|
into the low key.
|
||
|
The function
|
||
|
.B fsmap_advance
|
||
|
provides this functionality.
|
||
|
|
||
|
.SS Fields of struct fsmap
|
||
|
.PP
|
||
|
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
|
||
|
.B 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 bitmask 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 filesystem.
|
||
|
.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
|
||
|
|
||
|
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
|
||
|
|
||
|
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 bitmap.
|
||
|
.TP
|
||
|
.B EXT4_FMR_OWN_INOBM
|
||
|
Inode bitmap.
|
||
|
.RE
|
||
|
|
||
|
.SH RETURN VALUE
|
||
|
On error, \-1 is returned, and
|
||
|
.I errno
|
||
|
is set to indicate the error.
|
||
|
.PP
|
||
|
.SH ERRORS
|
||
|
Error codes can be one of, but are not limited to, the following:
|
||
|
.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 non-zero value
|
||
|
was passed in one of the fields that must be zero.
|
||
|
.TP
|
||
|
.B EFAULT
|
||
|
The pointer passed in was not mapped to a valid memory address.
|
||
|
.TP
|
||
|
.B EBADF
|
||
|
.IR fd
|
||
|
is not open for reading.
|
||
|
.TP
|
||
|
.B EOPNOTSUPP
|
||
|
The filesystem does not support this command.
|
||
|
.TP
|
||
|
.B EUCLEAN
|
||
|
The filesystem metadata is corrupt and needs repair.
|
||
|
.TP
|
||
|
.B EBADMSG
|
||
|
The filesystem has detected a checksum error in the metadata.
|
||
|
.TP
|
||
|
.B ENOMEM
|
||
|
Insufficient memory to process the request.
|
||
|
|
||
|
.SH EXAMPLE
|
||
|
.TP
|
||
|
Please see io/fsmap.c in the xfsprogs distribution for a sample program.
|
||
|
|
||
|
.SH CONFORMING TO
|
||
|
This API is Linux-specific.
|
||
|
Not all filesystems support it.
|
||
|
.fi
|
||
|
.in
|
||
|
.SH SEE ALSO
|
||
|
.BR ioctl (2)
|