summaryrefslogtreecommitdiffstats
path: root/man2/fsync.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/fsync.2')
-rw-r--r--man2/fsync.2195
1 files changed, 195 insertions, 0 deletions
diff --git a/man2/fsync.2 b/man2/fsync.2
new file mode 100644
index 0000000..623e7ca
--- /dev/null
+++ b/man2/fsync.2
@@ -0,0 +1,195 @@
+.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and
+.\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified 21 Aug 1994 by Michael Chastain <mec@shell.portal.com>:
+.\" Removed note about old libc (pre-4.5.26) translating to 'sync'.
+.\" Modified 15 Apr 1995 by Michael Chastain <mec@shell.portal.com>:
+.\" Added `see also' section.
+.\" Modified 13 Apr 1996 by Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
+.\" Added remarks about fdatasync.
+.\" Modified 31 Jan 1997 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 18 Apr 2001 by Andi Kleen
+.\" Fix description to describe what it really does; add a few caveats.
+.\" 2006-04-28, mtk, substantial rewrite of various parts.
+.\" 2012-02-27 Various changes by Christoph Hellwig <hch@lst.de>
+.\"
+.TH fsync 2 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+fsync, fdatasync \- synchronize a file's in-core state with storage device
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.PP
+.BI "int fsync(int " fd );
+.PP
+.BI "int fdatasync(int " fd );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.nf
+.BR fsync ():
+ glibc 2.16 and later:
+ No feature test macros need be defined
+ glibc up to and including 2.15:
+ _BSD_SOURCE || _XOPEN_SOURCE
+ || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
+.fi
+.PP
+.BR fdatasync ():
+.nf
+ _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500
+.fi
+.SH DESCRIPTION
+.BR fsync ()
+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
+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.
+.PP
+As well as flushing the file data,
+.BR fsync ()
+also flushes the metadata information associated with the file (see
+.BR inode (7)).
+.PP
+Calling
+.BR fsync ()
+does not necessarily ensure
+that the entry in the directory containing the file has also reached disk.
+For that an explicit
+.BR fsync ()
+on a file descriptor for the directory is also needed.
+.PP
+.BR fdatasync ()
+is similar to
+.BR fsync (),
+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
+or
+.I st_mtime
+(respectively, time of last access and
+time of last modification; see
+.BR inode (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
+.RI ( st_size ,
+as made by say
+.BR ftruncate (2)),
+would require a metadata flush.
+.PP
+The aim of
+.BR fdatasync ()
+is to reduce disk activity for applications that do not
+require all metadata to be synchronized with the disk.
+.SH RETURN VALUE
+On success, these system calls return zero.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EBADF
+.I fd
+is not a valid open file descriptor.
+.TP
+.B EINTR
+The function was interrupted by a signal; see
+.BR signal (7).
+.TP
+.B EIO
+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,
+.\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750
+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.
+.TP
+.B ENOSPC
+Disk space was exhausted while synchronizing.
+.TP
+.BR EROFS ", " EINVAL
+.I fd
+is bound to a special file (e.g., a pipe, FIFO, or socket)
+which does not support synchronization.
+.TP
+.BR ENOSPC ", " EDQUOT
+.I fd
+is bound to a file on NFS or another filesystem which does not allocate
+space at the time of a
+.BR write (2)
+system call, and some previous write failed due to insufficient
+storage space.
+.SH VERSIONS
+On POSIX systems on which
+.BR fdatasync ()
+is available,
+.B _POSIX_SYNCHRONIZED_IO
+is defined in
+.I <unistd.h>
+to a value greater than 0.
+(See also
+.BR sysconf (3).)
+.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
+.\" -1: unavailable, 0: ask using sysconf().
+.\" glibc defines them to 1.
+.PP
+On some UNIX systems (but not Linux),
+.I fd
+must be a
+.I writable
+file descriptor.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, 4.3BSD.
+.PP
+In Linux 2.2 and earlier,
+.BR fdatasync ()
+is equivalent to
+.BR fsync (),
+and so has no performance advantage.
+.PP
+The
+.BR fsync ()
+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
+.BR hdparm (8)
+or
+.BR sdparm (8)
+to guarantee safe operation.
+.SH SEE ALSO
+.BR sync (1),
+.BR bdflush (2),
+.BR open (2),
+.BR posix_fadvise (2),
+.BR pwritev (2),
+.BR sync (2),
+.BR sync_file_range (2),
+.BR fflush (3),
+.BR fileno (3),
+.BR hdparm (8),
+.BR mount (8)