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!)

lib/libc/sys/sync.2

@@ -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 @@ The function
 .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
-may return before the buffers are completely flushed.
+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
+does not return until all buffers have been written.