mirror of https://github.com/mkerrisk/man-pages
224 lines
6.7 KiB
Groff
224 lines
6.7 KiB
Groff
.\" 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)
|