1 files changed, 213 insertions, 0 deletions
diff --git a/man/man2/sync_file_range.2 b/man/man2/sync_file_range.2
new file mode 100644
index 000000000..2f6fadbe9
--- /dev/null
+++ b/man/man2/sync_file_range.2
@@ -0,0 +1,213 @@
+.\" Copyright (c) 2006 Andrew Morton <akpm@osdl.org>
+.\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 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 (date) "Linux man-pages (unreleased)"
+.SH NAME
+sync_file_range \- sync a file segment with disk
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #define _FILE_OFFSET_BITS 64
+.B #include <fcntl.h>
+.P
+.BI "int sync_file_range(int " fd ", off_t " offset ", off_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.
+.P
+.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.
+.P
+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.
+.P
+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.
+.P
+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
+.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:
+.P
+.in +4n
+.EX
+.BI "int sync_file_range2(int " fd ", unsigned int " flags ,
+.BI "                     off_t " offset ", off_t " nbytes );
+.EE
+.in
+.P
+The behavior of this system call is otherwise exactly the same as
+.BR sync_file_range ().
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.17.
+.SS sync_file_range2()
+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 NOTES
+.B _FILE_OFFSET_BITS
+should be defined to be 64 in code that takes the address of
+.BR sync_file_range ,
+if the code is intended to be portable
+to traditional 32-bit x86 and ARM platforms where
+.BR off_t 's
+width defaults to 32 bits.
+.SH SEE ALSO
+.BR fdatasync (2),
+.BR fsync (2),
+.BR msync (2),
+.BR sync (2)