Module Name: src
Committed By: dholland
Date: Wed Mar 25 05:32:52 UTC 2009
Modified Files:
src/lib/libc/sys: sync.2
Log Message:
Update the note about sync returning before buffers are written: it is a
piece of historical behavior, not a current bug. Also, while here, add a
bit about disk write-back caches and point to dkctl/scsictl.
Bump date. (first time since 1993!)
To generate a diff of this commit:
cvs rdiff -u -r1.15 -r1.16 src/lib/libc/sys/sync.2
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/sys/sync.2
diff -u src/lib/libc/sys/sync.2:1.15 src/lib/libc/sys/sync.2:1.16
--- src/lib/libc/sys/sync.2:1.15 Thu Aug 7 16:44:10 2003
+++ src/lib/libc/sys/sync.2 Wed Mar 25 05:32:52 2009
@@ -1,4 +1,4 @@
-.\" $NetBSD: sync.2,v 1.15 2003/08/07 16:44:10 agc Exp $
+.\" $NetBSD: sync.2,v 1.16 2009/03/25 05:32:52 dholland Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -29,7 +29,7 @@
.\"
.\" @(#)sync.2 8.1 (Berkeley) 6/4/93
.\"
-.Dd June 4, 1993
+.Dd March 25, 2009
.Dt SYNC 2
.Os
.Sh NAME
@@ -64,14 +64,39 @@
.Xr fsync 2
may be used to synchronize individual file descriptor
attributes.
+.Sh CAUTIONS
+Many modern disks contain write-back caches.
+In theory
+.Fn sync
+flushes these.
+In practice there are many possible ways for this mechanism to go
+astray.
+It is prudent (where possible) to allow a few seconds after syncing
+for everything to settle before e.g. turning off the power.
+.Pp
+It may also be desirable to use
+.Xr dkctl 8
+or
+.Xr scsictl 8
+to disable the write-back cache entirely.
.Sh SEE ALSO
+.Xr dkctl 8 ,
.Xr fsync 2 ,
+.Xr scsictl 8 ,
.Xr sync 8
.Sh HISTORY
A
.Fn sync
function call appeared in
.At v6 .
-.Sh BUGS
+.Pp
+Historically,
+.Fn sync
+would schedule buffers for writing but not actually wait for the
+writes to finish.
+It was necessary to issue a second or sometimes a third call to ensure
+that all buffers had in fact been written out.
+In
+.Nx ,
.Fn sync
-may return before the buffers are completely flushed.
+does not return until all buffers have been written.
