share/man/man3c/fsync.3c

   1 '\" te
   2 .\" Copyright (c) 2008 Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH FSYNC 3C "Feb 5, 2008"
   8 .SH NAME
   9 fsync \- synchronize changes to a file
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <unistd.h>
  14
  15 \fBint\fR \fBfsync\fR(\fBint\fR \fIfildes\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBfsync()\fR function moves all modified data and attributes of the file
  22 descriptor \fIfildes\fR to a storage device. When \fBfsync()\fR returns, all
  23 in-memory modified copies of buffers associated with \fIfildes\fR have been
  24 written to the physical medium. The \fBfsync()\fR function is different from
  25 \fBsync()\fR, which schedules disk I/O for all files  but returns before the
  26 I/O completes. The \fBfsync()\fR function forces all outstanding data
  27 operations to synchronized file integrity completion (see \fBfcntl.h\fR(3HEAD)
  28 definition of \fBO_SYNC\fR.)
  29 .sp
  30 .LP
  31 The \fBfsync()\fR function forces all currently queued I/O operations
  32 associated with the file indicated by the file descriptor \fIfildes\fR to the
  33 synchronized I/O completion state. All I/O operations are completed as defined
  34 for synchronized I/O file integrity completion.
  35 .SH RETURN VALUES
  36 .sp
  37 .LP
  38 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
  39 returned and \fBerrno\fR is set to indicate the error. If the \fBfsync()\fR
  40 function fails, outstanding I/O operations are not guaranteed to have been
  41 completed.
  42 .SH ERRORS
  43 .sp
  44 .LP
  45 The \fBfsync()\fR function will fail if:
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fBEBADF\fR\fR
  50 .ad
  51 .RS 13n
  52 The \fIfildes\fR argument is not a valid file descriptor.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fBEINTR\fR\fR
  59 .ad
  60 .RS 13n
  61 A signal was caught during execution of the \fBfsync()\fR function.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fBEIO\fR\fR
  68 .ad
  69 .RS 13n
  70 An I/O error occurred while reading from or writing to the file system.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fBENOSPC\fR\fR
  77 .ad
  78 .RS 13n
  79 There was no free space remaining on the device containing the file.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBETIMEDOUT\fR\fR
  86 .ad
  87 .RS 13n
  88 Remote connection timed out. This occurs when the file is on an  \fBNFS\fR file
  89 system mounted with the  \fIsoft\fR option. See  \fBmount_nfs\fR(8).
  90 .RE
  91
  92 .sp
  93 .LP
  94 In the event that any of the queued I/O operations fail, \fBfsync()\fR returns
  95 the error conditions defined for \fBread\fR(2) and \fBwrite\fR(2).
  96 .SH USAGE
  97 .sp
  98 .LP
  99 The \fBfsync()\fR function should be used by applications that require that a
 100 file be in a known state. For example, an application that contains a simple
 101 transaction facility might use  \fBfsync()\fR to ensure that all changes to a
 102 file or files caused by a given transaction were recorded on a storage medium.
 103 .sp
 104 .LP
 105 The manner in which the data reach the physical medium depends on both
 106 implementation and hardware.  The \fBfsync()\fR function returns when notified
 107 by the device driver that the write has taken place.
 108 .SH ATTRIBUTES
 109 .sp
 110 .LP
 111 See \fBattributes\fR(5) for descriptions of the following attributes:
 112 .sp
 113
 114 .sp
 115 .TS
 116 box;
 117 c | c
 118 l | l .
 119 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 120 _
 121 Interface Stability     Committed
 122 _
 123 MT-Level        Async-Signal-Safe
 124 _
 125 Standard        See \fBstandards\fR(5).
 126 .TE
 127
 128 .SH SEE ALSO
 129 .sp
 130 .LP
 131 \fBmount_nfs\fR(8), \fBread\fR(2), \fBsync\fR(2), \fBwrite\fR(2),
 132 \fBfcntl.h\fR(3HEAD), \fBfdatasync\fR(3C), \fBattributes\fR(5),
 133 \fBstandards\fR(5)