lib/libc/sys/fsync.2

   1 .\" Copyright (c) 1983, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
   4 .\"
   5 .\" Parts of this documentation were written by
   6 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
   7 .\" from the FreeBSD Foundation.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)fsync.2     8.1 (Berkeley) 6/4/93
  34 .\"
  35 .Dd March 30, 2020
  36 .Dt FSYNC 2
  37 .Os
  38 .Sh NAME
  39 .Nm fdatasync ,
  40 .Nm fsync
  41 .Nd "synchronise changes to a file"
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In unistd.h
  46 .Ft int
  47 .Fn fdatasync "int fd"
  48 .Ft int
  49 .Fn fsync "int fd"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn fsync
  53 system call
  54 causes all modified data and attributes of the file referenced by
  55 the file descriptor
  56 .Fa fd
  57 to be moved to a permanent storage device.
  58 This normally results in all in-core modified copies
  59 of buffers for the associated file to be written to a disk.
  60 .Pp
  61 The
  62 .Fn fdatasync
  63 system call causes all modified data of
  64 .Fa fd
  65 to be moved to a permanent storage device.
  66 Unlike
  67 .Fn fsync ,
  68 the system call does not guarantee that file attributes or
  69 metadata necessary to access the file are committed to the permanent storage.
  70 .Pp
  71 The
  72 .Fn fsync
  73 system call
  74 should be used by programs that require a file to be
  75 in a known state, for example, in building a simple transaction
  76 facility.
  77 If the file metadata has already been committed, using
  78 .Fn fdatasync
  79 can be more efficient than
  80 .Fn fsync .
  81 .Pp
  82 Both
  83 .Fn fdatasync
  84 and
  85 .Fn fsync
  86 calls are cancellation points.
  87 .Sh RETURN VALUES
  88 .Rv -std fsync
  89 .Sh ERRORS
  90 The
  91 .Fn fsync
  92 and
  93 .Fn fdatasync
  94 calls fail if:
  95 .Bl -tag -width Er
  96 .It Bq Er EBADF
  97 The
  98 .Fa fd
  99 argument
 100 is not a valid descriptor.
 101 .It Bq Er EINVAL
 102 The
 103 .Fa fd
 104 argument
 105 refers to a socket, not to a file.
 106 .It Bq Er EIO
 107 An I/O error occurred while reading from or writing to the file system.
 108 .It Bq Er EINTEGRITY
 109 Corrupted data was detected while reading from the file system.
 110 .El
 111 .Sh SEE ALSO
 112 .Xr fsync 1 ,
 113 .Xr sync 2 ,
 114 .Xr syncer 4 ,
 115 .Xr sync 8
 116 .Sh HISTORY
 117 The
 118 .Fn fsync
 119 system call appeared in
 120 .Bx 4.2 .
 121 The
 122 .Fn fdatasync
 123 system call appeared in
 124 .Fx 11.1 .
 125 .Sh BUGS
 126 The
 127 .Fn fdatasync
 128 system call currently does not guarantee that enqueued
 129 .Xr aio 4
 130 requests for the file referenced by
 131 .Fa fd
 132 are completed before the syscall returns.