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/。