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