diff options
Diffstat (limited to 'man/man2/fsync.2')
| -rw-r--r-- | man/man2/fsync.2 | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/man/man2/fsync.2 b/man/man2/fsync.2 new file mode 100644 index 000000000..e8d19bcc8 --- /dev/null +++ b/man/man2/fsync.2 @@ -0,0 +1,200 @@ +.\" 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 (date) "Linux man-pages (unreleased)" +.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> +.P +.BI "int fsync(int " fd ); +.P +.BI "int fdatasync(int " fd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.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 +.P +.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. +.P +As well as flushing the file data, +.BR fsync () +also flushes the metadata information associated with the file (see +.BR inode (7)). +.P +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. +.P +.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. +.P +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 +.B EROFS +.TQ +.B EINVAL +.I fd +is bound to a special file (e.g., a pipe, FIFO, or socket) +which does not support synchronization. +.TP +.B ENOSPC +.TQ +.B 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. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.2BSD. +.P +In Linux 2.2 and earlier, +.BR fdatasync () +is equivalent to +.BR fsync (), +and so has no performance advantage. +.P +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. +.P +Under AT&T UNIX System V Release 4 +.I fd +needs to be opened for writing. +This is by itself incompatible with the original BSD interface +and forbidden by POSIX, +but nevertheless survives in HP-UX and AIX. +.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) |