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

112
man2/ioctl_getfsmap.2
View File

@ -20,7 +20,7 @@
.\" License along with this manual; if not, see .\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>. .\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END .\" %%%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 .SH NAME
ioctl_getfsmap \- retrieve the physical layout of the filesystem ioctl_getfsmap \- retrieve the physical layout of the filesystem
.SH SYNOPSIS .SH SYNOPSIS
@ -35,34 +35,35 @@ ioctl_getfsmap \- retrieve the physical layout of the filesystem
.SH DESCRIPTION .SH DESCRIPTION
This This
.BR ioctl (2) .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 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. block, examine free space, or find known bad blocks, among other things.
.PP
The sole argument to this ioctl should be a pointer to a single The sole argument to this operation should be a pointer to a single
.BR "struct fsmap_head" ":" .IR "struct fsmap_head" ":"
.in +4n .in +4n
.nf .nf
struct fsmap { struct fsmap {
__u32 fmr_device; /* device id */ __u32 fmr_device; /* Device ID */
__u32 fmr_flags; /* mapping flags */ __u32 fmr_flags; /* Mapping flags */
__u64 fmr_physical; /* device offset of segment */ __u64 fmr_physical; /* Device offset of segment */
__u64 fmr_owner; /* owner id */ __u64 fmr_owner; /* Owner ID */
__u64 fmr_offset; /* file offset of segment */ __u64 fmr_offset; /* File offset of segment */
__u64 fmr_length; /* length of segment */ __u64 fmr_length; /* Length of segment */
__u64 fmr_reserved[3]; /* must be zero */ __u64 fmr_reserved[3]; /* Must be zero */
}; };
struct fsmap_head { struct fsmap_head {
__u32 fmh_iflags; /* control flags */ __u32 fmh_iflags; /* Control flags */
__u32 fmh_oflags; /* output flags */ __u32 fmh_oflags; /* Output flags */
__u32 fmh_count; /* # of entries in array incl. input */ __u32 fmh_count; /* # of entries in array incl. input */
__u32 fmh_entries; /* # of entries filled in (output). */ __u32 fmh_entries; /* # of entries filled in (output) */
__u64 fmh_reserved[6]; /* must be zero */ __u64 fmh_reserved[6]; /* Must be zero */
struct fsmap fmh_keys[2]; /* low and high keys for the mapping search */ struct fsmap fmh_keys[2]; /* Low and high keys for
struct fsmap fmh_recs[]; /* returned records */ the mapping search */
struct fsmap fmh_recs[]; /* Returned records */
}; };
.fi .fi
@ -70,7 +71,7 @@ struct fsmap_head {
The two The two
.I fmh_keys .I fmh_keys
array elements specify the lowest and highest reverse-mapping 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. information.
A reverse mapping key consists of the tuple (device, block, owner, offset). 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 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 Filesystem mappings are copied into the
.I fmh_recs .I fmh_recs
array, which immediately follows the header data. array, which immediately follows the header data.
.\"
.SS Fields of struct fsmap_head .SS Fields of struct fsmap_head
.PP .PP
The The
.I fmh_iflags .I fmh_iflags
field is a bitmask passed to the kernel to alter the output. 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 .PP
The The
.I fmh_oflags .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 If
.B FMH_OF_DEV_T .B FMH_OF_DEV_T
is set, then the is set, then the
.I fmr_device .I fmr_device
field represents a field represents a
.B dev_t .I dev_t
structure containing the major and minor numbers of the block device. structure containing the major and minor numbers of the block device.
.PP .PP
The The
.I fmh_count .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 will be set to the number of records that would have been returned had
the array been large enough; the array been large enough;
no mapping information will be returned. no mapping information will be returned.
.PP .PP
The The
.I fmh_entries .I fmh_entries
field contains the number of elements in the field contains the number of elements in the
.I fmh_recs .I fmh_recs
array that contain useful information. array that contain useful information.
.PP .PP
The The
.I fmh_reserved .I fmh_reserved
fields must be set to zero. fields must be set to zero.
.\"
.SS Keys .SS Keys
.PP .PP
The two key records in 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 specify the lowest and highest extent records in the keyspace that the caller
wants returned. wants returned.
A filesystem that can share blocks between files likely requires the tuple 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 If the high key is set to (8:0, 1048576, 0, 0, 0), only records below 1MiB will
be returned. be returned.
The format of The format of
.B fmr_device .I fmr_device
in the keys must match the format of the same field in the output records, in the keys must match the format of the same field in the output records,
as defined below. as defined below.
By convention, the field By convention, the field
.B fsmap_head.fmh_keys[0] .I fsmap_head.fmh_keys[0]
must contain the low key and 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. must contain the high key for the request.
.PP .PP
For convenience, if For convenience, if
.B fmr_length .I fmr_length
is set in the low key, it will be added to is set in the low key, it will be added to
.IR fmr_block " or " fmr_offset .IR fmr_block " or " fmr_offset
as appropriate. as appropriate.
The caller can take advantage of this subtlety to set up subsequent calls The caller can take advantage of this subtlety to set up subsequent calls
by copying 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. into the low key.
The function The function
.B fsmap_advance .I fsmap_advance
(defined in
.IR linux/fsmap.h )
provides this functionality. provides this functionality.
.\"
.SS Fields of struct fsmap .SS Fields of struct fsmap
.PP .PP
The The
@ -170,16 +170,14 @@ If the
flag is set in the header's flag is set in the header's
.I fmh_oflags .I fmh_oflags
field, this field contains a field, this field contains a
.B dev_t .I dev_t
from which major and minor numbers can be extracted. from which major and minor numbers can be extracted.
If the flag is not set, this field contains a value that must be unique If the flag is not set, this field contains a value that must be unique
for each unique storage device. for each unique storage device.
.PP .PP
The The
.I fmr_physical .I fmr_physical
field contains the disk address of the extent in bytes. field contains the disk address of the extent in bytes.
.PP .PP
The The
.I fmr_owner .I fmr_owner
@ -190,7 +188,6 @@ is set in the
.I fmr_flags .I fmr_flags
field, in which case the value is determined by the filesystem. field, in which case the value is determined by the filesystem.
See the section below about owner values for more details. See the section below about owner values for more details.
.PP .PP
The The
.I fmr_offset .I fmr_offset
@ -199,16 +196,14 @@ This field has no meaning if the
.BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP .BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP
flags are set in flags are set in
.IR fmr_flags "." .IR fmr_flags "."
.PP .PP
The The
.I fmr_length .I fmr_length
field contains the length of the extent in bytes. field contains the length of the extent in bytes.
.PP .PP
The The
.I fmr_flags .I fmr_flags
field is a bitmask of extent state flags. field is a bit mask of extent state flags.
The bits are: The bits are:
.RS 0.4i .RS 0.4i
.TP .TP
@ -232,13 +227,12 @@ field contains a special value instead of an inode number.
.B FMR_OF_LAST .B FMR_OF_LAST
This is the last record in the filesystem. This is the last record in the filesystem.
.RE .RE
.PP .PP
The The
.I fmr_reserved .I fmr_reserved
field will be set to zero. field will be set to zero.
.\"
.SS Owner Values .SS Owner values
Generally, the value of the Generally, the value of the
.I fmr_owner .I fmr_owner
field for non-metadata extents should be an inode number. 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 .B FMR_OWN_METADATA
This extent is filesystem metadata. This extent is filesystem metadata.
.RE .RE
.PP
XFS can return the following special owner values: XFS can return the following special owner values:
.RS 0.4i .RS 0.4i
.TP .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 This extent has been marked defective either by the filesystem or the
underlying device. underlying device.
.RE .RE
.PP
ext4 can return the following special owner values: ext4 can return the following special owner values:
.RS 0.4i .RS 0.4i
.TP .TP
@ -323,19 +317,20 @@ The filesystem journal.
Inode records. Inode records.
.TP .TP
.B EXT4_FMR_OWN_BLKBM .B EXT4_FMR_OWN_BLKBM
Block bitmap. Block bit map.
.TP .TP
.B EXT4_FMR_OWN_INOBM .B EXT4_FMR_OWN_INOBM
Inode bitmap. Inode bit map.
.RE .RE
.SH RETURN VALUE .SH RETURN VALUE
On error, \-1 is returned, and On error, \-1 is returned, and
.I errno .I errno
is set to indicate the error. is set to indicate the error.
.PP .PP
.SH ERRORS .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 .TP
.B EINVAL .B EINVAL
The array is not long enough, the keys do not point to a valid part of 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 .TP
.B ENOMEM .B ENOMEM
Insufficient memory to process the request. Insufficient memory to process the request.
.SH EXAMPLE .SH EXAMPLE
.TP See
Please see io/fsmap.c in the xfsprogs distribution for a sample program. .I io/fsmap.c
in the
.I xfsprogs
distribution for a sample program.
.SH CONFORMING TO .SH CONFORMING TO
This API is Linux-specific. This API is Linux-specific.
Not all filesystems support it. Not all filesystems support it.
.fi
.in
.SH SEE ALSO .SH SEE ALSO
.BR ioctl (2) .BR ioctl (2)