]>
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 | .\" |
460495ca | 38 | .TH FSYNC 2 2015-08-08 "Linux" "Linux Programmer's Manual" |
fea681da | 39 | .SH NAME |
f67cdb5d | 40 | fsync, fdatasync \- synchronize a file's in-core state with storage device |
fea681da MK |
41 | .SH SYNOPSIS |
42 | .B #include <unistd.h> | |
43 | .sp | |
44 | .BI "int fsync(int " fd ); | |
45 | .sp | |
46 | .BI "int fdatasync(int " fd ); | |
cc4615cc MK |
47 | .sp |
48 | .in -4n | |
49 | Feature Test Macro Requirements for glibc (see | |
50 | .BR feature_test_macros (7)): | |
51 | .in | |
52 | .sp | |
53 | .BR fsync (): | |
54 | _BSD_SOURCE || _XOPEN_SOURCE | |
da8dbaa5 MK |
55 | .br |
56 | || /* since glibc 2.8: */ _POSIX_C_SOURCE\ >=\ 200112L | |
57 | .\" _POSIX_C_SOURCE\ >=\ 200112L only since glibc 2.8 | |
cc4615cc MK |
58 | .br |
59 | .BR fdatasync (): | |
60 | _POSIX_C_SOURCE\ >=\ 199309L || _XOPEN_SOURCE\ >=\ 500 | |
fea681da | 61 | .SH DESCRIPTION |
e511ffb6 | 62 | .BR fsync () |
c13182ef MK |
63 | transfers ("flushes") all modified in-core data of |
64 | (i.e., modified buffer cache pages for) the | |
f67cdb5d MK |
65 | file referred to by the file descriptor |
66 | .I fd | |
71ae2f4a CH |
67 | to the disk device (or other permanent storage device) so that all |
68 | changed information can be retrieved even after the system crashed or | |
ad476033 MK |
69 | was rebooted. |
70 | This includes writing through or flushing a disk cache if present. | |
f67cdb5d | 71 | The call blocks until the device reports that the transfer has completed. |
0425de01 | 72 | It also flushes metadata information associated with the file (see |
c13182ef | 73 | .BR stat (2)). |
f67cdb5d MK |
74 | |
75 | Calling | |
76 | .BR fsync () | |
77 | does not necessarily ensure | |
fea681da MK |
78 | that the entry in the directory containing the file has also reached disk. |
79 | For that an explicit | |
e511ffb6 | 80 | .BR fsync () |
f67cdb5d | 81 | on a file descriptor for the directory is also needed. |
fea681da | 82 | |
e511ffb6 | 83 | .BR fdatasync () |
c13182ef | 84 | is similar to |
f67cdb5d | 85 | .BR fsync (), |
c13182ef | 86 | but does not flush modified metadata unless that metadata |
f67cdb5d MK |
87 | is needed in order to allow a subsequent data retrieval to be |
88 | correctly handled. | |
c13182ef MK |
89 | For example, changes to |
90 | .I st_atime | |
91 | or | |
f67cdb5d | 92 | .I st_mtime |
310b7919 MK |
93 | (respectively, time of last access and |
94 | time of last modification; see | |
c13182ef | 95 | .BR stat (2)) |
1954b6a9 | 96 | do not require flushing because they are not necessary for |
f67cdb5d MK |
97 | a subsequent data read to be handled correctly. |
98 | On the other hand, a change to the file size | |
99 | .RI ( st_size , | |
100 | as made by say | |
101 | .BR ftruncate (2)), | |
102 | would require a metadata flush. | |
103 | ||
104 | The aim of | |
8da9ae24 | 105 | .BR fdatasync () |
f67cdb5d | 106 | is to reduce disk activity for applications that do not |
d9bfdb9c | 107 | require all metadata to be synchronized with the disk. |
47297adb | 108 | .SH RETURN VALUE |
c6a16930 | 109 | On success, these system calls return zero. |
c13182ef | 110 | On error, \-1 is returned, and |
fea681da MK |
111 | .I errno |
112 | is set appropriately. | |
113 | .SH ERRORS | |
114 | .TP | |
115 | .B EBADF | |
116 | .I fd | |
71ae2f4a | 117 | is not a valid open file descriptor. |
fea681da MK |
118 | .TP |
119 | .B EIO | |
120 | An error occurred during synchronization. | |
121 | .TP | |
122 | .BR EROFS ", " EINVAL | |
123 | .I fd | |
124 | is bound to a special file which does not support synchronization. | |
47297adb | 125 | .SH CONFORMING TO |
ab97e9ed | 126 | POSIX.1-2001, POSIX.1-2008, 4.3BSD. |
c6a16930 MK |
127 | .SH AVAILABILITY |
128 | On POSIX systems on which | |
129 | .BR fdatasync () | |
130 | is available, | |
131 | .B _POSIX_SYNCHRONIZED_IO | |
132 | is defined in | |
133 | .I <unistd.h> | |
134 | to a value greater than 0. | |
135 | (See also | |
136 | .BR sysconf (3).) | |
137 | .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. | |
138 | .\" -1: unavailable, 0: ask using sysconf(). | |
139 | .\" glibc defines them to 1. | |
fea681da | 140 | .SH NOTES |
ba9830cf MK |
141 | On some UNIX systems (but not Linux), |
142 | .I fd | |
143 | must be a | |
144 | .I writable | |
145 | file descriptor. | |
146 | ||
c6a16930 MK |
147 | In Linux 2.2 and earlier, |
148 | .BR fdatasync () | |
149 | is equivalent to | |
8da9ae24 | 150 | .BR fsync (), |
c6a16930 | 151 | and so has no performance advantage. |
71ae2f4a CH |
152 | |
153 | The | |
154 | .BR fsync () | |
155 | implementations in older kernels and lesser used filesystems | |
ad476033 MK |
156 | does not know how to flush disk caches. |
157 | In these cases disk caches need to be disabled using | |
71ae2f4a CH |
158 | .BR hdparm (8) |
159 | or | |
160 | .BR sdparm (8) | |
161 | to guarantee safe operation. | |
47297adb | 162 | .SH SEE ALSO |
fea681da MK |
163 | .BR bdflush (2), |
164 | .BR open (2), | |
310b7919 | 165 | .BR sync (2), |
bb8617d4 | 166 | .BR sync_file_range (2), |
1d793a51 | 167 | .BR hdparm (8), |
fea681da | 168 | .BR mount (8), |
c023a7f8 | 169 | .BR sync (1) |