1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
.\" $NetBSD: fsync.2,v 1.18 2013/09/22 10:02:05 apb Exp $
.\"
.\" Copyright (c) 1983, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)fsync.2 8.1 (Berkeley) 6/4/93
.\"
.Dd September 22, 2013
.Dt FSYNC 2
.Os
.Sh NAME
.Nm fsync ,
.Nm fsync_range
.Nd "synchronize a file's in-core state with that on disk"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fn fsync "int fd"
.Ft int
.Fn fsync_range "int fd" "int how" "off_t start" "off_t length"
.Sh DESCRIPTION
.Fn fsync
causes all modified data and attributes of
.Fa fd
to be written to a permanent storage device.
This normally results in all in-core modified copies
of buffers for the associated file to be written to a disk.
.Pp
.Fn fsync_range
is similar, but provides control over the region of the file
to be synchronized, and the method of synchronization.
.Pp
These functions should be used by programs that require a file to be
in a known state, for example, in building a simple transaction
facility.
.Pp
Note that writing the data to a permanent storage device
does not necessarily write the data to permanent storage media
within that device;
for example, after writing data to a disk device, the data might
reside in a cache within the device, but not yet on
more permanent storage within the device.
Neither
.Fn fsync
nor the default behavior of
.Fn fsync_range
(without the
.Dv FDISKSYNC
flag)
will flush disk caches,
because they assume that storage devices are able to ensure that
completed writes are transferred to media some time between the
write and a power failure or system crash.
.Pp
.Fn fsync_range
causes all modified data starting at
.Fa start
for length
.Fa length
of
.Fa fd
to be written to a permanent storage device.
If the
.Fa length
parameter is zero,
.Fn fsync_range
will synchronize all of the file data.
.Pp
.Fn fsync_range
takes a
.Fa how
parameter which contains one or more of the following flags:
.Bl -tag -width FDATASYNC -offset indent
.It Dv FDATASYNC
Synchronize the file data and sufficient meta-data to retrieve the
data for the specified range.
This is equivalent to
.Xr fdatasync 2
on the specified range.
.It Dv FFILESYNC
Synchronize all modified file data and meta-data for the specified range.
This is equivalent to
.Xr fsync 2
on the specified range.
.It Dv FDISKSYNC
Request the destination device to ensure that the relevant data
and meta-data is flushed from any cache to permanent storage media.
In the present implementation, the entire cache on the affected device will
be flushed, and this may have a significant impact on performance.
.El
.Pp
The
.Dv FDATASYNC
and
.Dv FFILESYNC
flags are mutually exclusive.
Either of those flags may be combined with the
.Dv FDISKSYNC
flag.
.Pp
Note that
.Fn fsync_range
requires that the file
.Fa fd
must be open for writing, whereas
.Fn fsync
does not.
.Sh RETURN VALUES
A 0 value is returned on success.
A \-1 value indicates an error.
.Sh ERRORS
.Fn fsync
or
.Fn fsync_range
fail if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa fd
is not a valid descriptor.
.It Bq Er EINVAL
.Fa fd
refers to a socket, not to a file.
.It Bq Er EIO
An I/O error occurred while reading from or writing to the file system.
.El
.Pp
Additionally,
.Fn fsync_range
fails if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa fd
is not open for writing.
.It Bq Er EINVAL
.Fa start
+
.Fa length
is less than
.Fa start .
.El
.Sh NOTES
For optimal efficiency, the
.Fn fsync_range
call requires that the file system containing the file referenced by
.Fa fd
support partial synchronization of file data.
For file systems which do
not support partial synchronization, the entire file will be synchronized
and the call will be the equivalent of calling
.Fn fsync .
.Sh SEE ALSO
.Xr fdatasync 2 ,
.Xr sync 2 ,
.Xr sync 8
.Sh HISTORY
The
.Fn fsync
function call appeared in
.Bx 4.2 .
.Pp
The
.Fn fsync_range
function call first appeared in
.Nx 2.0
and is modeled after the function available in AIX.
|
