Debian Codegraph @

upstream/debian-unstable/man2/fsync.2

raw
1 .\" Copyright 1993, Rickard E. Faith <[email protected]>
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH fsync 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 fsync, fdatasync \- synchronize a file's in-core state with storage device
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BI "int fsync(int " fd );
18 .P
19 .BI "int fdatasync(int " fd );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .nf
28 .BR fsync ():
29 glibc 2.16 and later:
30 No feature test macros need be defined
31 glibc up to and including 2.15:
32 _BSD_SOURCE || _XOPEN_SOURCE
33 || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
34 .fi
35 .P
36 .BR fdatasync ():
37 .nf
38 _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500
39 .fi
40 .SH DESCRIPTION
41 .BR fsync ()
42 transfers ("flushes") all modified in-core data of
43 (i.e., modified buffer cache pages for) the
44 file referred to by the file descriptor
45 .I fd
46 to the disk device (or other permanent storage device) so that all
47 changed information can be retrieved even if the system crashes or
48 is rebooted.
49 This includes writing through or flushing a disk cache if present.
50 The call blocks until the device reports that the transfer has completed.
51 .P
52 As well as flushing the file data,
53 .BR fsync ()
54 also flushes the metadata information associated with the file (see
55 .BR inode (7)).
56 .P
57 Calling
58 .BR fsync ()
59 does not necessarily ensure
60 that the entry in the directory containing the file has also reached disk.
61 For that an explicit
62 .BR fsync ()
63 on a file descriptor for the directory is also needed.
64 .P
65 .BR fdatasync ()
66 is similar to
67 .BR fsync (),
68 but does not flush modified metadata unless that metadata
69 is needed in order to allow a subsequent data retrieval to be
70 correctly handled.
71 For example, changes to
72 .I st_atime
73 or
74 .I st_mtime
75 (respectively, time of last access and
76 time of last modification;
77 see
78 .BR inode (7))
79 do not require flushing because they are not necessary for
80 a subsequent data read to be handled correctly.
81 On the other hand, a change to the file size
82 .RI ( st_size ,
83 as made by say
84 .BR ftruncate (2)),
85 would require a metadata flush.
86 .P
87 The aim of
88 .BR fdatasync ()
89 is to reduce disk activity for applications that do not
90 require all metadata to be synchronized with the disk.
91 .SH RETURN VALUE
92 On success, these system calls return zero.
93 On error, \-1 is returned, and
94 .I errno
95 is set to indicate the error.
96 .SH ERRORS
97 .TP
98 .B EBADF
99 .I fd
100 is not a valid open file descriptor.
101 .TP
102 .B EINTR
103 The function was interrupted by a signal;
104 see
105 .BR signal (7).
106 .TP
107 .B EIO
108 An error occurred during synchronization.
109 This error may relate to data written to some other file descriptor
110 on the same file.
111 Since Linux 4.13,
112 .\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750
113 errors from write-back will be reported to
114 all file descriptors that might have written the data which triggered
115 the error.
116 Some filesystems (e.g., NFS) keep close track of which data
117 came through which file descriptor, and give more precise reporting.
118 Other filesystems (e.g., most local filesystems) will report errors to
119 all file descriptors that were open on the file when the error was recorded.
120 .TP
121 .B ENOSPC
122 Disk space was exhausted while synchronizing.
123 .TP
124 .B EROFS
125 .TQ
126 .B EINVAL
127 .I fd
128 is bound to a special file (e.g., a pipe, FIFO, or socket)
129 which does not support synchronization.
130 .TP
131 .B ENOSPC
132 .TQ
133 .B EDQUOT
134 .I fd
135 is bound to a file on NFS or another filesystem which does not allocate
136 space at the time of a
137 .BR write (2)
138 system call, and some previous write failed due to insufficient
139 storage space.
140 .SH VERSIONS
141 On POSIX systems on which
142 .BR fdatasync ()
143 is available,
144 .B _POSIX_SYNCHRONIZED_IO
145 is defined in
146 .I <unistd.h>
147 to a value greater than 0.
148 (See also
149 .BR sysconf (3).)
150 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
151 .\" -1: unavailable, 0: ask using sysconf().
152 .\" glibc defines them to 1.
153 .SH STANDARDS
154 POSIX.1-2024.
155 .SH HISTORY
156 .TP
157 .BR fsync ()
158 4.2BSD,
159 SUSv1,
160 POSIX.1-1996.
161 .TP
162 .BR fdatasync ()
163 POSIX.1-1996.
164 .P
165 In Linux 2.2 and earlier,
166 .BR fdatasync ()
167 is equivalent to
168 .BR fsync (),
169 and so has no performance advantage.
170 .P
171 The
172 .BR fsync ()
173 implementations in older kernels and lesser used filesystems
174 do not know how to flush disk caches.
175 In these cases disk caches need to be disabled using
176 .BR hdparm (8)
177 or
178 .BR sdparm (8)
179 to guarantee safe operation.
180 .P
181 Under AT&T UNIX System V Release 4
182 .I fd
183 needs to be opened for writing.
184 This is by itself incompatible with the original BSD interface
185 and forbidden by POSIX,
186 but nevertheless survives in HP-UX and AIX.
187 .SH SEE ALSO
188 .BR sync (1),
189 .BR bdflush (2),
190 .BR open (2),
191 .BR posix_fadvise (2),
192 .BR pwritev (2),
193 .BR sync (2),
194 .BR sync_file_range (2),
195 .BR fflush (3),
196 .BR fileno (3),
197 .BR hdparm (8),
198 .BR mount (8)