xnu-6153.11.26.tar.gz

[apple/xnu.git] / bsd / man / man2 / fsync.2

diff --git a/bsd/man/man2/fsync.2 b/bsd/man/man2/fsync.2
index 3f4b0d69455dd0549bff1b69c4eeb34912f0c51f..c772a497e66388eda0f74ab655da86988452c1ce 100644 (file)
--- a/bsd/man/man2/fsync.2
+++ b/bsd/man/man2/fsync.2
@@ -42,38 +42,83 @@
 .Sh SYNOPSIS
 .Fd #include <unistd.h>
 .Ft int
-.Fn fsync "int fd"
+.Fo fsync
+.Fa "int fildes"
+.Fc
 .Sh DESCRIPTION
-.Fn Fsync
+.Fn fsync
 causes all modified data and attributes of
-.Fa fd
+.Fa fildes
 to be moved to a permanent storage device.
 This normally results in all in-core modified copies
 of buffers for the associated file to be written to a disk.
 .Pp
-.Fn Fsync
-should be used by programs that require a file to be
-in a known state, for example, in building a simple transaction
-facility.
+Note that while
+.Fn fsync
+will flush all data from the host to the drive
+(i.e. the "permanent storage device"),
+the drive itself may not physically write the data
+to the platters for quite some time
+and it may be written in an out-of-order sequence.
+.Pp
+Specifically, if the drive loses power
+or the OS crashes,
+the application may find that only some or none of their data was written.
+The disk drive may also re-order the data
+so that later writes may be present, while earlier writes are not.
+.Pp
+This is not a theoretical edge case.
+This scenario is easily reproduced with real world workloads
+and drive power failures.
+.Pp
+For applications that require tighter guarantees
+about the integrity of their data,
+Mac OS X provides the F_FULLFSYNC fcntl.
+The F_FULLFSYNC fcntl asks the drive to flush all buffered data
+to permanent storage.
+Applications, such as databases,
+that require a strict ordering of writes
+should use F_FULLFSYNC to ensure that their data
+is written in the order they expect.
+Please see
+.Xr fcntl 2
+for more detail.
+.Pp
 .Sh RETURN VALUES
-A 0 value is returned on success.  A -1 value indicates
-an error.
+.Rv -std fsync
 .Sh ERRORS
 The
 .Fn fsync
-fails if:
+system call will fail if:
 .Bl -tag -width Er
+.\" ==========
 .It Bq Er EBADF
-.Fa Fd
+.Fa fildes
 is not a valid descriptor.
+.\" ==========
+.It Bq Er EINTR
+Its execution is interrupted by a signal.
+.\" ==========
 .It Bq Er EINVAL
-.Fa Fd
-refers to a socket, not to a file.
+.Fa fildes
+refers to a file type (e.g., a socket)
+that does not support this operation.
+.\" ==========
 .It Bq Er EIO
 An I/O error occurred while reading from or writing to the file system.
 .El
+.Pp
+If a queued I/O operation fails,
+.Fn fsync
+may fail with any of the errors defined for
+.Xr read 2
+or
+.Xr write 2 .
 .Sh SEE ALSO
+.Xr fcntl 2 ,
+.Xr read 2 ,
 .Xr sync 2 ,
+.Xr write 2 ,
 .Xr sync 8 ,
 .Xr update 8
 .Sh HISTORY