289 lines
7.2 KiB
HTML
289 lines
7.2 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of FSYNC</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>FSYNC</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
fsync, fdatasync - synchronize a file's in-core state with storage device
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>#include <<A HREF="file:///usr/include/unistd.h">unistd.h</A>></B>
|
|
|
|
<P>
|
|
|
|
<B>int fsync(int </B><I>fd</I><B>);</B>
|
|
|
|
<P>
|
|
|
|
<B>int fdatasync(int </B><I>fd</I><B>);</B>
|
|
|
|
<P>
|
|
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A></B>(7)):
|
|
|
|
|
|
<P>
|
|
|
|
<B>fsync</B>():
|
|
|
|
<BR> Glibc 2.16 and later:
|
|
<BR> No feature test macros need be defined
|
|
<BR> Glibc up to and including 2.15:
|
|
<BR> _BSD_SOURCE || _XOPEN_SOURCE
|
|
<BR> || /* since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
|
|
<BR>
|
|
|
|
<B>fdatasync</B>():
|
|
|
|
<BR> _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>fsync</B>()
|
|
|
|
transfers ("flushes") all modified in-core data of
|
|
(i.e., modified buffer cache pages for) the
|
|
file referred to by the file descriptor
|
|
<I>fd</I>
|
|
|
|
to the disk device (or other permanent storage device) so that all
|
|
changed information can be retrieved even if the system crashes or
|
|
is rebooted.
|
|
This includes writing through or flushing a disk cache if present.
|
|
The call blocks until the device reports that the transfer has completed.
|
|
<P>
|
|
|
|
As well as flushing the file data,
|
|
<B>fsync</B>()
|
|
|
|
also flushes the metadata information associated with the file (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+inode">inode</A></B>(7)).
|
|
|
|
<P>
|
|
|
|
Calling
|
|
<B>fsync</B>()
|
|
|
|
does not necessarily ensure
|
|
that the entry in the directory containing the file has also reached disk.
|
|
For that an explicit
|
|
<B>fsync</B>()
|
|
|
|
on a file descriptor for the directory is also needed.
|
|
<P>
|
|
|
|
<B>fdatasync</B>()
|
|
|
|
is similar to
|
|
<B>fsync</B>(),
|
|
|
|
but does not flush modified metadata unless that metadata
|
|
is needed in order to allow a subsequent data retrieval to be
|
|
correctly handled.
|
|
For example, changes to
|
|
<I>st_atime</I>
|
|
|
|
or
|
|
<I>st_mtime</I>
|
|
|
|
(respectively, time of last access and
|
|
time of last modification; see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+inode">inode</A></B>(7))
|
|
|
|
do not require flushing because they are not necessary for
|
|
a subsequent data read to be handled correctly.
|
|
On the other hand, a change to the file size
|
|
(<I>st_size</I>,
|
|
|
|
as made by say
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ftruncate">ftruncate</A></B>(2)),
|
|
|
|
would require a metadata flush.
|
|
<P>
|
|
|
|
The aim of
|
|
<B>fdatasync</B>()
|
|
|
|
is to reduce disk activity for applications that do not
|
|
require all metadata to be synchronized with the disk.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success, these system calls return zero.
|
|
On error, -1 is returned, and
|
|
<I>errno</I>
|
|
|
|
is set appropriately.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>EBADF</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
is not a valid open file descriptor.
|
|
<DT id="2"><B>EIO</B>
|
|
|
|
<DD>
|
|
An error occurred during synchronization.
|
|
This error may relate to data written to some other file descriptor
|
|
on the same file.
|
|
Since Linux 4.13,
|
|
|
|
errors from write-back will be reported to
|
|
all file descriptors that might have written the data which triggered
|
|
the error.
|
|
Some filesystems (e.g., NFS) keep close track of which data
|
|
came through which file descriptor, and give more precise reporting.
|
|
Other filesystems (e.g., most local filesystems) will report errors to
|
|
all file descriptors that were open on the file when the error was recorded.
|
|
<DT id="3"><B>ENOSPC</B>
|
|
|
|
<DD>
|
|
Disk space was exhausted while synchronizing.
|
|
<DT id="4"><B>EROFS</B>, <B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
is bound to a special file (e.g., a pipe, FIFO, or socket)
|
|
which does not support synchronization.
|
|
<DT id="5"><B>ENOSPC</B>, <B>EDQUOT</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
is bound to a file on NFS or another filesystem which does not allocate
|
|
space at the time of a
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
system call, and some previous write failed due to insufficient
|
|
storage space.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
POSIX.1-2001, POSIX.1-2008, 4.3BSD.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>AVAILABILITY</H2>
|
|
|
|
On POSIX systems on which
|
|
<B>fdatasync</B>()
|
|
|
|
is available,
|
|
<B>_POSIX_SYNCHRONIZED_IO</B>
|
|
|
|
is defined in
|
|
<I><<A HREF="file:///usr/include/unistd.h">unistd.h</A>></I>
|
|
|
|
to a value greater than 0.
|
|
(See also
|
|
<B><A HREF="/cgi-bin/man/man2html?3+sysconf">sysconf</A></B>(3).)
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
On some UNIX systems (but not Linux),
|
|
<I>fd</I>
|
|
|
|
must be a
|
|
<I>writable</I>
|
|
|
|
file descriptor.
|
|
<P>
|
|
|
|
In Linux 2.2 and earlier,
|
|
<B>fdatasync</B>()
|
|
|
|
is equivalent to
|
|
<B>fsync</B>(),
|
|
|
|
and so has no performance advantage.
|
|
<P>
|
|
|
|
The
|
|
<B>fsync</B>()
|
|
|
|
implementations in older kernels and lesser used filesystems
|
|
do not know how to flush disk caches.
|
|
In these cases disk caches need to be disabled using
|
|
<B><A HREF="/cgi-bin/man/man2html?8+hdparm">hdparm</A></B>(8)
|
|
|
|
or
|
|
<B><A HREF="/cgi-bin/man/man2html?8+sdparm">sdparm</A></B>(8)
|
|
|
|
to guarantee safe operation.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+sync">sync</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+bdflush">bdflush</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+posix_fadvise">posix_fadvise</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pwritev">pwritev</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+sync">sync</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+sync_file_range">sync_file_range</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+fflush">fflush</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+fileno">fileno</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+hdparm">hdparm</A></B>(8),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+mount">mount</A></B>(8)
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="6"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="7"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="8"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="9"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="10"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="11"><A HREF="#lbAG">CONFORMING TO</A><DD>
|
|
<DT id="12"><A HREF="#lbAH">AVAILABILITY</A><DD>
|
|
<DT id="13"><A HREF="#lbAI">NOTES</A><DD>
|
|
<DT id="14"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
|
<DT id="15"><A HREF="#lbAK">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:32 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|