Re: [PATCH v2] ioctl_getfsmap.2: document the GETFSMAP ioctl

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

On 05/18/2017 04:07 AM, Darrick J. Wong wrote:
> Document the new GETFSMAP ioctl that returns the physical layout of a
> (disk-based) filesystem.

Thanks, Darrick! Applied (with a few minor edits). (Currently sitting in
a local branch, just in case anyone sends review comments that need
integrating.)

Cheers,

Michael

> Signed-off-by: Darrick J. Wong <darrick.wong-QHcLZuEGTsvQT0dZR+AlfA@public.gmane.org>
> ---
> v2: emphasize that filesystems are not obligated to return inode numbers
> ---
>  man2/ioctl_getfsmap.2 |  375 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 375 insertions(+)
>  create mode 100644 man2/ioctl_getfsmap.2
> 
> diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2
> new file mode 100644
> index 0000000..b451950
> --- /dev/null
> +++ b/man2/ioctl_getfsmap.2
> @@ -0,0 +1,375 @@
> +.\" 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)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/