| .\" Copyright (c) 2006 Andrew Morton <akpm@osdl.org> |
| .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 2006-07-05 Initial creation, Michael Kerrisk based on |
| .\" Andrew Morton's comments in fs/sync.c |
| .\" 2010-10-09, mtk, Document sync_file_range2() |
| .\" |
| .TH SYNC_FILE_RANGE 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| sync_file_range \- sync a file segment with disk |
| .SH SYNOPSIS |
| .nf |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .B #include <fcntl.h> |
| .PP |
| .BI "int sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes , |
| .BI " unsigned int " flags ); |
| .fi |
| .SH DESCRIPTION |
| .BR sync_file_range () |
| permits fine control when synchronizing the open file referred to by the |
| file descriptor |
| .I fd |
| with disk. |
| .PP |
| .I offset |
| is the starting byte of the file range to be synchronized. |
| .I nbytes |
| specifies the length of the range to be synchronized, in bytes; if |
| .I nbytes |
| is zero, then all bytes from |
| .I offset |
| through to the end of file are synchronized. |
| Synchronization is in units of the system page size: |
| .I offset |
| is rounded down to a page boundary; |
| .I (offset+nbytes\-1) |
| is rounded up to a page boundary. |
| .PP |
| The |
| .I flags |
| bit-mask argument can include any of the following values: |
| .TP |
| .B SYNC_FILE_RANGE_WAIT_BEFORE |
| 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. |
| .TP |
| .B SYNC_FILE_RANGE_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. |
| .TP |
| .B SYNC_FILE_RANGE_WAIT_AFTER |
| Wait upon write-out of all pages in the range |
| after performing any write. |
| .PP |
| Specifying |
| .I flags |
| as 0 is permitted, as a no-op. |
| .SS Warning |
| This system call is extremely dangerous and should not be used in portable |
| programs. |
| None of these operations writes out the file's metadata. |
| Therefore, unless the application is strictly performing overwrites of |
| already-instantiated disk blocks, there are no guarantees that the data will |
| be available after a crash. |
| There is no user interface to know if a write is purely an overwrite. |
| On filesystems using copy-on-write semantics (e.g., |
| .IR btrfs ) |
| an overwrite of existing allocated blocks is impossible. |
| When writing into preallocated space, |
| many filesystems also require calls into the block |
| allocator, which this system call does not sync out to disk. |
| This system call does not flush disk write caches and thus does not provide |
| any data integrity on systems with volatile disk write caches. |
| .SS Some details |
| .B SYNC_FILE_RANGE_WAIT_BEFORE |
| and |
| .B SYNC_FILE_RANGE_WAIT_AFTER |
| will detect any |
| I/O errors or |
| .B ENOSPC |
| conditions and will return these to the caller. |
| .PP |
| Useful combinations of the |
| .I flags |
| bits are: |
| .TP |
| .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE |
| Ensures that all pages |
| in the specified range which were dirty when |
| .BR sync_file_range () |
| was called are placed |
| under write-out. |
| This is a start-write-for-data-integrity operation. |
| .TP |
| .B SYNC_FILE_RANGE_WRITE |
| 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. |
| .TP |
| .BR 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 |
| .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE |
| operation to wait for completion of that operation, and obtain its result. |
| .TP |
| .B 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 |
| .BR sync_file_range () |
| was called are committed to disk. |
| .SH RETURN VALUE |
| On success, |
| .BR sync_file_range () |
| returns 0; on failure \-1 is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| .I fd |
| is not a valid file descriptor. |
| .TP |
| .B EINVAL |
| .I flags |
| specifies an invalid bit; or |
| .I offset |
| or |
| .I nbytes |
| is invalid. |
| .TP |
| .B EIO |
| I/O error. |
| .TP |
| .B ENOMEM |
| Out of memory. |
| .TP |
| .B ENOSPC |
| Out of disk space. |
| .TP |
| .B ESPIPE |
| .I fd |
| refers to something other than a regular file, a block device, or |
| a directory. |
| .SH VERSIONS |
| .BR sync_file_range () |
| appeared on Linux in kernel 2.6.17. |
| .SH CONFORMING TO |
| This system call is Linux-specific, and should be avoided |
| in portable programs. |
| .SH NOTES |
| .SS sync_file_range2() |
| Some architectures (e.g., PowerPC, ARM) |
| need 64-bit arguments to be aligned in a suitable pair of registers. |
| .\" See kernel commit edd5cd4a9424f22b0fa08bef5e299d41befd5622 |
| On such architectures, the call signature of |
| .BR sync_file_range () |
| shown in the SYNOPSIS would force |
| a register to be wasted as padding between the |
| .I fd |
| and |
| .I offset |
| arguments. |
| (See |
| .BR syscall (2) |
| for details.) |
| Therefore, these architectures define a different |
| system call that orders the arguments suitably: |
| .PP |
| .in +4n |
| .EX |
| .BI "int sync_file_range2(int " fd ", unsigned int " flags , |
| .BI " off64_t " offset ", off64_t " nbytes ); |
| .EE |
| .in |
| .PP |
| The behavior of this system call is otherwise exactly the same as |
| .BR sync_file_range (). |
| .PP |
| A system call with this signature first appeared on the ARM architecture |
| in Linux 2.6.20, with the name |
| .BR 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 |
| .BR sync_file_range2 () |
| under the name |
| .BR sync_file_range (). |
| .SH SEE ALSO |
| .BR fdatasync (2), |
| .BR fsync (2), |
| .BR msync (2), |
| .BR sync (2) |