SYNC_FILE_RANGE - Linux手册页

时间:2019-08-20 17:59:31  来源:igfitidea点击:

Linux程序员手册 第2部分
更新日期: 2017-09-15

名称

sync_file_range-将文件段与磁盘同步

语法

#define _GNU_SOURCE         /* See feature_test_macros(7) */
#include <fcntl.h>

int sync_file_range(int fd, off64_t offset, off64_t nbytes,
                    unsigned int flags);

说明

当将文件描述符fd引用的打开文件与磁盘同步时,sync_file_range()允许进行精细控制。

offset是要同步的文件范围的起始字节。 nbytes指定要同步的范围的长度,以字节为单位;如果nbytes为零,则将从offset到文件末尾的所有字节同步。同步以系统页面大小为单位:偏移量向下舍入到页面边界; (offset + nbytes-1)向上舍入到页面边界。

标志位掩码参数可以包含以下任何值:

SYNC_FILE_RANGE_WAIT_BEFORE
等待写出指定范围内已提交给设备驱动程序进行写出的所有页面,然后再执行任何写操作。
SYNC_FILE_RANGE_WRITE
启动指定范围内当前尚未提交的所有脏页的注销。请注意,如果您尝试写入的内容超过请求队列的大小,那么即使这样做也会阻塞。
SYNC_FILE_RANGE_WAIT_AFTER
执行任何写操作后,请等待范围中所有页面的写出。

允许将标志指定为0(无操作)。

Warning

此系统调用非常危险,因此不应在可移植程序中使用。这些操作都不会写出文件的元数据。因此,除非应用程序严格执行已实例化的磁盘块的覆盖,否则无法保证崩溃后数据将可用。没有用户界面可以知道写入是否纯粹是覆盖。在使用写时复制语义(例如btrfs)的文件系统上,无法覆盖现有已分配的块。当写入预分配的空间时,许多文件系统还需要调用块分配器,而该系统调用不会同步到磁盘。该系统调用不会刷新磁盘写缓存,因此在具有易失性磁盘写缓存的系统上不会提供任何数据完整性。

Some details

SYNC_FILE_RANGE_WAIT_BEFORE和SYNC_FILE_RANGE_WAIT_AFTER将检测任何I / O错误或ENOSPC条件,并将这些错误返回给调用方。

标志位的有用组合是:

SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
确保在调用sync_file_range()时指定范围内所有脏页都被写出。这是一个数据完整性写入操作。
SYNC_FILE_RANGE_WRITE
开始写出当前不在指定范围内的所有脏页。这是异步刷新到磁盘操作。这不适用于数据完整性操作。
SYNC_FILE_RANGE_WAIT_BEFORE(or SYNC_FILE_RANGE_WAIT_AFTER)
等待指定范围内所有页面的写出完成。可以在更早版本的SYNC_FILE_RANGE_WAIT_BEFORE |之后使用。 SYNC_FILE_RANGE_WRITE操作以等待该操作完成,并获得其结果。
SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER
这是一个针对数据完整性的写操作,它将确保在调用sync_file_range()时指定范围内所有脏页都被提交到磁盘。

返回值

成功时,sync_file_range()返回0;否则,返回0。如果失败,则返回-1并将errno设置为指示错误。

错误说明

EBADF
fd不是有效的文件描述符。
EINVAL
标志指定一个无效位;或offset或nbytes无效。
EIO
I / O错误。
ENOMEM
内存不足。
ENOSPC
磁盘空间不足。
ESPIPE
fd引用的不是常规文件,块设备或目录。

版本

sync_file_range()出现在Linux内核2.6.17中。

遵循规范

此系统调用是特定于Linux的,在可移植程序中应避免使用。

备注

sync_file_range2()

某些体系结构(例如PowerPC,ARM)需要64位自变量在一对合适的寄存器中对齐。在这样的体系结构上,摘要中显示的sync_file_range()的调用签名将迫使寄存器浪费为fd和offset参数之间的填充。 (有关详细信息,请参见syscall(2)。)因此,这些体系结构定义了一个不同的系统调用,该调用适当地对参数进行排序:

int sync_file_range2(int fd, unsigned int flags,
                     off64_t offset, off64_t nbytes);

否则,此系统调用的行为与sync_file_range()完全相同。

具有此签名的系统调用首先出现在Linux 2.6.20中的ARM体系结构上,名称为arm_sync_file_range()。当为PowerPC添加了类似的系统调用时,它在Linux 2.6.22中被重命名。在提供glibc支持的体系结构上,glibc透明地将sync_file_range2()包装在名称sync_file_range()下。

另外参见

fdatasync(2),fsync(2),msync(2),sync(2)

出版信息

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