man2/fsync.2

   1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and
   2 .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   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.
  15 .\" 2006-04-28, mtk, substantial rewrite of various parts.
  16 .\" 2012-02-27 Various changes by Christoph Hellwig <hch@lst.de>
  17 .\"
  18 .TH fsync 2 (date) "Linux man-pages (unreleased)"
  19 .SH NAME
  20 fsync, fdatasync \- synchronize a file's in-core state with storage device
  21 .SH LIBRARY
  22 Standard C library
  23 .RI ( libc ", " \-lc )
  24 .SH SYNOPSIS
  25 .nf
  26 .B #include <unistd.h>
  27 .PP
  28 .BI "int fsync(int " fd );
  29 .PP
  30 .BI "int fdatasync(int " fd );
  31 .fi
  32 .PP
  33 .RS -4
  34 Feature Test Macro Requirements for glibc (see
  35 .BR feature_test_macros (7)):
  36 .RE
  37 .PP
  38 .nf
  39 .BR fsync ():
  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
  44             || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
  45 .fi
  46 .PP
  47 .BR fdatasync ():
  48 .nf
  49     _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500
  50 .fi
  51 .SH DESCRIPTION
  52 .BR fsync ()
  53 transfers ("flushes") all modified in-core data of
  54 (i.e., modified buffer cache pages for) the
  55 file referred to by the file descriptor
  56 .I fd
  57 to the disk device (or other permanent storage device) so that all
  58 changed information can be retrieved even if the system crashes or
  59 is rebooted.
  60 This includes writing through or flushing a disk cache if present.
  61 The call blocks until the device reports that the transfer has completed.
  62 .PP
  63 As well as flushing the file data,
  64 .BR fsync ()
  65 also flushes the metadata information associated with the file (see
  66 .BR inode (7)).
  67 .PP
  68 Calling
  69 .BR fsync ()
  70 does not necessarily ensure
  71 that the entry in the directory containing the file has also reached disk.
  72 For that an explicit
  73 .BR fsync ()
  74 on a file descriptor for the directory is also needed.
  75 .PP
  76 .BR fdatasync ()
  77 is similar to
  78 .BR fsync (),
  79 but does not flush modified metadata unless that metadata
  80 is needed in order to allow a subsequent data retrieval to be
  81 correctly handled.
  82 For example, changes to
  83 .I st_atime
  84 or
  85 .I st_mtime
  86 (respectively, time of last access and
  87 time of last modification; see
  88 .BR inode (7))
  89 do not require flushing because they are not necessary for
  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.
  96 .PP
  97 The aim of
  98 .BR fdatasync ()
  99 is to reduce disk activity for applications that do not
 100 require all metadata to be synchronized with the disk.
 101 .SH RETURN VALUE
 102 On success, these system calls return zero.
 103 On error, \-1 is returned, and
 104 .I errno
 105 is set to indicate the error.
 106 .SH ERRORS
 107 .TP
 108 .B EBADF
 109 .I fd
 110 is not a valid open file descriptor.
 111 .TP
 112 .B EINTR
 113 The function was interrupted by a signal; see
 114 .BR signal (7).
 115 .TP
 116 .B EIO
 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,
 121 .\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750
 122 errors from write-back will be reported to
 123 all file descriptors that might have written the data which triggered
 124 the error.
 125 Some filesystems (e.g., NFS) keep close track of which data
 126 came through which file descriptor, and give more precise reporting.
 127 Other filesystems (e.g., most local filesystems) will report errors to
 128 all file descriptors that were open on the file when the error was recorded.
 129 .TP
 130 .B ENOSPC
 131 Disk space was exhausted while synchronizing.
 132 .TP
 133 .BR EROFS ", " EINVAL
 134 .I fd
 135 is bound to a special file (e.g., a pipe, FIFO, or socket)
 136 which does not support synchronization.
 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.
 145 .SH STANDARDS
 146 POSIX.1-2001, POSIX.1-2008, 4.3BSD.
 147 .PP
 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.
 160 .SH NOTES
 161 On some UNIX systems (but not Linux),
 162 .I fd
 163 must be a
 164 .I writable
 165 file descriptor.
 166 .PP
 167 In Linux 2.2 and earlier,
 168 .BR fdatasync ()
 169 is equivalent to
 170 .BR fsync (),
 171 and so has no performance advantage.
 172 .PP
 173 The
 174 .BR fsync ()
 175 implementations in older kernels and lesser used filesystems
 176 do not know how to flush disk caches.
 177 In these cases disk caches need to be disabled using
 178 .BR hdparm (8)
 179 or
 180 .BR sdparm (8)
 181 to guarantee safe operation.
 182 .SH SEE ALSO
 183 .BR sync (1),
 184 .BR bdflush (2),
 185 .BR open (2),
 186 .BR posix_fadvise (2),
 187 .BR pwritev (2),
 188 .BR sync (2),
 189 .BR sync_file_range (2),
 190 .BR fflush (3),
 191 .BR fileno (3),
 192 .BR hdparm (8),
 193 .BR mount (8)