summaryrefslogtreecommitdiffstats
path: root/man2/ioctl_getfsmap.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/ioctl_getfsmap.2')
-rw-r--r--man2/ioctl_getfsmap.2351
1 files changed, 0 insertions, 351 deletions
diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2
deleted file mode 100644
index 97fbc67..0000000
--- a/man2/ioctl_getfsmap.2
+++ /dev/null
@@ -1,351 +0,0 @@
-.\" Copyright (c) 2017, Oracle. All rights reserved.
-.\"
-.\" SPDX-License-Identifier: GPL-2.0-or-later
-.TH ioctl_getfsmap 2 2024-03-03 "Linux man-pages 6.7"
-.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)