| .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and |
| .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| fsync, fdatasync \- synchronize a file's in-core state with storage device |
| .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 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 CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, 4.3BSD. |
| .PP |
| 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 NOTES |
| On some UNIX systems (but not Linux), |
| .I fd |
| must be a |
| .I writable |
| file descriptor. |
| .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) |