Debian Codegraph @

upstream/debian-trixie/man2/sync_file_range.2

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