Man Linux: Main Page and Category List

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 .