1.\" $NetBSD: fsync.2,v 1.15 2003/11/18 08:49:18 wiz Exp $ 2.\" 3.\" Copyright (c) 1983, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)fsync.2 8.1 (Berkeley) 6/4/93 31.\" 32.Dd November 14, 2003 33.Dt FSYNC 2 34.Os 35.Sh NAME 36.Nm fsync , 37.Nm fsync_range 38.Nd "synchronize a file's in-core state with that on disk" 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Ft int 44.Fn fsync "int fd" 45.Ft int 46.Fn fsync_range "int fd" "int how" "off_t start" "off_t length" 47.Sh DESCRIPTION 48.Fn fsync 49causes all modified data and attributes of 50.Fa fd 51to be moved to a permanent storage device. 52This normally results in all in-core modified copies 53of buffers for the associated file to be written to a disk. 54.Pp 55.Fn fsync 56should be used by programs that require a file to be 57in a known state, for example, in building a simple transaction 58facility. 59.Pp 60.Fn fsync_range 61causes all modified data starting at 62.Fa start 63for length 64.Fa length 65of 66.Fa fd 67to be written to permanent storage. 68Note that 69.Fn fsync_range 70requires that the file 71.Fa fd 72must be open for writing. 73.Pp 74.Fn fsync_range 75may flush the file data in one of two manners: 76.Bl -tag -width FDATASYNC 77.It Dv FDATASYNC 78Synchronize the file data and sufficient meta-data to retrieve the 79data for the specified range. 80.It Dv FFILESYNC 81Synchronize all modified file data and meta-data for the specified range. 82.El 83.Pp 84If the 85.Fa length 86parameter is zero, 87.Fn fsync_range 88will synchronize all of the file data. 89.Sh RETURN VALUES 90A 0 value is returned on success. 91A \-1 value indicates an error. 92.Sh ERRORS 93.Fn fsync 94or 95.Fn fsync_range 96fail if: 97.Bl -tag -width Er 98.It Bq Er EBADF 99.Fa fd 100is not a valid descriptor. 101.It Bq Er EINVAL 102.Fa fd 103refers to a socket, not to a file. 104.It Bq Er EIO 105An I/O error occurred while reading from or writing to the file system. 106.El 107.Pp 108Additionally, 109.Fn fsync_range 110fails if: 111.Bl -tag -width Er 112.It Bq Er EBADF 113.Fa fd 114is not open for writing. 115.It Bq Er EINVAL 116.Fa start 117+ 118.Fa length 119is less than 120.Fa start . 121.El 122.Sh NOTES 123For optimal efficiency, the 124.Fn fsync_range 125call requires that the file system containing the file referenced by 126.Fa fd 127support partial synchronization of file data. 128For file systems which do 129not support partial synchronization, the entire file will be synchronized 130and the call will be the equivalent of calling 131.Fn fsync . 132.Sh SEE ALSO 133.Xr sync 2 , 134.Xr sync 8 135.Sh HISTORY 136The 137.Fn fsync 138function call appeared in 139.Bx 4.2 . 140.Pp 141The 142.Fn fsync_range 143function call first appeared in 144.Nx 2.0 145and is modeled after the function available in AIX. 146