summaryrefslogtreecommitdiff
path: root/lib/libc/sys/fsync.2
blob: ec379ce4d6cbcce1fd946be8e5ef143c090dc856 (plain)
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
.\"	$NetBSD: fsync.2,v 1.15 2003/11/18 08:49:18 wiz 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 November 14, 2003
.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 moved 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
should be used by programs that require a file to be
in a known state, for example, in building a simple transaction
facility.
.Pp
.Fn fsync_range
causes all modified data starting at
.Fa start
for length
.Fa length
of
.Fa fd
to be written to permanent storage.
Note that
.Fn fsync_range
requires that the file
.Fa fd
must be open for writing.
.Pp
.Fn fsync_range
may flush the file data in one of two manners:
.Bl -tag -width FDATASYNC
.It Dv FDATASYNC
Synchronize the file data and sufficient meta-data to retrieve the
data for the specified range.
.It Dv FFILESYNC
Synchronize all modified file data and meta-data for the specified range.
.El
.Pp
If the
.Fa length
parameter is zero,
.Fn fsync_range
will synchronize all of the file data.
.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 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.