summaryrefslogtreecommitdiffstats
path: root/man2/sync_file_range.2
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
commit3d08cd331c1adcf0d917392f7e527b3f00511748 (patch)
tree312f0d1e1632f48862f044b8bb87e602dcffb5f9 /man2/sync_file_range.2
parentAdding debian version 6.7-2. (diff)
downloadmanpages-3d08cd331c1adcf0d917392f7e527b3f00511748.tar.xz
manpages-3d08cd331c1adcf0d917392f7e527b3f00511748.zip
Merging upstream version 6.8.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man2/sync_file_range.2')
-rw-r--r--man2/sync_file_range.2213
1 files changed, 0 insertions, 213 deletions
diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2
deleted file mode 100644
index becef29..0000000
--- a/man2/sync_file_range.2
+++ /dev/null
@@ -1,213 +0,0 @@
-.\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)