original/man2/sync_file_range.2

   1 .\" Copyright (c) 2006 Andrew Morton <akpm@osdl.org>
   2 .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" 2006-07-05 Initial creation, Michael Kerrisk based on
  27 .\"     Andrew Morton's comments in fs/sync.c
  28 .\" 2010-10-09, mtk, Document sync_file_range2()
  29 .\"
  30 .TH SYNC_FILE_RANGE 2 2014-08-19 "Linux" "Linux Programmer's Manual"
  31 .SH NAME
  32 sync_file_range \- sync a file segment with disk
  33 .SH SYNOPSIS
  34 .nf
  35 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  36 .B #include <fcntl.h>
  37
  38 .BI "int sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes ,
  39 .BI "                    unsigned int " flags );
  40 .fi
  41 .SH DESCRIPTION
  42 .BR sync_file_range ()
  43 permits fine control when synchronizing the open file referred to by the
  44 file descriptor
  45 .I fd
  46 with disk.
  47
  48 .I offset
  49 is the starting byte of the file range to be synchronized.
  50 .I nbytes
  51 specifies the length of the range to be synchronized, in bytes; if
  52 .I nbytes
  53 is zero, then all bytes from
  54 .I offset
  55 through to the end of file are synchronized.
  56 Synchronization is in units of the system page size:
  57 .I offset
  58 is rounded down to a page boundary;
  59 .I (offset+nbytes-1)
  60 is rounded up to a page boundary.
  61
  62 The
  63 .I flags
  64 bit-mask argument can include any of the following values:
  65 .TP
  66 .B SYNC_FILE_RANGE_WAIT_BEFORE
  67 Wait upon write-out of all pages in the specified range
  68 that have already been submitted to the device driver for write-out
  69 before performing any write.
  70 .TP
  71 .B SYNC_FILE_RANGE_WRITE
  72 Initiate write-out of all dirty pages in the specified
  73 range which are not presently submitted write-out.
  74 Note that even this may block if you attempt to
  75 write more than request queue size.
  76 .TP
  77 .B SYNC_FILE_RANGE_WAIT_AFTER
  78 Wait upon write-out of all pages in the range
  79 after performing any write.
  80 .PP
  81 Specifying
  82 .I flags
  83 as 0 is permitted, as a no-op.
  84 .SS Warning
  85 This system call is extremely dangerous and should not be used in portable
  86 programs.
  87 None of these operations writes out the file's metadata.
  88 Therefore, unless the application is strictly performing overwrites of
  89 already-instantiated disk blocks, there are no guarantees that the data will
  90 be available after a crash.
  91 There is no user interface to know if a write is purely an overwrite.
  92 On filesystems using copy-on-write semantics (e.g.,
  93 .IR btrfs )
  94 an overwrite of existing allocated blocks is impossible.
  95 When writing into preallocated space,
  96 many filesystems also require calls into the block
  97 allocator, which this system call does not sync out to disk.
  98 This system call does not flush disk write caches and thus does not provide
  99 any data integrity on systems with volatile disk write caches.
 100 .SS Some details
 101 .B SYNC_FILE_RANGE_WAIT_BEFORE
 102 and
 103 .B SYNC_FILE_RANGE_WAIT_AFTER
 104 will detect any
 105 I/O errors or
 106 .B ENOSPC
 107 conditions and will return these to the caller.
 108
 109 Useful combinations of the
 110 .I flags
 111 bits are:
 112 .TP
 113 .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
 114 Ensures that all pages
 115 in the specified range which were dirty when
 116 .BR sync_file_range ()
 117 was called are placed
 118 under write-out.
 119 This is a start-write-for-data-integrity operation.
 120 .TP
 121 .B SYNC_FILE_RANGE_WRITE
 122 Start write-out of all dirty pages in the specified range which
 123 are not presently under write-out.
 124 This is an asynchronous flush-to-disk
 125 operation.
 126 This is not suitable for data integrity operations.
 127 .TP
 128 .BR SYNC_FILE_RANGE_WAIT_BEFORE " (or " SYNC_FILE_RANGE_WAIT_AFTER )
 129 Wait for
 130 completion of write-out of all pages in the specified range.
 131 This can be used after an earlier
 132 .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
 133 operation to wait for completion of that operation, and obtain its result.
 134 .TP
 135 .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | \
 136 SYNC_FILE_RANGE_WAIT_AFTER
 137 This is a write-for-data-integrity operation
 138 that will ensure that all pages in the specified range which were dirty when
 139 .BR sync_file_range ()
 140 was called are committed to disk.
 141 .SH RETURN VALUE
 142 On success,
 143 .BR sync_file_range ()
 144 returns 0; on failure \-1 is returned and
 145 .I errno
 146 is set to indicate the error.
 147 .SH ERRORS
 148 .TP
 149 .B EBADF
 150 .I fd
 151 is not a valid file descriptor.
 152 .TP
 153 .B EINVAL
 154 .I flags
 155 specifies an invalid bit; or
 156 .I offset
 157 or
 158 .I nbytes
 159 is invalid.
 160 .TP
 161 .B EIO
 162 I/O error.
 163 .TP
 164 .B ENOMEM
 165 Out of memory.
 166 .TP
 167 .B ENOSPC
 168 Out of disk space.
 169 .TP
 170 .B ESPIPE
 171 .I fd
 172 refers to something other than a regular file, a block device,
 173 a directory, or a symbolic link.
 174 .\" FIXME . (bug?) Actually, how can 'fd' refer to a symbolic link (S_ISLNK)?
 175 .\" (In user space at least) it isn't possible to obtain a file descriptor
 176 .\" for a symbolic link.
 177 .SH VERSIONS
 178 .BR sync_file_range ()
 179 appeared on Linux in kernel 2.6.17.
 180 .SH CONFORMING TO
 181 This system call is Linux-specific, and should be avoided
 182 in portable programs.
 183 .SH NOTES
 184 .SS sync_file_range2()
 185 Some architectures (e.g., PowerPC, ARM)
 186 need 64-bit arguments to be aligned in a suitable pair of registers.
 187 .\" See kernel commit edd5cd4a9424f22b0fa08bef5e299d41befd5622
 188 On such architectures, the call signature of
 189 .BR sync_file_range ()
 190 shown in the SYNOPSIS would force
 191 a register to be wasted as padding between the
 192 .I fd
 193 and
 194 .I offset
 195 arguments.
 196 (See
 197 .BR syscall (2)
 198 for details.)
 199 Therefore, these architectures define a different
 200 system call that orders the arguments suitably:
 201 .PP
 202 .in +4n
 203 .nf
 204 .BI "int sync_file_range2(int " fd ", unsigned int " flags ,
 205 .BI "                     off64_t " offset ", off64_t " nbytes );
 206 .fi
 207 .in
 208 .PP
 209 The behavior of this system call is otherwise exactly the same as
 210 .BR sync_file_range ().
 211
 212 A system call with this signature first appeared on the ARM architecture
 213 in Linux 2.6.20, with the name
 214 .BR arm_sync_file_range ().
 215 It was renamed in Linux 2.6.22,
 216 when the analogous system call was added for PowerPC.
 217 On architectures where glibc support is provided,
 218 glibc transparently wraps
 219 .BR sync_file_range2 ()
 220 under the name
 221 .BR sync_file_range ().
 222 .SH SEE ALSO
 223 .BR fdatasync (2),
 224 .BR fsync (2),
 225 .BR msync (2),
 226 .BR sync (2)
 227 .SH COLOPHON
 228 This page is part of release 3.79 of the Linux
 229 .I man-pages
 230 project.
 231 A description of the project,
 232 information about reporting bugs,
 233 and the latest version of this page,
 234 can be found at
 235 \%http://www.kernel.org/doc/man\-pages/.