mirror of https://github.com/mkerrisk/man-pages
ioctl_getfsmap.2: Minor fixes to Darrick Wong's page
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
f0efd47a49
commit
194721a4cf
|
|
@ -20,7 +20,7 @@
|
|||
.\" 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"
|
||||
.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
|
||||
|
|
@ -35,34 +35,35 @@ ioctl_getfsmap \- retrieve the physical layout of the filesystem
|
|||
.SH DESCRIPTION
|
||||
This
|
||||
.BR ioctl (2)
|
||||
retrieves physical extent mappings for a filesystem.
|
||||
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 ioctl should be a pointer to a single
|
||||
.BR "struct fsmap_head" ":"
|
||||
.PP
|
||||
The sole argument to this operation should be a pointer to a single
|
||||
.IR "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 */
|
||||
__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 */
|
||||
__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 */
|
||||
struct fsmap fmh_keys[2]; /* Low and high keys for
|
||||
the mapping search */
|
||||
struct fsmap fmh_recs[]; /* Returned records */
|
||||
};
|
||||
|
||||
.fi
|
||||
|
|
@ -70,7 +71,7 @@ struct fsmap_head {
|
|||
The two
|
||||
.I fmh_keys
|
||||
array elements specify the lowest and highest reverse-mapping
|
||||
keys, respectively, for which userspace would like physical 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
|
||||
|
|
@ -80,25 +81,24 @@ therefore may return multiple mappings for a given physical block.
|
|||
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.
|
||||
|
||||
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 bitmask of flags set by the kernel concerning the returned mappings.
|
||||
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
|
||||
.B dev_t
|
||||
.I dev_t
|
||||
structure containing the major and minor numbers of the block device.
|
||||
|
||||
.PP
|
||||
The
|
||||
.I fmh_count
|
||||
|
|
@ -109,23 +109,21 @@ If this value is 0,
|
|||
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
|
||||
.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
|
||||
|
|
@ -138,28 +136,30 @@ 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
|
||||
.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
|
||||
.B fsmap_head.fmh_keys[0]
|
||||
.I fsmap_head.fmh_keys[0]
|
||||
must contain the low key and
|
||||
.B fsmap_head.fmh_keys[1]
|
||||
.I fsmap_head.fmh_keys[1]
|
||||
must contain the high key for the request.
|
||||
.PP
|
||||
For convenience, if
|
||||
.B fmr_length
|
||||
.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
|
||||
.B fsmap_head.fmh_recs[fsmap_head.fmh_entries - 1]
|
||||
.I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1]
|
||||
into the low key.
|
||||
The function
|
||||
.B fsmap_advance
|
||||
.I fsmap_advance
|
||||
(defined in
|
||||
.IR linux/fsmap.h )
|
||||
provides this functionality.
|
||||
|
||||
.\"
|
||||
.SS Fields of struct fsmap
|
||||
.PP
|
||||
The
|
||||
|
|
@ -170,16 +170,14 @@ If the
|
|||
flag is set in the header's
|
||||
.I fmh_oflags
|
||||
field, this field contains a
|
||||
.B dev_t
|
||||
.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
|
||||
|
|
@ -190,7 +188,6 @@ 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
|
||||
|
|
@ -199,16 +196,14 @@ 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.
|
||||
field is a bit mask of extent state flags.
|
||||
The bits are:
|
||||
.RS 0.4i
|
||||
.TP
|
||||
|
|
@ -232,13 +227,12 @@ field contains a special value instead of an inode number.
|
|||
.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
|
||||
.\"
|
||||
.SS Owner values
|
||||
Generally, the value of the
|
||||
.I fmr_owner
|
||||
field for non-metadata extents should be an inode number.
|
||||
|
|
@ -265,7 +259,7 @@ This extent is in use but its owner is not known or not easily retrieved.
|
|||
.B FMR_OWN_METADATA
|
||||
This extent is filesystem metadata.
|
||||
.RE
|
||||
|
||||
.PP
|
||||
XFS can return the following special owner values:
|
||||
.RS 0.4i
|
||||
.TP
|
||||
|
|
@ -302,7 +296,7 @@ This extent is being used to stage a copy-on-write.
|
|||
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
|
||||
|
|
@ -323,19 +317,20 @@ The filesystem journal.
|
|||
Inode records.
|
||||
.TP
|
||||
.B EXT4_FMR_OWN_BLKBM
|
||||
Block bitmap.
|
||||
Block bit map.
|
||||
.TP
|
||||
.B EXT4_FMR_OWN_INOBM
|
||||
Inode bitmap.
|
||||
Inode bit map.
|
||||
.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:
|
||||
The error placed in
|
||||
.I errno
|
||||
can be one of, but is not limited to, the following:
|
||||
.TP
|
||||
.B EINVAL
|
||||
The array is not long enough, the keys do not point to a valid part of
|
||||
|
|
@ -361,15 +356,14 @@ 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.
|
||||
|
||||
See
|
||||
.I io/fsmap.c
|
||||
in the
|
||||
.I 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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue