1.\" $NetBSD: fsync.2,v 1.17 2010/05/17 12:38:04 jruoho 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 May 17, 2010 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 -offset indent 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 84By default, 85.Fn fsync_range 86does not flush disk caches, assuming that storage media are able to ensure 87completed writes are transfered to media. 88The 89.Dv FDISKSYNC 90flag may be included in the 91.Fa how 92parameter to trigger flushing of all disk caches for the file. 93.Pp 94If the 95.Fa length 96parameter is zero, 97.Fn fsync_range 98will synchronize all of the file data. 99.Sh RETURN VALUES 100A 0 value is returned on success. 101A \-1 value indicates an error. 102.Sh ERRORS 103.Fn fsync 104or 105.Fn fsync_range 106fail if: 107.Bl -tag -width Er 108.It Bq Er EBADF 109.Fa fd 110is not a valid descriptor. 111.It Bq Er EINVAL 112.Fa fd 113refers to a socket, not to a file. 114.It Bq Er EIO 115An I/O error occurred while reading from or writing to the file system. 116.El 117.Pp 118Additionally, 119.Fn fsync_range 120fails if: 121.Bl -tag -width Er 122.It Bq Er EBADF 123.Fa fd 124is not open for writing. 125.It Bq Er EINVAL 126.Fa start 127+ 128.Fa length 129is less than 130.Fa start . 131.El 132.Sh NOTES 133For optimal efficiency, the 134.Fn fsync_range 135call requires that the file system containing the file referenced by 136.Fa fd 137support partial synchronization of file data. 138For file systems which do 139not support partial synchronization, the entire file will be synchronized 140and the call will be the equivalent of calling 141.Fn fsync . 142.Sh SEE ALSO 143.Xr sync 2 , 144.Xr sync 8 145.Sh HISTORY 146The 147.Fn fsync 148function call appeared in 149.Bx 4.2 . 150.Pp 151The 152.Fn fsync_range 153function call first appeared in 154.Nx 2.0 155and is modeled after the function available in AIX. 156