lib/libc/sys/fsync.2

   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
  49 causes all modified data and attributes of
  50 .Fa fd
  51 to be moved to a permanent storage device.
  52 This normally results in all in-core modified copies
  53 of buffers for the associated file to be written to a disk.
  54 .Pp
  55 .Fn fsync
  56 should be used by programs that require a file to be
  57 in a known state, for example, in building a simple transaction
  58 facility.
  59 .Pp
  60 .Fn fsync_range
  61 causes all modified data starting at
  62 .Fa start
  63 for length
  64 .Fa length
  65 of
  66 .Fa fd
  67 to be written to permanent storage.
  68 Note that
  69 .Fn fsync_range
  70 requires that the file
  71 .Fa fd
  72 must be open for writing.
  73 .Pp
  74 .Fn fsync_range
  75 may flush the file data in one of two manners:
  76 .Bl -tag -width FDATASYNC -offset indent
  77 .It Dv FDATASYNC
  78 Synchronize the file data and sufficient meta-data to retrieve the
  79 data for the specified range.
  80 .It Dv FFILESYNC
  81 Synchronize all modified file data and meta-data for the specified range.
  82 .El
  83 .Pp
  84 By default,
  85 .Fn fsync_range
  86 does not flush disk caches, assuming that storage media are able to ensure
  87 completed writes are transfered to media.
  88 The
  89 .Dv FDISKSYNC
  90 flag may be included in the
  91 .Fa how
  92 parameter to trigger flushing of all disk caches for the file.
  93 .Pp
  94 If the
  95 .Fa length
  96 parameter is zero,
  97 .Fn fsync_range
  98 will synchronize all of the file data.
  99 .Sh RETURN VALUES
 100 A 0 value is returned on success.
 101 A \-1 value indicates an error.
 102 .Sh ERRORS
 103 .Fn fsync
 104 or
 105 .Fn fsync_range
 106 fail if:
 107 .Bl -tag -width Er
 108 .It Bq Er EBADF
 109 .Fa fd
 110 is not a valid descriptor.
 111 .It Bq Er EINVAL
 112 .Fa fd
 113 refers to a socket, not to a file.
 114 .It Bq Er EIO
 115 An I/O error occurred while reading from or writing to the file system.
 116 .El
 117 .Pp
 118 Additionally,
 119 .Fn fsync_range
 120 fails if:
 121 .Bl -tag -width Er
 122 .It Bq Er EBADF
 123 .Fa fd
 124 is not open for writing.
 125 .It Bq Er EINVAL
 126 .Fa start
 127 +
 128 .Fa length
 129 is less than
 130 .Fa start .
 131 .El
 132 .Sh NOTES
 133 For optimal efficiency, the
 134 .Fn fsync_range
 135 call requires that the file system containing the file referenced by
 136 .Fa fd
 137 support partial synchronization of file data.
 138 For file systems which do
 139 not support partial synchronization, the entire file will be synchronized
 140 and 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
 146 The
 147 .Fn fsync
 148 function call appeared in
 149 .Bx 4.2 .
 150 .Pp
 151 The
 152 .Fn fsync_range
 153 function call first appeared in
 154 .Nx 2.0
 155 and is modeled after the function available in AIX.