Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 351 insertions, 0 deletions

diff --git a/man/man2/ioctl_getfsmap.2 b/man/man2/ioctl_getfsmap.2
new file mode 100644
index 0000000..e10134c
--- /dev/null
+++ b/man/man2/ioctl_getfsmap.2
@@ -0,0 +1,351 @@
+.\" Copyright (c) 2017, Oracle.  All rights reserved.
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.TH ioctl_getfsmap 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+ioctl_getfsmap \- retrieve the physical layout of the filesystem
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/fsmap.h>  " "/* Definition of " FS_IOC_GETFSMAP ,
+.BR "                             FM?_OF_*" ", and " *FMR_OWN_* " constants */"
+.B #include <sys/ioctl.h>
+.P
+.BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
+.fi
+.SH DESCRIPTION
+This
+.BR ioctl (2)
+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.
+.P
+The sole argument to this operation should be a pointer to a single
+.IR "struct fsmap_head" ":"
+.P
+.in +4n
+.EX
+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 */
+};
+.EE
+.in
+.P
+The two
+.I fmh_keys
+array elements specify the lowest and highest reverse-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
+support sharing physical blocks between multiple files and
+therefore may return multiple mappings for a given physical block.
+.P
+Filesystem mappings are copied into the
+.I fmh_recs
+array, which immediately follows the header data.
+.\"
+.SS Fields of struct fsmap_head
+The
+.I fmh_iflags
+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.
+.P
+The
+.I fmh_oflags
+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
+.I dev_t
+structure containing the major and minor numbers of the block device.
+.P
+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.
+.P
+The
+.I fmh_entries
+field contains the number of elements in the
+.I fmh_recs
+array that contain useful information.
+.P
+The
+.I fmh_reserved
+fields must be set to zero.
+.\"
+.SS Keys
+The two key records in
+.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
+.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 36\ KiB on disk.
+If the high key is set to (8:0, 1048576, 0, 0, 0),
+only records below 1\ MiB will be returned.
+The format of
+.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
+.I fsmap_head.fmh_keys[0]
+must contain the low key and
+.I fsmap_head.fmh_keys[1]
+must contain the high key for the operation.
+.P
+For convenience, if
+.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
+.I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1]
+into the low key.
+The function
+.I fsmap_advance
+(defined in
+.IR linux/fsmap.h )
+provides this functionality.
+.\"
+.SS Fields of struct fsmap
+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
+.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.
+.P
+The
+.I fmr_physical
+field contains the disk address of the extent in bytes.
+.P
+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.
+.P
+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 "."
+.P
+The
+.I fmr_length
+field contains the length of the extent in bytes.
+.P
+The
+.I fmr_flags
+field is a bit mask 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 data set.
+.RE
+.P
+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
+.P
+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
+.P
+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 bit map.
+.TP
+.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.
+.SH ERRORS
+The error placed in
+.I errno
+can be one of, but is not limited to, the following:
+.TP
+.B EBADF
+.I fd
+is not open for reading.
+.TP
+.B EBADMSG
+The filesystem has detected a checksum error in the metadata.
+.TP
+.B EFAULT
+The pointer passed in was not mapped to a valid memory address.
+.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 nonzero value
+was passed in one of the fields that must be zero.
+.TP
+.B ENOMEM
+Insufficient memory to process the operation.
+.TP
+.B EOPNOTSUPP
+The filesystem does not support this operation.
+.TP
+.B EUCLEAN
+The filesystem metadata is corrupt and needs repair.
+.SH STANDARDS
+Linux.
+.P
+Not all filesystems support it.
+.SH HISTORY
+Linux 4.12.
+.SH EXAMPLES
+See
+.I io/fsmap.c
+in the
+.I xfsprogs
+distribution for a sample program.
+.SH SEE ALSO
+.BR ioctl (2)