2006-07-06 08:53:25 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
|
|
|
.\" Copyright (c) 2006 Andrew Morton <akpm@osdl.org>
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com>
|
2006-07-06 08:53:25 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2006-07-06 08:53:25 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2006-07-06 08:53:25 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" 2006-07-05 Initial creation, Michael Kerrisk based on
|
2006-07-06 08:53:25 +00:00
|
|
|
.\" Andrew Morton's comments in fs/sync.c
|
2010-10-09 03:18:17 +00:00
|
|
|
.\" 2010-10-09, mtk, Document sync_file_range2()
|
2006-07-06 08:53:25 +00:00
|
|
|
.\"
|
2010-10-09 03:18:17 +00:00
|
|
|
.TH SYNC_FILE_RANGE 2 2010-10-09 "Linux" "Linux Programmer's Manual"
|
2006-07-06 08:53:25 +00:00
|
|
|
.SH NAME
|
|
|
|
sync_file_range \- sync a file segment with disk
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
getresuid.2, mremap.2, poll.2, remap_file_pages.2, setresuid.2, splice.2, sync_file_range.2, syscall.2, tee.2, vmsplice.2, INFINITY.3, aio_init.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, fopencookie.3, ftw.3, getaddrinfo_a.3, getloadavg.3, getutent.3, grantpt.3, hsearch.3, lseek64.3, memmem.3, mempcpy.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, sched_getcpu.3, sincos.3, strchr.3, strfry.3, strnlen.3, strptime.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlockpt.3, wcwidth.3: Add reference to feature_test_macros(7)
Some pages simply list feature test macro requirements in
the form:
#define #GNU_SOURCE
#include <someheader.h>
For these pages, add a "See feature_test_macros(7)" comment
on the "#define" line.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 04:31:47 +00:00
|
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
2006-07-06 08:53:25 +00:00
|
|
|
.B #include <fcntl.h>
|
|
|
|
|
2007-05-21 22:46:30 +00:00
|
|
|
.BI "int sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes ,
|
|
|
|
.BI " unsigned int " flags );
|
2006-07-06 08:53:25 +00:00
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.BR sync_file_range ()
|
2008-03-11 12:53:16 +00:00
|
|
|
permits fine control when synchronizing the open file referred to by the
|
2006-07-06 08:53:25 +00:00
|
|
|
file descriptor
|
|
|
|
.I fd
|
|
|
|
with disk.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
.I offset
|
2007-06-08 09:56:56 +00:00
|
|
|
is the starting byte of the file range to be synchronized.
|
2007-04-12 22:42:49 +00:00
|
|
|
.I nbytes
|
2007-06-08 09:56:56 +00:00
|
|
|
specifies the length of the range to be synchronized, in bytes; if
|
2006-07-06 08:53:25 +00:00
|
|
|
.I nbytes
|
2007-04-12 22:42:49 +00:00
|
|
|
is zero, then all bytes from
|
2006-07-06 08:53:25 +00:00
|
|
|
.I offset
|
2007-06-08 09:56:56 +00:00
|
|
|
through to the end of file are synchronized.
|
|
|
|
Synchronization is in units of the system page size:
|
2007-04-12 22:42:49 +00:00
|
|
|
.I offset
|
2006-07-06 08:53:25 +00:00
|
|
|
is rounded down to a page boundary;
|
2007-04-12 22:42:49 +00:00
|
|
|
.I (offset+nbytes-1)
|
2006-07-06 08:53:25 +00:00
|
|
|
is rounded up to a page boundary.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
The
|
|
|
|
.I flags
|
2006-07-06 08:53:25 +00:00
|
|
|
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.
|
2008-07-02 13:00:16 +00:00
|
|
|
Note that even this may block if you attempt to
|
2008-06-13 10:51:02 +00:00
|
|
|
write more than request queue size.
|
2006-07-06 08:53:25 +00:00
|
|
|
.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.
|
2010-01-17 04:44:25 +00:00
|
|
|
.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.
|
2006-07-06 08:53:25 +00:00
|
|
|
Therefore, unless the application is strictly performing overwrites of
|
2010-01-17 04:44:25 +00:00
|
|
|
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.
|
2010-06-15 03:16:42 +00:00
|
|
|
On file systems using copy-on-write semantics (e.g.,
|
2010-01-17 04:44:25 +00:00
|
|
|
.IR btrfs )
|
|
|
|
an overwrite of existing allocated blocks is impossible.
|
|
|
|
When writing into preallocated space,
|
2010-06-15 03:16:42 +00:00
|
|
|
many file systems also require calls into the block
|
2010-01-17 04:44:25 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
.B SYNC_FILE_RANGE_WAIT_BEFORE
|
|
|
|
and
|
|
|
|
.B SYNC_FILE_RANGE_WAIT_AFTER
|
2006-07-06 08:53:25 +00:00
|
|
|
will detect any
|
2007-04-12 22:42:49 +00:00
|
|
|
I/O errors or
|
|
|
|
.B ENOSPC
|
2006-07-06 08:53:25 +00:00
|
|
|
conditions and will return these to the caller.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
Useful combinations of the
|
|
|
|
.I flags
|
2006-07-06 08:53:25 +00:00
|
|
|
bits are:
|
|
|
|
.TP
|
|
|
|
.B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
|
|
|
|
Ensures that all pages
|
2007-04-12 22:42:49 +00:00
|
|
|
in the specified range which were dirty when
|
|
|
|
.BR sync_file_range ()
|
2006-07-06 08:53:25 +00:00
|
|
|
was called are placed
|
2007-04-12 22:42:49 +00:00
|
|
|
under write-out.
|
2006-07-06 08:53:25 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
are not presently under write-out.
|
|
|
|
This is an asynchronous flush-to-disk
|
|
|
|
operation.
|
2006-07-06 08:53:25 +00:00
|
|
|
This is not suitable for data integrity operations.
|
|
|
|
.TP
|
|
|
|
.BR SYNC_FILE_RANGE_WAIT_BEFORE " (or " SYNC_FILE_RANGE_WAIT_AFTER )
|
|
|
|
Wait for
|
2007-04-12 22:42:49 +00:00
|
|
|
completion of write-out of all pages in the specified range.
|
|
|
|
This can be used after an earlier
|
2007-06-22 19:42:52 +00:00
|
|
|
.B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
|
2006-07-06 08:53:25 +00:00
|
|
|
operation to wait for completion of that operation, and obtain its result.
|
|
|
|
.TP
|
2008-05-29 07:55:33 +00:00
|
|
|
.B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | \
|
|
|
|
SYNC_FILE_RANGE_WAIT_AFTER
|
|
|
|
This is a write-for-data-integrity operation
|
2006-07-06 08:53:25 +00:00
|
|
|
that will ensure that all pages in the specified range which were dirty when
|
2007-05-21 21:25:44 +00:00
|
|
|
.BR sync_file_range ()
|
2006-07-06 08:53:25 +00:00
|
|
|
was called are committed to disk.
|
2007-05-21 22:46:30 +00:00
|
|
|
.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.
|
2006-07-06 08:53:25 +00:00
|
|
|
.SH ERRORS
|
2006-07-20 16:16:51 +00:00
|
|
|
.TP
|
2006-07-06 08:53:25 +00:00
|
|
|
.B EBADF
|
|
|
|
.I fd
|
|
|
|
is not a valid file descriptor.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I flags
|
2007-04-12 22:42:49 +00:00
|
|
|
specifies an invalid bit; or
|
2006-07-06 08:53:25 +00:00
|
|
|
.I offset
|
|
|
|
or
|
|
|
|
.I nbytes
|
|
|
|
is invalid.
|
|
|
|
.TP
|
2007-08-27 07:56:52 +00:00
|
|
|
.B EIO
|
|
|
|
I/O error.
|
|
|
|
.TP
|
2006-07-06 08:53:25 +00:00
|
|
|
.B ENOMEM
|
|
|
|
Out of memory.
|
|
|
|
.TP
|
|
|
|
.B ENOSPC
|
|
|
|
Out of disk space.
|
|
|
|
.TP
|
|
|
|
.B ESPIPE
|
|
|
|
.I fd
|
2007-04-12 22:42:49 +00:00
|
|
|
refers to something other than a regular file, a block device,
|
2006-07-06 08:53:25 +00:00
|
|
|
a directory, or a symbolic link.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" FIXME . (bug?) Actually, how can 'fd' refer to a symbolic link (S_ISLNK)?
|
|
|
|
.\" (In userspace at least) it isn't possible to obtain a file descriptor
|
2006-07-06 08:53:25 +00:00
|
|
|
.\" for a symbolic link.
|
2006-09-06 09:17:14 +00:00
|
|
|
.SH VERSIONS
|
|
|
|
.BR sync_file_range ()
|
|
|
|
appeared on Linux in kernel 2.6.17.
|
2007-05-18 16:30:46 +00:00
|
|
|
.SH "CONFORMING TO"
|
2007-12-25 21:28:09 +00:00
|
|
|
This system call is Linux-specific, and should be avoided
|
2007-05-18 16:30:46 +00:00
|
|
|
in portable programs.
|
2010-10-09 03:18:17 +00:00
|
|
|
.SH NOTES
|
|
|
|
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 ()
|
|
|
|
is flawed, since it forces a register to be wasted as padding between the
|
|
|
|
.I fd
|
|
|
|
and
|
|
|
|
.I offset
|
|
|
|
arguments.
|
|
|
|
Therefore, these architectures define a different
|
|
|
|
system call that orders the arguments suitably:
|
|
|
|
.PP
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
.BI "int sync_file_range2(int " fd ", unsigned int " flags ,
|
|
|
|
.BI " off64_t " offset ", off64_t " nbytes );
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
.PP
|
|
|
|
The behavior of this system call is otherwise exactly the same as
|
2010-11-01 06:52:28 +00:00
|
|
|
.BR sync_file_range ().
|
2010-10-09 03:18:17 +00:00
|
|
|
|
|
|
|
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 ().
|
2006-07-06 08:53:25 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR fdatasync (2),
|
|
|
|
.BR fsync (2),
|
|
|
|
.BR msync (2),
|
getresuid.2, intro.2, mremap.2, open.2, poll.2, posix_fadvise.2, pread.2, remap_file_pages.2, setresuid.2, signal.2, splice.2, sync_file_range.2, tee.2, vmsplice.2, INFINITY.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, dprintf.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, ffs.3, fmemopen.3, fopencookie.3, ftw.3, getdate.3, getline.3, getloadavg.3, getopt.3, getsubopt.3, getutent.3, grantpt.3, hsearch.3, intro.3, lseek64.3, memmem.3, mempcpy.3, mq_receive.3, mq_send.3, posix_fallocate.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, readdir.3, sigset.3, sincos.3, stpcpy.3, stpncpy.3, strchr.3, strfry.3, strnlen.3, strptime.3, strsignal.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlocked_stdio.3, unlockpt.3, wcpcpy.3, wcpncpy.3, wcsdup.3, wcwidth.3: SEE ALSO: Remove redundant reference to feature_test_macros(7)
Reported-by: Florian Lehmann <flo.lehmann@googlemail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 05:05:22 +00:00
|
|
|
.BR sync (2)
|