LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

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 2017-05-28 15:36:50 +02:00
parent f0efd47a49
commit 194721a4cf
1 changed files with 53 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
man2/ioctl_getfsmap.2
View File

@ -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_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_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,13 +81,13 @@ 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 bit mask passed to the kernel to alter the output.
There are no flags defined, so callers must set this value to zero.
No flags are currently defined, so the caller must set this value to zero.
.PP
The
.I fmh_oflags
@ -96,9 +97,8 @@ If
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,12 +196,10 @@ 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
@ -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
@ -328,14 +322,15 @@ Block bitmap.
.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.
.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)