NAME

       fsync - synchronize changes to a file

SYNOPSIS

       #include <unistd.h>

       int fsync(int fildes);

DESCRIPTION

       The  fsync()  function  shall request that all data for the open file descriptor named by fildes is to be
       transferred to the storage device associated with the file described  by  fildes  in  an  implementation-
       defined manner. The fsync() function shall not return until the system has completed that action or until
       an error is detected.

       If  _POSIX_SYNCHRONIZED_IO  is  defined,  the  fsync()  function  shall  force  all  currently queued I/O
       operations associated with the  file  indicated  by  file  descriptor  fildes  to  the  synchronized  I/O
       completion  state.  All  I/O operations shall be completed as defined for synchronized I/O file integrity
       completion.

RETURN VALUE

       Upon successful completion, fsync() shall return 0. Otherwise, -1 shall be  returned  and  errno  set  to
       indicate  the error. If the fsync() function fails, outstanding I/O operations are not guaranteed to have
       been completed.

ERRORS

       The fsync() function shall fail if:

       EBADF  The fildes argument is not a valid descriptor.

       EINTR  The fsync() function was interrupted by a signal.

       EINVAL The fildes argument does not refer to a file on which this operation is possible.

       EIO    An I/O error occurred while reading from or writing to the file system.

       In the event that any of the queued I/O operations  fail,  fsync()  shall  return  the  error  conditions
       defined for read() and write().

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The  fsync()  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.

RATIONALE

       The  fsync()  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 fsync() 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.

       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, fsync() 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.

       It is reasonable to assert that the key aspects of fsync() 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 fsync(), allowing it
       to be treated as a quality-of-implementation issue.

FUTURE DIRECTIONS

       None.

SEE ALSO

       sync() , the Base Definitions volume of IEEE Std 1003.1-2001, <unistd.h>

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 .

IEEE/The Open Group                                   2003                                              FSYNC(P)