FSYNC(2,L)                  AIX Technical Reference                  FSYNC(2,L)



-------------------------------------------------------------------------------
fsync, fcommit



PURPOSE

Writes changes in a file to permanent storage.

SYNTAX

int fsync (fildes)
int fildes;

int fcommit (fildes)
int fildes;

DESCRIPTION

The fsync system call causes all modified data in the file open on fildes to be
saved to permanent storage.  The fcommit system call is a synonym for the fsync
system call.  Saving to permanent storage is sometimes called a commit
operation.

An fsync system call can be issued by a process executing at the node on which
the file is stored or by a process executing at another node.  In either case,
the file is written to permanent storage at the node that holds the file.

If the file is open in O_DEFERC mode, fsync incorporates all data changes into
a new version of the file.  Old pages are freed and become unrecoverable.  The
file must be a regular file, not a pipe or special file, and the file
descriptor must be open for writing.  If the file has not been changed since it
was open or last committed, this operation has no effect.

The file remains open after the fsync and a subsequent fabort system call on
this file will roll back the file only to the latest commit checkpoint.  fsync
and fabort only affect the file's content and, except for the file's size,
modification time and file status change time, the other file information is
unaffected.  Changes effected by system calls such as chmod, chown, and utime
are atomic and are not aborted by fabort.

Changes made to a file opened with O_DEFERC are ordinarily made permanent when
the file is closed or soon after, and thus, an explicit fsync is not usually
necessary.  If the file is open multiple times, the commit occurs on the final
close of any write file descriptor.  If this final close of the file is not
done explicitly, but instead, the file is closed by exit, the file is still
committed.

The fsync system call may be used to make a checkpoint of a file.  This might
be useful to protect against system failure which might cause file changes to
be undone.  Furthermore, if the file is replicated on several sites, fsync
causes all copies of the file to be updated.  For a file that continues to be



Processed November 7, 1990        FSYNC(2,L)                                  1

FSYNC(2,L)                  AIX Technical Reference                  FSYNC(2,L)



open for a long time, checkpoints will tend to keep the copies of the file more
closely up to date.  This may be important if the network later becomes
partitioned and some user or process is unable to access the latest version of
the file.  The user still may be able to access a more recent version of the
file than could have been accessed in the absence of the checkpoint.

The fsync system call does not return until the file has been successfully
updated at a site storing the file.  If the file is replicated, the primary
copy is written synchronously and other copies of the file are updated
asynchronously as the other sites storing the file request the changed file.  A
usage pattern with rapid, repetitive commits on a replicated file will probably
be inefficient and should be avoided.  Rapid commits may cause a slow or loaded
site to skip a version of a file.  If this happens, the secondary copy of the
file is updated by propagating the entire file, rather than by propagating just
the changed pages, as would be the case if the secondary copy was just one
version out of date.

Warning:  If the file is open both in O_DEFERC mode and the default open mode
(O_DEFERC is not set in the open system call), by the same or different
processes, changes may be written to permanent storage other than when an fsync
system call is issued.  Concurrent opens of this form should be avoided.

RETURN VALUE

Upon successful completion, fsync returns a value of 0.  If fsync fails, a
value of -1 is returned and errno is set to indicate the error.

ERROR CONDITIONS

The fsync system call fails if one or more of the following are true:

EIO     I/O error.

EBADF   fildes is not a valid file descriptor open for writing.

EINVAL  fildes refers to a socket, not to a file.

ENOSPC  There is no more space left on the file system.

If the Transparent Computing Facility is installed on your system, fsync can
also fail if one or more of the following are true:

ESITEDN1
        The storage site is down or has gone down since this file descriptor
        was issued.

ESITEDN2
        The operation was terminated because a site failed.

RELATED INFORMATION

In this book:  "close, closex," "fabort," "open, openx, creat," and "sync."



Processed November 7, 1990        FSYNC(2,L)                                  2