]>
Commit | Line | Data |
---|---|---|
f67cdb5d | 1 | .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and |
c11b1abf | 2 | .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>: | |
27 | .\" Removed note about old libc (pre-4.5.26) translating to 'sync'. | |
28 | .\" Modified 15 Apr 1995 by Michael Chastain <mec@shell.portal.com>: | |
29 | .\" Added `see also' section. | |
30 | .\" Modified 13 Apr 1996 by Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de> | |
31 | .\" Added remarks about fdatasync. | |
32 | .\" Modified 31 Jan 1997 by Eric S. Raymond <esr@thyrsus.com> | |
33 | .\" Modified 18 Apr 2001 by Andi Kleen | |
34 | .\" Fix description to describe what it really does; add a few caveats. | |
f67cdb5d | 35 | .\" 2006-04-28, mtk, substantial rewrite of various parts. |
ad476033 | 36 | .\" 2012-02-27 Various changes by Christoph Hellwig <hch@lst.de> |
fea681da | 37 | .\" |
bffbb22f | 38 | .TH FSYNC 2 2020-06-09 "Linux" "Linux Programmer's Manual" |
fea681da | 39 | .SH NAME |
f67cdb5d | 40 | fsync, fdatasync \- synchronize a file's in-core state with storage device |
fea681da | 41 | .SH SYNOPSIS |
c7db92b9 | 42 | .nf |
fea681da | 43 | .B #include <unistd.h> |
68e4db0a | 44 | .PP |
fea681da | 45 | .BI "int fsync(int " fd ); |
68e4db0a | 46 | .PP |
fea681da | 47 | .BI "int fdatasync(int " fd ); |
c7db92b9 | 48 | .fi |
68e4db0a | 49 | .PP |
d39ad78f | 50 | .RS -4 |
cc4615cc MK |
51 | Feature Test Macro Requirements for glibc (see |
52 | .BR feature_test_macros (7)): | |
d39ad78f | 53 | .RE |
68e4db0a | 54 | .PP |
2bafc702 | 55 | .nf |
cc4615cc | 56 | .BR fsync (): |
a48088b0 MK |
57 | Glibc 2.16 and later: |
58 | No feature test macros need be defined | |
59 | Glibc up to and including 2.15: | |
60 | _BSD_SOURCE || _XOPEN_SOURCE | |
5c10d2c5 | 61 | || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L |
2bafc702 | 62 | .fi |
98c9347c | 63 | .PP |
cc4615cc | 64 | .BR fdatasync (): |
2bafc702 | 65 | .nf |
5c10d2c5 | 66 | _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500 |
2bafc702 | 67 | .fi |
fea681da | 68 | .SH DESCRIPTION |
e511ffb6 | 69 | .BR fsync () |
c13182ef MK |
70 | transfers ("flushes") all modified in-core data of |
71 | (i.e., modified buffer cache pages for) the | |
f67cdb5d MK |
72 | file referred to by the file descriptor |
73 | .I fd | |
71ae2f4a | 74 | to the disk device (or other permanent storage device) so that all |
296951cf TC |
75 | changed information can be retrieved even if the system crashes or |
76 | is rebooted. | |
ad476033 | 77 | This includes writing through or flushing a disk cache if present. |
f67cdb5d | 78 | The call blocks until the device reports that the transfer has completed. |
2021d0b3 MK |
79 | .PP |
80 | As well as flushing the file data, | |
81 | .BR fsync () | |
82 | also flushes the metadata information associated with the file (see | |
b2b21942 | 83 | .BR inode (7)). |
efeece04 | 84 | .PP |
f67cdb5d MK |
85 | Calling |
86 | .BR fsync () | |
87 | does not necessarily ensure | |
fea681da MK |
88 | that the entry in the directory containing the file has also reached disk. |
89 | For that an explicit | |
e511ffb6 | 90 | .BR fsync () |
f67cdb5d | 91 | on a file descriptor for the directory is also needed. |
efeece04 | 92 | .PP |
e511ffb6 | 93 | .BR fdatasync () |
c13182ef | 94 | is similar to |
f67cdb5d | 95 | .BR fsync (), |
c13182ef | 96 | but does not flush modified metadata unless that metadata |
f67cdb5d MK |
97 | is needed in order to allow a subsequent data retrieval to be |
98 | correctly handled. | |
c13182ef MK |
99 | For example, changes to |
100 | .I st_atime | |
101 | or | |
f67cdb5d | 102 | .I st_mtime |
310b7919 MK |
103 | (respectively, time of last access and |
104 | time of last modification; see | |
e6fc1596 | 105 | .BR inode (7)) |
1954b6a9 | 106 | do not require flushing because they are not necessary for |
f67cdb5d MK |
107 | a subsequent data read to be handled correctly. |
108 | On the other hand, a change to the file size | |
109 | .RI ( st_size , | |
110 | as made by say | |
111 | .BR ftruncate (2)), | |
112 | would require a metadata flush. | |
efeece04 | 113 | .PP |
f67cdb5d | 114 | The aim of |
8da9ae24 | 115 | .BR fdatasync () |
f67cdb5d | 116 | is to reduce disk activity for applications that do not |
d9bfdb9c | 117 | require all metadata to be synchronized with the disk. |
47297adb | 118 | .SH RETURN VALUE |
c6a16930 | 119 | On success, these system calls return zero. |
c13182ef | 120 | On error, \-1 is returned, and |
fea681da | 121 | .I errno |
f6a4078b | 122 | is set to indicate the error. |
fea681da MK |
123 | .SH ERRORS |
124 | .TP | |
125 | .B EBADF | |
126 | .I fd | |
71ae2f4a | 127 | is not a valid open file descriptor. |
fea681da MK |
128 | .TP |
129 | .B EIO | |
c6822f69 MK |
130 | An error occurred during synchronization. |
131 | This error may relate to data written to some other file descriptor | |
132 | on the same file. | |
133 | Since Linux 4.13, | |
9c93cce7 | 134 | .\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750 |
c6822f69 | 135 | errors from write-back will be reported to |
9c93cce7 | 136 | all file descriptors that might have written the data which triggered |
c6822f69 MK |
137 | the error. |
138 | Some filesystems (e.g., NFS) keep close track of which data | |
9c93cce7 | 139 | came through which file descriptor, and give more precise reporting. |
c6822f69 | 140 | Other filesystems (e.g., most local filesystems) will report errors to |
4f53f6ac | 141 | all file descriptors that were open on the file when the error was recorded. |
fea681da | 142 | .TP |
404de594 CR |
143 | .B ENOSPC |
144 | Disk space was exhausted while synchronizing. | |
145 | .TP | |
fea681da MK |
146 | .BR EROFS ", " EINVAL |
147 | .I fd | |
03117dc0 MK |
148 | is bound to a special file (e.g., a pipe, FIFO, or socket) |
149 | which does not support synchronization. | |
9c93cce7 N |
150 | .TP |
151 | .BR ENOSPC ", " EDQUOT | |
152 | .I fd | |
153 | is bound to a file on NFS or another filesystem which does not allocate | |
154 | space at the time of a | |
155 | .BR write (2) | |
156 | system call, and some previous write failed due to insufficient | |
157 | storage space. | |
47297adb | 158 | .SH CONFORMING TO |
ab97e9ed | 159 | POSIX.1-2001, POSIX.1-2008, 4.3BSD. |
bd168648 | 160 | .PP |
c6a16930 MK |
161 | On POSIX systems on which |
162 | .BR fdatasync () | |
163 | is available, | |
164 | .B _POSIX_SYNCHRONIZED_IO | |
165 | is defined in | |
166 | .I <unistd.h> | |
167 | to a value greater than 0. | |
168 | (See also | |
169 | .BR sysconf (3).) | |
170 | .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. | |
171 | .\" -1: unavailable, 0: ask using sysconf(). | |
172 | .\" glibc defines them to 1. | |
fea681da | 173 | .SH NOTES |
ba9830cf MK |
174 | On some UNIX systems (but not Linux), |
175 | .I fd | |
176 | must be a | |
177 | .I writable | |
178 | file descriptor. | |
efeece04 | 179 | .PP |
c6a16930 MK |
180 | In Linux 2.2 and earlier, |
181 | .BR fdatasync () | |
182 | is equivalent to | |
8da9ae24 | 183 | .BR fsync (), |
c6a16930 | 184 | and so has no performance advantage. |
efeece04 | 185 | .PP |
71ae2f4a CH |
186 | The |
187 | .BR fsync () | |
188 | implementations in older kernels and lesser used filesystems | |
1f4b8446 | 189 | do not know how to flush disk caches. |
ad476033 | 190 | In these cases disk caches need to be disabled using |
71ae2f4a CH |
191 | .BR hdparm (8) |
192 | or | |
193 | .BR sdparm (8) | |
194 | to guarantee safe operation. | |
47297adb | 195 | .SH SEE ALSO |
ac6cfaca | 196 | .BR sync (1), |
fea681da MK |
197 | .BR bdflush (2), |
198 | .BR open (2), | |
7ba63e47 | 199 | .BR posix_fadvise (2), |
d9e64b42 | 200 | .BR pwritev (2), |
310b7919 | 201 | .BR sync (2), |
bb8617d4 | 202 | .BR sync_file_range (2), |
966d59d5 | 203 | .BR fflush (3), |
bf4c35a8 | 204 | .BR fileno (3), |
1d793a51 | 205 | .BR hdparm (8), |
ac6cfaca | 206 | .BR mount (8) |