IOCTL_FIDEDUPERANGE - Linux手册页

时间:2019-08-20 17:58:54  来源:igfitidea点击:

Linux程序员手册 第2部分
更新日期: 2019-10-10

名称

ioctl_fideduperange-与另一个文件共享一个文件的一些数据

语法

#包括
#包括

int ioctl(int src_fd,FIDEDUPERANGE,struct file_dedupe_range * arg);

说明

如果文件系统支持多个文件之间共享物理存储的文件,则该ioctl(2)操作可用于通过共享基础存储(如果文件数据相同)来使src_fd文件中的某些数据出现在dest_fd文件中("重复数据删除" ")。这两个文件必须位于同一文件系统中。通过允许文件系统存储数据的一个共享副本,可以减少存储消耗。如果应将文件写入共享区域,则文件系统必须确保所做的更改对正在写入的文件保持私有。此行为通常称为"写入时复制"。

该ioctl对文件描述符src_fd中最多src_length个字节(偏移量为src_offset)执行"比较并共享(如果相同)"操作。此信息以以下形式的结构传递:

struct file_dedupe_range {
    __u64 src_offset;
    __u64 src_length;
    __u16 dest_count;
    __u16 reserved1;
    __u32 reserved2;
    struct file_dedupe_range_info info[0];
};

对于并发写入,重复数据删除是原子的,因此无需获取任何锁定即可获得一致的重复数据删除副本。

字段reserved1和reserved2必须为零。

重复数据删除操作的目标在结构末尾的数组中传送。目的地数在dest_count中给出,并且目的地信息以以下形式传达:

struct file_dedupe_range_info {
    __s64 dest_fd;
    __u64 dest_offset;
    __u64 bytes_deduped;
    __s32 status;
    __u32 reserved;
};

每个重复数据删除操作的目标是文件描述符dest_fd中的src_length字节,偏移量为dest_offset。保留的字段必须为零。在调用过程中,必须打开src_fd进行读取,而必须打开dest_fd进行写入。 struct file_dedupe_range和struct file_dedupe_range_info数组的组合大小不得超过系统页面大小。 src_length的最大大小取决于文件系统,通常为16 MiB。该限制将由文件系统以静默方式强制执行。按照惯例,src_fd使用的存储被映射到dest_fd中,并且dest_fd中的先前内容被释放。

成功完成此ioctl后,将成功删除重复数据的字节数以bytes_deduped的形式返回,并以状态返回用于重复数据删除操作的状态码。如果范围内的单个字节都不匹配,则将忽略重复数据删除请求,并将状态设置为FILE_DEDUPE_RANGE_DIFFERS。为了成功,将状态代码设置为FILE_DEDUPE_RANGE_SAME,如果发生错误,则将其设置为负错误代码;如果数据不匹配,则将其设置为FILE_DEDUPE_RANGE_DIFFERS。

返回值

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

错误说明

错误代码可以是但不限于以下之一:

EBADF
src_fd不开放供读取; dest_fd不能进行写入操作,也不能进行仅追加写入操作;或src_fd所在的文件系统不支持重复数据删除。
EINVAL
文件系统不支持对给定文件的范围进行重复数据删除。如果文件描述符代表设备,FIFO或套接字,也会出现此错误。磁盘文件系统通常要求offset和length参数要与基本块大小对齐。 Btrfs和XFS都不支持同一文件中重叠的重复数据删除范围。
EISDIR
文件之一是目录,文件系统不支持目录中的共享区域。
ENOMEM
内核无法分配足够的内存来执行该操作,或者dest_count太大,以致输入参数描述跨越了一个以上的内存页面。
EOPNOTSUPP
如果文件系统不支持对两个文件描述符之一进行重复数据删除,或者任何一个文件描述符都引用了特殊的索引节点,则可能出现这种情况。
EPERM
dest_fd是不可变的。
ETXTBSY
其中一个文件是交换文件。交换文件无法共享存储。
EXDEV
dest_fd和src_fd不在同一已挂载的文件系统上。

版本

这个ioctl操作首先出现在Linux 4.5中。它以前被称为BTRFS_IOC_FILE_EXTENT_SAME,并且是Btrfs专用的。

遵循规范

此API是特定于Linux的。

备注

因为写时复制操作需要分配新的存储,所以fallocate(2)操作可以取消共享共享块,以确保后续的写操作不会因缺少磁盘空间而失败。

某些文件系统可能会限制可以在单个调用中进行重复数据删除的数据量。

另外参见

ioctl(2)

出版信息

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