Return to fsync.2 CVS log

Up to [cvs.NetBSD.org] / src / lib / libc / sys

Extend fsync_range(2) to support the FDISKSYNC flag, which requests
that the sync be propogated out through the disk drive caches.

.\"	$NetBSD: fsync.2,v 1.16 2005/01/25 23:55:20 wrstuden Exp $
.\"
.\" Copyright (c) 1983, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)fsync.2	8.1 (Berkeley) 6/4/93
.\"
.Dd November 14, 2003
.Dt FSYNC 2
.Os
.Sh NAME
.Nm fsync ,
.Nm fsync_range
.Nd "synchronize a file's in-core state with that on disk"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fn fsync "int fd"
.Ft int
.Fn fsync_range "int fd" "int how" "off_t start" "off_t length"
.Sh DESCRIPTION
.Fn fsync
causes all modified data and attributes of
.Fa fd
to be moved to a permanent storage device.
This normally results in all in-core modified copies
of buffers for the associated file to be written to a disk.
.Pp
.Fn fsync
should be used by programs that require a file to be
in a known state, for example, in building a simple transaction
facility.
.Pp
.Fn fsync_range
causes all modified data starting at
.Fa start
for length
.Fa length
of
.Fa fd
to be written to permanent storage.
Note that
.Fn fsync_range
requires that the file
.Fa fd
must be open for writing.
.Pp
.Fn fsync_range
may flush the file data in one of two manners:
.Bl -tag -width FDATASYNC
.It Dv FDATASYNC
Synchronize the file data and sufficient meta-data to retrieve the
data for the specified range.
.It Dv FFILESYNC
Synchronize all modified file data and meta-data for the specified range.
.El
.Pp
By default,
.Fn fsync_range
does not flush disk caches, assuming that storage media are able to ensure
completed writes are transfered to media.
The
.Fa FDISKSYNC
flag may be included in the
.Fa how
parameter to trigger flushing of all disk caches for the file.
.Pp
If the
.Fa length
parameter is zero,
.Fn fsync_range
will synchronize all of the file data.
.Sh RETURN VALUES
A 0 value is returned on success.
A \-1 value indicates an error.
.Sh ERRORS
.Fn fsync
or
.Fn fsync_range
fail if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa fd
is not a valid descriptor.
.It Bq Er EINVAL
.Fa fd
refers to a socket, not to a file.
.It Bq Er EIO
An I/O error occurred while reading from or writing to the file system.
.El
.Pp
Additionally,
.Fn fsync_range
fails if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa fd
is not open for writing.
.It Bq Er EINVAL
.Fa start
+
.Fa length
is less than
.Fa start .
.El
.Sh NOTES
For optimal efficiency, the
.Fn fsync_range
call requires that the file system containing the file referenced by
.Fa fd
support partial synchronization of file data.
For file systems which do
not support partial synchronization, the entire file will be synchronized
and the call will be the equivalent of calling
.Fn fsync .
.Sh SEE ALSO
.Xr sync 2 ,
.Xr sync 8
.Sh HISTORY
The
.Fn fsync
function call appeared in
.Bx 4.2 .
.Pp
The
.Fn fsync_range
function call first appeared in
.Nx 2.0
and is modeled after the function available in AIX.