2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "FSYNC" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" fsync
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
fsync \- synchronize changes to a file
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fB#include <unistd.h>
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
int fsync(int\fP \fIfildes\fP\fB); \fP
|
|
|
|
\fB
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIfsync\fP() function shall request that all data for the open
|
|
|
|
file descriptor named by \fIfildes\fP is to be transferred
|
|
|
|
to the storage device associated with the file described by \fIfildes\fP
|
|
|
|
in an implementation-defined manner. The \fIfsync\fP()
|
|
|
|
function shall not return until the system has completed that action
|
|
|
|
or until an error is detected.
|
|
|
|
.LP
|
|
|
|
If _POSIX_SYNCHRONIZED_IO is defined, the \fIfsync\fP() function shall
|
|
|
|
force all currently queued I/O operations associated with
|
|
|
|
the file indicated by file descriptor \fIfildes\fP to the synchronized
|
|
|
|
I/O completion state. All I/O operations shall be completed
|
|
|
|
as defined for synchronized I/O file integrity completion.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.LP
|
|
|
|
Upon successful completion, \fIfsync\fP() shall return 0. Otherwise,
|
|
|
|
-1 shall be returned and \fIerrno\fP set to indicate the
|
|
|
|
error. If the \fIfsync\fP() function fails, outstanding I/O operations
|
|
|
|
are not guaranteed to have been completed.
|
|
|
|
.SH ERRORS
|
|
|
|
.LP
|
|
|
|
The \fIfsync\fP() function shall fail if:
|
|
|
|
.TP 7
|
|
|
|
.B EBADF
|
|
|
|
The \fIfildes\fP argument is not a valid descriptor.
|
|
|
|
.TP 7
|
|
|
|
.B EINTR
|
|
|
|
The \fIfsync\fP() function was interrupted by a signal.
|
|
|
|
.TP 7
|
|
|
|
.B EINVAL
|
|
|
|
The \fIfildes\fP argument does not refer to a file on which this operation
|
|
|
|
is possible.
|
|
|
|
.TP 7
|
|
|
|
.B EIO
|
|
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
In the event that any of the queued I/O operations fail, \fIfsync\fP()
|
|
|
|
shall return the error conditions defined for \fIread\fP() and \fIwrite\fP().
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
The \fIfsync\fP() function should be used by programs which require
|
|
|
|
modifications to a file to be completed before continuing;
|
|
|
|
for example, a program which contains a simple transaction facility
|
|
|
|
might use it to ensure that all modifications to a file or
|
|
|
|
files caused by a transaction are recorded.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
The \fIfsync\fP() function is intended to force a physical write of
|
|
|
|
data from the buffer cache, and to assure that after a
|
|
|
|
system crash or other failure that all data up to the time of the
|
|
|
|
\fIfsync\fP() call is recorded on the disk. Since the concepts
|
|
|
|
of "buffer cache", "system crash", "physical write", and "non-volatile
|
|
|
|
storage" are not defined here, the wording has to be
|
|
|
|
more abstract.
|
|
|
|
.LP
|
|
|
|
If _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily
|
|
|
|
on the conformance document to tell the user what can be
|
|
|
|
expected from the system. It is explicitly intended that a null implementation
|
|
|
|
is permitted. This could be valid in the case where
|
|
|
|
the system cannot assure non-volatile storage under any circumstances
|
|
|
|
or when the system is highly fault-tolerant and the
|
|
|
|
functionality is not required. In the middle ground between these
|
|
|
|
extremes, \fIfsync\fP() might or might not actually cause data
|
|
|
|
to be written where it is safe from a power failure. The conformance
|
|
|
|
document should identify at least that one configuration
|
|
|
|
exists (and how to obtain that configuration) where this can be assured
|
|
|
|
for at least some files that the user can select to use for
|
|
|
|
critical data. It is not intended that an exhaustive list is required,
|
|
|
|
but rather sufficient information is provided so that if
|
|
|
|
critical data needs to be saved, the user can determine how the system
|
|
|
|
is to be configured to allow the data to be written to
|
|
|
|
non-volatile storage.
|
|
|
|
.LP
|
|
|
|
It is reasonable to assert that the key aspects of \fIfsync\fP() are
|
|
|
|
unreasonable to test in a test suite. That does not make
|
|
|
|
the function any less valuable, just more difficult to test. A formal
|
|
|
|
conformance test should probably force a system crash (power
|
|
|
|
shutdown) during the test for this condition, but it needs to be done
|
|
|
|
in such a way that automated testing does not require this to
|
|
|
|
be done except when a formal record of the results is being made.
|
|
|
|
It would also not be unreasonable to omit testing for
|
|
|
|
\fIfsync\fP(), allowing it to be treated as a quality-of-implementation
|
|
|
|
issue.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
|
|
|
\fIsync\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
|
|
\fI<unistd.h>\fP
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|