original/man2/sync_file_range.2

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