]>
Commit | Line | Data |
---|---|---|
3ca974e3 MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (c) 2006 Andrew Morton <akpm@osdl.org> | |
c11b1abf | 4 | .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
3ca974e3 MK |
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. | |
c13182ef | 14 | .\" |
3ca974e3 MK |
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. | |
c13182ef | 22 | .\" |
3ca974e3 MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
25 | .\" | |
c13182ef | 26 | .\" 2006-07-05 Initial creation, Michael Kerrisk based on |
3ca974e3 MK |
27 | .\" Andrew Morton's comments in fs/sync.c |
28 | .\" | |
d9343c5c | 29 | .TH SYNC_FILE_RANGE 2 2006-07-05 "Linux" "Linux Programmer's Manual" |
3ca974e3 MK |
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 | ||
6ef95cb0 MK |
37 | .BI "int sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes , |
38 | .BI " unsigned int " flags ); | |
3ca974e3 MK |
39 | .fi |
40 | .SH DESCRIPTION | |
41 | .BR sync_file_range () | |
42 | permits fine control when synchronising the open file referred to by the | |
43 | file descriptor | |
44 | .I fd | |
45 | with disk. | |
46 | ||
c13182ef | 47 | .I offset |
d9bfdb9c | 48 | is the starting byte of the file range to be synchronized. |
c13182ef | 49 | .I nbytes |
d9bfdb9c | 50 | specifies the length of the range to be synchronized, in bytes; if |
3ca974e3 | 51 | .I nbytes |
c13182ef | 52 | is zero, then all bytes from |
3ca974e3 | 53 | .I offset |
d9bfdb9c MK |
54 | through to the end of file are synchronized. |
55 | Synchronization is in units of the system page size: | |
c13182ef | 56 | .I offset |
3ca974e3 | 57 | is rounded down to a page boundary; |
c13182ef | 58 | .I (offset+nbytes-1) |
3ca974e3 MK |
59 | is rounded up to a page boundary. |
60 | ||
c13182ef MK |
61 | The |
62 | .I flags | |
3ca974e3 MK |
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 | .TP | |
74 | .B SYNC_FILE_RANGE_WAIT_AFTER | |
75 | Wait upon write-out of all pages in the range | |
76 | after performing any write. | |
77 | .PP | |
78 | Specifying | |
79 | .I flags | |
80 | as 0 is permitted, as a no-op. | |
2b2581ee | 81 | .SS Some details |
c13182ef | 82 | None of these operations write out the file's metadata. |
3ca974e3 | 83 | Therefore, unless the application is strictly performing overwrites of |
c13182ef | 84 | already-instantiated disk blocks, |
3ca974e3 MK |
85 | there are no guarantees that the data will be available after a crash. |
86 | ||
c13182ef MK |
87 | .B SYNC_FILE_RANGE_WAIT_BEFORE |
88 | and | |
89 | .B SYNC_FILE_RANGE_WAIT_AFTER | |
3ca974e3 | 90 | will detect any |
c13182ef MK |
91 | I/O errors or |
92 | .B ENOSPC | |
3ca974e3 MK |
93 | conditions and will return these to the caller. |
94 | ||
c13182ef MK |
95 | Useful combinations of the |
96 | .I flags | |
3ca974e3 MK |
97 | bits are: |
98 | .TP | |
99 | .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | |
100 | Ensures that all pages | |
c13182ef MK |
101 | in the specified range which were dirty when |
102 | .BR sync_file_range () | |
3ca974e3 | 103 | was called are placed |
c13182ef | 104 | under write-out. |
3ca974e3 MK |
105 | This is a start-write-for-data-integrity operation. |
106 | .TP | |
107 | .B SYNC_FILE_RANGE_WRITE | |
108 | Start write-out of all dirty pages in the specified range which | |
c13182ef MK |
109 | are not presently under write-out. |
110 | This is an asynchronous flush-to-disk | |
111 | operation. | |
3ca974e3 MK |
112 | This is not suitable for data integrity operations. |
113 | .TP | |
114 | .BR SYNC_FILE_RANGE_WAIT_BEFORE " (or " SYNC_FILE_RANGE_WAIT_AFTER ) | |
115 | Wait for | |
c13182ef MK |
116 | completion of write-out of all pages in the specified range. |
117 | This can be used after an earlier | |
2f0af33b | 118 | .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE |
3ca974e3 MK |
119 | operation to wait for completion of that operation, and obtain its result. |
120 | .TP | |
121 | .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER | |
c13182ef MK |
122 | This is a traditional |
123 | .BR fdatasync (2) | |
3ca974e3 MK |
124 | operation. |
125 | It is a write-for-data-integrity operation | |
126 | that will ensure that all pages in the specified range which were dirty when | |
a7e1c01a | 127 | .BR sync_file_range () |
3ca974e3 | 128 | was called are committed to disk. |
6ef95cb0 MK |
129 | .SH RETURN VALUE |
130 | On success, | |
131 | .BR sync_file_range () | |
132 | returns 0; on failure \-1 is returned and | |
133 | .I errno | |
134 | is set to indicate the error. | |
3ca974e3 | 135 | .SH ERRORS |
defcceb3 | 136 | .TP |
3ca974e3 MK |
137 | .B EBADF |
138 | .I fd | |
139 | is not a valid file descriptor. | |
140 | .TP | |
3ca974e3 MK |
141 | .B EINVAL |
142 | .I flags | |
c13182ef | 143 | specifies an invalid bit; or |
3ca974e3 MK |
144 | .I offset |
145 | or | |
146 | .I nbytes | |
147 | is invalid. | |
148 | .TP | |
eab64696 MK |
149 | .B EIO |
150 | I/O error. | |
151 | .TP | |
3ca974e3 MK |
152 | .B ENOMEM |
153 | Out of memory. | |
154 | .TP | |
155 | .B ENOSPC | |
156 | Out of disk space. | |
157 | .TP | |
158 | .B ESPIPE | |
159 | .I fd | |
c13182ef | 160 | refers to something other than a regular file, a block device, |
3ca974e3 | 161 | a directory, or a symbolic link. |
c13182ef MK |
162 | .\" FIXME . (bug?) Actually, how can 'fd' refer to a symbolic link (S_ISLNK)? |
163 | .\" (In userspace at least) it isn't possible to obtain a file descriptor | |
3ca974e3 | 164 | .\" for a symbolic link. |
2b6832a9 MK |
165 | .SH VERSIONS |
166 | .BR sync_file_range () | |
167 | appeared on Linux in kernel 2.6.17. | |
2dd578fd | 168 | .SH "CONFORMING TO" |
8382f16d | 169 | This system call is Linux-specific, and should be avoided |
2dd578fd | 170 | in portable programs. |
3ca974e3 MK |
171 | .SH "SEE ALSO" |
172 | .BR fdatasync (2), | |
173 | .BR fsync (2), | |
174 | .BR msync (2), | |
0a90178c MK |
175 | .BR sync (2), |
176 | .BR feature_test_macros (7) |