NetBSD/lib/libc/sys/fsync.2

.\"	$NetBSD: fsync.2,v 1.21 2021/02/17 22:55:20 wiz 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 February 17, 2021
.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 written 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_range
is similar, but provides control over the region of the file
to be synchronized, and the method of synchronization.
.Pp
These functions should be used by programs that require a file to be
in a known state, for example, in building a simple transaction
facility.
.Pp
Note that writing the data to a permanent storage device
does not necessarily write the data to permanent storage media
within that device;
for example, after writing data to a disk device, the data might
reside in a cache within the device, but not yet on
more permanent storage within the device.
Neither
.Fn fsync
nor the default behavior of
.Fn fsync_range
(without the
.Dv FDISKSYNC
flag)
will flush disk caches,
because they assume that storage devices are able to ensure that
completed writes are transferred to media some time between the
write and a power failure or system crash.
.Pp
.Fn fsync_range
causes all modified data starting at
.Fa start
for length
.Fa length
of
.Fa fd
to be written to a permanent storage device.
If the
.Fa length
parameter is zero,
.Fn fsync_range
will synchronize all of the file data.
.Pp
.Fn fsync_range
takes a
.Fa how
parameter which contains one or more of the following flags:
.Bl -tag -width FDATASYNC -offset indent
.It Dv FDATASYNC
Synchronize the file data and sufficient meta-data to retrieve the
data for the specified range.
This is equivalent to
.Xr fdatasync 2
on the specified range.
.It Dv FFILESYNC
Synchronize all modified file data and meta-data for the specified range.
This is equivalent to
.Nm
on the specified range.
.It Dv FDISKSYNC
Request the destination device to ensure that the relevant data
and meta-data is flushed from any cache to permanent storage media.
In the present implementation, the entire cache on the affected device will
be flushed, and this may have a significant impact on performance.
.El
.Pp
The
.Dv FDATASYNC
and
.Dv FFILESYNC
flags are mutually exclusive.
Either of those flags may be combined with the
.Dv FDISKSYNC
flag.
.Pp
Note that
.Fn fsync_range
requires that the file
.Fa fd
must be open for writing, whereas
.Fn fsync
does not.
.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
is less than zero, or
.Fa start
+
.Fa length
is less than
.Fa start
or triggers an integer overflow; or
.Fa how
contains an invalid value.
.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 fdatasync 2 ,
.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.