|SYNC_FILE_RANGE(2)||Linux Programmer's Manual||SYNC_FILE_RANGE(2)|
#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);
offset is the starting byte of the file range to be synchronized. nbytes specifies the length of the range to be synchronized, in bytes; if nbytes is zero, then all bytes from offset through to the end of file are synchronized. Synchronization is in units of the system page size: offset is rounded down to a page boundary; (offset+nbytes-1) is rounded up to a page boundary.
The flags bit-mask argument can include any of the following values:
- Wait upon write-out of all pages in the specified range that have already been submitted to the device driver for write-out before performing any write.
- Initiate write-out of all dirty pages in the specified range which are not presently submitted write-out. Note that even this may block if you attempt to write more than request queue size.
- Wait upon write-out of all pages in the range after performing any write.
Specifying flags as 0 is permitted, as a no-op.
Useful combinations of the flags bits are:
- SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
- Ensures that all pages in the specified range which were dirty when sync_file_range() was called are placed under write-out. This is a start-write-for-data-integrity operation.
- Start write-out of all dirty pages in the specified range which are not presently under write-out. This is an asynchronous flush-to-disk operation. This is not suitable for data integrity operations.
- SYNC_FILE_RANGE_WAIT_BEFORE (or SYNC_FILE_RANGE_WAIT_AFTER)
- Wait for completion of write-out of all pages in the specified range. This can be used after an earlier SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE operation to wait for completion of that operation, and obtain its result.
- SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER
- This is a write-for-data-integrity operation that will ensure that all pages in the specified range which were dirty when sync_file_range() was called are committed to disk.
- fd is not a valid file descriptor.
- flags specifies an invalid bit; or offset or nbytes is invalid.
- I/O error.
- Out of memory.
- Out of disk space.
- fd refers to something other than a regular file, a block device, or a directory.
int sync_file_range2(int fd, unsigned int flags, off64_t offset, off64_t nbytes);
The behavior of this system call is otherwise exactly the same as sync_file_range().
A system call with this signature first appeared on the ARM architecture in Linux 2.6.20, with the name arm_sync_file_range(). It was renamed in Linux 2.6.22, when the analogous system call was added for PowerPC. On architectures where glibc support is provided, glibc transparently wraps sync_file_range2() under the name sync_file_range().