]>
Commit | Line | Data |
---|---|---|
3ca974e3 | 1 | .\" Copyright (c) 2006 Andrew Morton <akpm@osdl.org> |
c11b1abf | 2 | .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
3ca974e3 | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
3ca974e3 | 5 | .\" |
c13182ef | 6 | .\" 2006-07-05 Initial creation, Michael Kerrisk based on |
3ca974e3 | 7 | .\" Andrew Morton's comments in fs/sync.c |
cd95b6a6 | 8 | .\" 2010-10-09, mtk, Document sync_file_range2() |
3ca974e3 | 9 | .\" |
4c1c5274 | 10 | .TH sync_file_range 2 (date) "Linux man-pages (unreleased)" |
3ca974e3 MK |
11 | .SH NAME |
12 | sync_file_range \- sync a file segment with disk | |
949dc28a AC |
13 | .SH LIBRARY |
14 | Standard C library | |
8fc3b2cf | 15 | .RI ( libc ", " \-lc ) |
3ca974e3 MK |
16 | .SH SYNOPSIS |
17 | .nf | |
b80f966b | 18 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
3ca974e3 | 19 | .B #include <fcntl.h> |
dbfe9c70 | 20 | .PP |
6ef95cb0 MK |
21 | .BI "int sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes , |
22 | .BI " unsigned int " flags ); | |
3ca974e3 MK |
23 | .fi |
24 | .SH DESCRIPTION | |
25 | .BR sync_file_range () | |
222ccf09 | 26 | permits fine control when synchronizing the open file referred to by the |
3ca974e3 MK |
27 | file descriptor |
28 | .I fd | |
29 | with disk. | |
efeece04 | 30 | .PP |
c13182ef | 31 | .I offset |
d9bfdb9c | 32 | is the starting byte of the file range to be synchronized. |
c13182ef | 33 | .I nbytes |
d9bfdb9c | 34 | specifies the length of the range to be synchronized, in bytes; if |
3ca974e3 | 35 | .I nbytes |
c13182ef | 36 | is zero, then all bytes from |
3ca974e3 | 37 | .I offset |
d9bfdb9c MK |
38 | through to the end of file are synchronized. |
39 | Synchronization is in units of the system page size: | |
c13182ef | 40 | .I offset |
3ca974e3 | 41 | is rounded down to a page boundary; |
cd415e73 | 42 | .I (offset+nbytes\-1) |
3ca974e3 | 43 | is rounded up to a page boundary. |
efeece04 | 44 | .PP |
c13182ef MK |
45 | The |
46 | .I flags | |
3ca974e3 MK |
47 | bit-mask argument can include any of the following values: |
48 | .TP | |
49 | .B SYNC_FILE_RANGE_WAIT_BEFORE | |
50 | Wait upon write-out of all pages in the specified range | |
51 | that have already been submitted to the device driver for write-out | |
52 | before performing any write. | |
53 | .TP | |
54 | .B SYNC_FILE_RANGE_WRITE | |
55 | Initiate write-out of all dirty pages in the specified | |
56 | range which are not presently submitted write-out. | |
65af053c | 57 | Note that even this may block if you attempt to |
35a09d71 | 58 | write more than request queue size. |
3ca974e3 MK |
59 | .TP |
60 | .B SYNC_FILE_RANGE_WAIT_AFTER | |
61 | Wait upon write-out of all pages in the range | |
62 | after performing any write. | |
63 | .PP | |
64 | Specifying | |
65 | .I flags | |
66 | as 0 is permitted, as a no-op. | |
db3e6745 CH |
67 | .SS Warning |
68 | This system call is extremely dangerous and should not be used in portable | |
69 | programs. | |
70 | None of these operations writes out the file's metadata. | |
3ca974e3 | 71 | Therefore, unless the application is strictly performing overwrites of |
db3e6745 CH |
72 | already-instantiated disk blocks, there are no guarantees that the data will |
73 | be available after a crash. | |
74 | There is no user interface to know if a write is purely an overwrite. | |
9ee4a2b6 | 75 | On filesystems using copy-on-write semantics (e.g., |
db3e6745 CH |
76 | .IR btrfs ) |
77 | an overwrite of existing allocated blocks is impossible. | |
78 | When writing into preallocated space, | |
9ee4a2b6 | 79 | many filesystems also require calls into the block |
db3e6745 CH |
80 | allocator, which this system call does not sync out to disk. |
81 | This system call does not flush disk write caches and thus does not provide | |
82 | any data integrity on systems with volatile disk write caches. | |
83 | .SS Some details | |
c13182ef MK |
84 | .B SYNC_FILE_RANGE_WAIT_BEFORE |
85 | and | |
86 | .B SYNC_FILE_RANGE_WAIT_AFTER | |
3ca974e3 | 87 | will detect any |
c13182ef MK |
88 | I/O errors or |
89 | .B ENOSPC | |
3ca974e3 | 90 | conditions and will return these to the caller. |
efeece04 | 91 | .PP |
c13182ef MK |
92 | Useful combinations of the |
93 | .I flags | |
3ca974e3 MK |
94 | bits are: |
95 | .TP | |
96 | .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | |
97 | Ensures that all pages | |
c13182ef MK |
98 | in the specified range which were dirty when |
99 | .BR sync_file_range () | |
3ca974e3 | 100 | was called are placed |
c13182ef | 101 | under write-out. |
3ca974e3 MK |
102 | This is a start-write-for-data-integrity operation. |
103 | .TP | |
104 | .B SYNC_FILE_RANGE_WRITE | |
105 | Start write-out of all dirty pages in the specified range which | |
c13182ef MK |
106 | are not presently under write-out. |
107 | This is an asynchronous flush-to-disk | |
108 | operation. | |
3ca974e3 MK |
109 | This is not suitable for data integrity operations. |
110 | .TP | |
111 | .BR SYNC_FILE_RANGE_WAIT_BEFORE " (or " SYNC_FILE_RANGE_WAIT_AFTER ) | |
112 | Wait for | |
c13182ef MK |
113 | completion of write-out of all pages in the specified range. |
114 | This can be used after an earlier | |
2f0af33b | 115 | .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE |
3ca974e3 MK |
116 | operation to wait for completion of that operation, and obtain its result. |
117 | .TP | |
7ce14e40 MK |
118 | .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | \ |
119 | SYNC_FILE_RANGE_WAIT_AFTER | |
120 | This is a write-for-data-integrity operation | |
3ca974e3 | 121 | that will ensure that all pages in the specified range which were dirty when |
a7e1c01a | 122 | .BR sync_file_range () |
3ca974e3 | 123 | was called are committed to disk. |
6ef95cb0 MK |
124 | .SH RETURN VALUE |
125 | On success, | |
126 | .BR sync_file_range () | |
127 | returns 0; on failure \-1 is returned and | |
128 | .I errno | |
129 | is set to indicate the error. | |
3ca974e3 | 130 | .SH ERRORS |
defcceb3 | 131 | .TP |
3ca974e3 MK |
132 | .B EBADF |
133 | .I fd | |
134 | is not a valid file descriptor. | |
135 | .TP | |
3ca974e3 MK |
136 | .B EINVAL |
137 | .I flags | |
c13182ef | 138 | specifies an invalid bit; or |
3ca974e3 MK |
139 | .I offset |
140 | or | |
141 | .I nbytes | |
142 | is invalid. | |
143 | .TP | |
eab64696 MK |
144 | .B EIO |
145 | I/O error. | |
146 | .TP | |
3ca974e3 MK |
147 | .B ENOMEM |
148 | Out of memory. | |
149 | .TP | |
150 | .B ENOSPC | |
151 | Out of disk space. | |
152 | .TP | |
153 | .B ESPIPE | |
154 | .I fd | |
7f52c459 MK |
155 | refers to something other than a regular file, a block device, or |
156 | a directory. | |
2b6832a9 MK |
157 | .SH VERSIONS |
158 | .BR sync_file_range () | |
159 | appeared on Linux in kernel 2.6.17. | |
3113c7f3 | 160 | .SH STANDARDS |
8382f16d | 161 | This system call is Linux-specific, and should be avoided |
2dd578fd | 162 | in portable programs. |
cd95b6a6 | 163 | .SH NOTES |
624ef274 | 164 | .SS sync_file_range2() |
cd95b6a6 MK |
165 | Some architectures (e.g., PowerPC, ARM) |
166 | need 64-bit arguments to be aligned in a suitable pair of registers. | |
167 | .\" See kernel commit edd5cd4a9424f22b0fa08bef5e299d41befd5622 | |
168 | On such architectures, the call signature of | |
169 | .BR sync_file_range () | |
63ec43ae MK |
170 | shown in the SYNOPSIS would force |
171 | a register to be wasted as padding between the | |
cd95b6a6 MK |
172 | .I fd |
173 | and | |
174 | .I offset | |
175 | arguments. | |
63ec43ae MK |
176 | (See |
177 | .BR syscall (2) | |
178 | for details.) | |
cd95b6a6 MK |
179 | Therefore, these architectures define a different |
180 | system call that orders the arguments suitably: | |
181 | .PP | |
182 | .in +4n | |
b8302363 | 183 | .EX |
cd95b6a6 MK |
184 | .BI "int sync_file_range2(int " fd ", unsigned int " flags , |
185 | .BI " off64_t " offset ", off64_t " nbytes ); | |
b8302363 | 186 | .EE |
cd95b6a6 MK |
187 | .in |
188 | .PP | |
189 | The behavior of this system call is otherwise exactly the same as | |
a45f957e | 190 | .BR sync_file_range (). |
efeece04 | 191 | .PP |
cd95b6a6 MK |
192 | A system call with this signature first appeared on the ARM architecture |
193 | in Linux 2.6.20, with the name | |
194 | .BR arm_sync_file_range (). | |
195 | It was renamed in Linux 2.6.22, | |
196 | when the analogous system call was added for PowerPC. | |
197 | On architectures where glibc support is provided, | |
198 | glibc transparently wraps | |
199 | .BR sync_file_range2 () | |
200 | under the name | |
201 | .BR sync_file_range (). | |
47297adb | 202 | .SH SEE ALSO |
3ca974e3 MK |
203 | .BR fdatasync (2), |
204 | .BR fsync (2), | |
205 | .BR msync (2), | |
0a4f8b7b | 206 | .BR sync (2) |