Bug 165929

The man pages for msync(2) and mmap both say:

     The msync() system call is obsolete since BSD implements a coherent file
     system buffer cache.  However, it may be used to associate dirty VM pages
     with file system buffers and thus cause them to be flushed to physical
     media sooner rather than later.

To the contrary, if a process does not call msync with MS_SYNC, the
process has no way to verify that dirty pages are successfully
written.

Personally, I liken this to calling close(2) before exiting: while the
system will attempt to flush pages, there is no guarantee that a
mmapped file has been successfully written until after msync(_, _,
MS_SYNC) has returned.

To make this more significant, in FreeBSD 8.3-PRERELEASE, the bug
described in kern/165923 will prevent dirty regions on an NFS-backed
file from being flushed by the syncer in most common situations.
Calling msync explicitly avoids the bug.  However, even if that bug is
fixed, an msync is still necessary to verify that the pages have been
successfully written.

Note that, as of 8.3-PRERELEASE, an msync is not sufficient to verify
the write; cf kern/165927.  If the syncer daemon flushes a file and
fails before the process calls msync, then msync will wrongly report
success.  However, even if this is fixed, it's still appropriate to
call msync.

Fix: Remove the assertions in the mmap(2) and msync(2) man pages that
indicate that msync is obsolete.

If kern/165927 has not been fixed, it should be documented in the
msync manpage.

If kern/165923 has not been fixed, it may be useful to document it in
the msync manpage, since it will appear to the user that a call to
msync has no effect.

The enclosed patch makes these changes.
How-To-Repeat: A demonstration of the necessity of msync can be found using the
program from the "How-To-Repeat" program from kern/165923.

If kern/165923 has not been fixed, then comment out "#define
WAIT_FOR_SYNC".  Run the program (using the setup described in that
PR), then run "sync" on the client.  Examine the backing-store file on
the server (or a different client) using "od -X", and observe that the
file is written if (and only if) DO_MSYNC is defined in the test
program.

If that bug has been fixed, and the different but related kern/165927
has also been fixed, then the reproduction instructions for
kern/165927 will demonstrate the necessity of calling msync.

If kern/165923 has been fixed but kern/165927 has not, then I don't
have a straightforward reproduction scenario to demonstrate the
usefulness of msync.  (The former bug makes msync required for proper
operation; the latter prevents it from being useful for error
reporting.)