2004-11-03 13:51:07 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
2006-04-27 23:31:05 +00:00
|
|
|
.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" 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-27 23:31:05 +00:00
|
|
|
.\" 2006-04-28, mtk, substantial rewrite of various parts.
|
2012-02-27 00:13:50 +00:00
|
|
|
.\" 2012-02-27 Various changes by Christoph Hellwig <hch@lst.de>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2012-02-27 00:13:50 +00:00
|
|
|
.TH FSYNC 2 2012-02-27 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2006-04-27 23:31:05 +00:00
|
|
|
fsync, fdatasync \- synchronize a file's in-core state with storage device
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <unistd.h>
|
|
|
|
.sp
|
|
|
|
.BI "int fsync(int " fd );
|
|
|
|
.sp
|
|
|
|
.BI "int fdatasync(int " fd );
|
2007-07-08 12:11:40 +00:00
|
|
|
.sp
|
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
|
|
|
.sp
|
|
|
|
.BR fsync ():
|
|
|
|
_BSD_SOURCE || _XOPEN_SOURCE
|
2008-11-08 02:42:33 +00:00
|
|
|
.br
|
|
|
|
|| /* since glibc 2.8: */ _POSIX_C_SOURCE\ >=\ 200112L
|
|
|
|
.\" _POSIX_C_SOURCE\ >=\ 200112L only since glibc 2.8
|
2007-07-08 12:11:40 +00:00
|
|
|
.br
|
|
|
|
.BR fdatasync ():
|
|
|
|
_POSIX_C_SOURCE\ >=\ 199309L || _XOPEN_SOURCE\ >=\ 500
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR fsync ()
|
2007-04-12 22:42:49 +00:00
|
|
|
transfers ("flushes") all modified in-core data of
|
|
|
|
(i.e., modified buffer cache pages for) the
|
2006-04-27 23:31:05 +00:00
|
|
|
file referred to by the file descriptor
|
|
|
|
.I fd
|
2012-02-27 00:11:14 +00:00
|
|
|
to the disk device (or other permanent storage device) so that all
|
|
|
|
changed information can be retrieved even after the system crashed or
|
2012-02-27 00:13:50 +00:00
|
|
|
was rebooted.
|
|
|
|
This includes writing through or flushing a disk cache if present.
|
2006-04-27 23:31:05 +00:00
|
|
|
The call blocks until the device reports that the transfer has completed.
|
2008-07-01 14:15:13 +00:00
|
|
|
It also flushes metadata information associated with the file (see
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR stat (2)).
|
2006-04-27 23:31:05 +00:00
|
|
|
|
2012-02-27 00:11:14 +00:00
|
|
|
|
2006-04-27 23:31:05 +00:00
|
|
|
Calling
|
|
|
|
.BR fsync ()
|
|
|
|
does not necessarily ensure
|
2004-11-03 13:51:07 +00:00
|
|
|
that the entry in the directory containing the file has also reached disk.
|
|
|
|
For that an explicit
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR fsync ()
|
2006-04-27 23:31:05 +00:00
|
|
|
on a file descriptor for the directory is also needed.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR fdatasync ()
|
2007-04-12 22:42:49 +00:00
|
|
|
is similar to
|
2006-04-27 23:31:05 +00:00
|
|
|
.BR fsync (),
|
2007-04-12 22:42:49 +00:00
|
|
|
but does not flush modified metadata unless that metadata
|
2006-04-27 23:31:05 +00:00
|
|
|
is needed in order to allow a subsequent data retrieval to be
|
|
|
|
correctly handled.
|
2007-04-12 22:42:49 +00:00
|
|
|
For example, changes to
|
|
|
|
.I st_atime
|
|
|
|
or
|
2006-04-27 23:31:05 +00:00
|
|
|
.I st_mtime
|
2005-07-19 07:15:17 +00:00
|
|
|
(respectively, time of last access and
|
|
|
|
time of last modification; see
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR stat (2))
|
2007-03-01 01:12:16 +00:00
|
|
|
do not require flushing because they are not necessary for
|
2006-04-27 23:31:05 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
The aim of
|
2007-09-19 05:25:00 +00:00
|
|
|
.BR fdatasync ()
|
2006-04-27 23:31:05 +00:00
|
|
|
is to reduce disk activity for applications that do not
|
2007-06-08 09:56:56 +00:00
|
|
|
require all metadata to be synchronized with the disk.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
2007-07-08 19:32:37 +00:00
|
|
|
On success, these system calls return zero.
|
2007-04-12 22:42:49 +00:00
|
|
|
On error, \-1 is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
.I fd
|
2012-02-27 00:11:14 +00:00
|
|
|
is not a valid open file descriptor.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EIO
|
|
|
|
An error occurred during synchronization.
|
|
|
|
.TP
|
|
|
|
.BR EROFS ", " EINVAL
|
|
|
|
.I fd
|
|
|
|
is bound to a special file which does not support synchronization.
|
2007-05-18 16:06:42 +00:00
|
|
|
.SH "CONFORMING TO"
|
2008-07-15 13:39:17 +00:00
|
|
|
4.3BSD, POSIX.1-2001.
|
2007-07-08 19:32:37 +00:00
|
|
|
.SH AVAILABILITY
|
|
|
|
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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
2012-02-27 00:23:06 +00:00
|
|
|
On some UNIX systems (but not Linux),
|
|
|
|
.I fd
|
|
|
|
must be a
|
|
|
|
.I writable
|
|
|
|
file descriptor.
|
|
|
|
|
2007-07-08 19:32:37 +00:00
|
|
|
In Linux 2.2 and earlier,
|
|
|
|
.BR fdatasync ()
|
|
|
|
is equivalent to
|
2007-09-19 05:25:00 +00:00
|
|
|
.BR fsync (),
|
2007-07-08 19:32:37 +00:00
|
|
|
and so has no performance advantage.
|
2012-02-27 00:11:14 +00:00
|
|
|
|
|
|
|
The
|
|
|
|
.BR fsync ()
|
|
|
|
implementations in older kernels and lesser used filesystems
|
2012-02-27 00:13:50 +00:00
|
|
|
does not know how to flush disk caches.
|
|
|
|
In these cases disk caches need to be disabled using
|
2012-02-27 00:11:14 +00:00
|
|
|
.BR hdparm (8)
|
|
|
|
or
|
|
|
|
.BR sdparm (8)
|
|
|
|
to guarantee safe operation.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR bdflush (2),
|
|
|
|
.BR open (2),
|
2005-07-19 07:15:17 +00:00
|
|
|
.BR sync (2),
|
2006-07-06 09:34:33 +00:00
|
|
|
.BR sync_file_range (2),
|
2006-04-27 23:39:55 +00:00
|
|
|
.BR hdparm (8),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR mount (8),
|
|
|
|
.BR sync (8),
|
|
|
|
.BR update (8)
|