Linux程序员手册 第2部分
更新日期： 2020-06-09

名称

ioctl_getfsmap-检索文件系统的物理布局

语法

＃包括
＃包括
＃包括

int ioctl(int fd，FS_IOC_GETFSMAP，结构fsmap_head * arg);

说明

此ioctl(2)操作检索文件系统的物理范围映射。此信息可用于发现哪些文件已映射到物理块，检查可用空间或查找已知的坏块等。

此操作的唯一参数应为指向单个结构fsmap_head的指针：

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 */
};

两个fmh_keys数组元素指定应用程序需要物理映射信息的最低和最高反向映射键。反向映射键由元组(设备，块，所有者，偏移量)组成。 owner和offset字段是键的一部分，因为某些文件系统支持在多个文件之间共享物理块，因此可能会为给定的物理块返回多个映射。

文件系统映射被复制到fmh_recs数组中，该数组紧随标题数据之后。

Fields of struct fsmap_head

fmh_iflags字段是传递给内核以更改输出的位掩码。当前未定义任何标志，因此调用者必须将此值设置为零。

fmh_oflags字段是内核设置的与返回的映射有关的标志的位掩码。如果设置了FMH_OF_DEV_T，则fmr_device字段表示一个dev_t结构，其中包含块设备的主要和次要编号。

fmh_count字段包含要传递给内核的数组中的元素数。如果该值为0，则fmh_entries将设置为如果数组足够大将返回的记录数。没有映射信息将被返回。

fmh_entries字段包含fmh_recs数组中包含有用信息的元素数。

fmh_reserved字段必须设置为零。

Keys

fsmap_head.fmh_keys中的两个关键记录指定了调用者要返回的键空间中的最低和最高范围记录。可以在文件之间共享块的文件系统可能需要元组(设备，物理，所有者，偏移量，标志)唯一地索引任何文件系统映射记录。经典的非共享文件系统可能仅能够识别(设备，物理，标志)任何记录。例如，如果低键设置为(8：0、36864、0、0、0)，则文件系统将仅返回磁盘上以36 KB以上的扩展区的记录。如果高键设置为(8：0，1048576，0，0，0)，则仅返回1 MiB以下的记录。键中的fmr_device格式必须与输出记录中相同字段的格式匹配，如下所示。按照约定，字段fsmap_head.fmh_keys [0]必须包含低键，而fsmap_head.fmh_keys [1]必须包含请求的高键。

为方便起见，如果在低调中设置了fmr_length，则会将其适当地添加到fmr_block或fmr_offset中。通过将fsmap_head.fmh_recs [fsmap_head.fmh_entries-1]复制到低调中，调用者可以利用此微妙之处来设置后续调用。功能fsmap_advance(在linux / fsmap.h中定义)提供了此功能。

Fields of struct fsmap

fmr_device字段唯一标识基础存储设备。如果在标头的fmh_oflags字段中设置了FMH_OF_DEV_T标志，则此字段包含一个dev_t，可以从中提取大号和小号。如果未设置该标志，则此字段包含一个值，该值对于每个唯一的存储设备都必须是唯一的。

fmr_physical字段包含扩展区的磁盘地址(以字节为单位)。

fmr_owner字段包含扩展区的所有者。除非在fmr_flags字段中设置了FMR_OF_SPECIAL_OWNER，否则这是一个inode编号，在这种情况下，该值由文件系统确定。有关更多详细信息，请参见以下有关所有者值的部分。

fmr_offset字段包含映射记录中的逻辑地址(以字节为单位)。如果在fmr_flags中设置了FMR_OF_SPECIAL_OWNER或FMR_OF_EXTENT_MAP标志，则此字段没有意义。

fmr_length字段包含扩展区的长度(以字节为单位)。

fmr_flags字段是扩展区状态标志的位掩码。这些位是：

FMR_OF_PREALLOC

范围已分配但尚未写入。

FMR_OF_ATTR_FORK

该范围包含扩展的属性数据。

FMR_OF_EXTENT_MAP

该范围包含所有者的范围图信息。

FMR_OF_SHARED

此范围的部分内容可以共享。

FMR_OF_SPECIAL_OWNER

fmr_owner字段包含特殊值而不是inode编号。

FMR_OF_LAST

这是数据集中的最后一条记录。

fmr_reserved字段将设置为零。

Owner values

通常，非元数据扩展区的fmr_owner字段的值应为inode编号。但是，文件系统没有义务报告索引节点号。如果无法轻易检索到索引节点号，调用者缺乏足够的特权，文件系统不支持稳定的索引节点号或出于任何其他原因，它们可能会报告FMR_OWN_UNKNOWN。如果文件系统希望根据进程功能来限制索引节点号的报告，则强烈建议将CAP_SYS_ADMIN功能用于此目的。

The following special owner values are generic to all filesystems:

FMR_OWN_FREE

可用空间。

FMR_OWN_UNKNOWN

此范围已在使用中，但其所有者未知或不容易检索。

FMR_OWN_METADATA

这个范围是文件系统元数据。

XFS可以返回以下特殊所有者值：

XFS_FMR_OWN_FREE

可用空间。

XFS_FMR_OWN_UNKNOWN

此范围已在使用中，但其所有者未知或不容易检索。

XFS_FMR_OWN_FS

存在于固定地址的静态文件系统元数据。这些是AG超级块，AGF，AGFL和AGI标头。

XFS_FMR_OWN_LOG

文件系统日志。

XFS_FMR_OWN_AG

分配组元数据，例如自由空间btree和反向映射btree。

XFS_FMR_OWN_INOBT

索引节点和自由索引节点树。

XFS_FMR_OWN_INODES

Inode记录。

XFS_FMR_OWN_REFC

参考计数信息。

XFS_FMR_OWN_COW

此范围用于暂存写时复制。

XFS_FMR_OWN_DEFECTIVE:

文件系统或基础设备已将该范围标记为有缺陷。

ext4可以返回以下特殊所有者值：

EXT4_FMR_OWN_FREE

可用空间。

EXT4_FMR_OWN_UNKNOWN

此范围已在使用中，但其所有者未知或不容易检索。

EXT4_FMR_OWN_FS

存在于固定地址的静态文件系统元数据。这是超级块和组描述符。

EXT4_FMR_OWN_LOG

文件系统日志。

EXT4_FMR_OWN_INODES

Inode记录。

EXT4_FMR_OWN_BLKBM

块位图。

EXT4_FMR_OWN_INOBM

索引节点位图。

返回值

如果出错，则返回-1，并且将errno设置为指示错误。

错误说明

放置在errno中的错误可以是但不限于以下之一：

EBADF

fd未开放供阅读。

EBADMSG

文件系统已检测到元数据中的校验和错误。

EFAULT

传入的指针未映射到有效的内存地址。

EINVAL

数组不够长，键未指向文件系统的有效部分，低键指向文件系统的物理存储地址空间中比高键更高的点，或者在其中一个中传递了非零值必须为零的字段。

ENOMEM

内存不足，无法处理请求。

EOPNOTSUPP

文件系统不支持此命令。

EUCLEAN

文件系统元数据已损坏，需要修复。

版本

FS_IOC_GETFSMAP操作首先出现在Linux 4.12中。

遵循规范

该API是特定于Linux的。并非所有文件系统都支持它。

示例

有关示例程序，请参见xfsprogs发行版中的io / fsmap.c。

另外参见

ioctl(2)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。