docs/165929: msync(2) man page indicates obsolescence, but it's useful

Sun Mar 11 11:30:10 UTC 2012

>Number:         165929
>Category:       docs
>Synopsis:       msync(2) man page indicates obsolescence, but it's useful
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Mar 11 11:30:10 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator:     Joel Ray Holveck <joelh at juniper.net>
>Release:        FreeBSD 8.3-PRERELEASE i386
>Organization:
>Environment:
System: FreeBSD thor.piquan.org 8.3-PRERELEASE FreeBSD 8.3-PRERELEASE #2: Sat Feb 25 15:52:16 PST 2012 root at thor.piquan.org:/usr/obj/usr/src/sys/THOR i386

>Description:
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.

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

>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.

--- mmap-doc.patch begins here ---
--- lib/libc/sys/mmap.2.orig	2012-03-10 19:49:31.000000000 -0800
+++ lib/libc/sys/mmap.2	2012-03-10 20:03:59.000000000 -0800
@@ -205,12 +205,9 @@
 system call generally do not flush dirty NOSYNC VM data.
 The
 .Xr msync 2
-system call is obsolete since
-.Bx
-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.
+system call 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.
 .It Dv MAP_PREFAULT_READ
 Immediately update the calling process's lowest-level virtual address
 translation structures, such as its page table, so that every memory
--- lib/libc/sys/msync.2.orig	2012-03-10 20:05:18.000000000 -0800
+++ lib/libc/sys/msync.2	2012-03-10 20:07:20.000000000 -0800
@@ -113,9 +113,16 @@
 .Sh BUGS
 The
 .Fn msync
-system call is obsolete since
-.Bx
-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.
+system call does not report errors if dirty pages could not be written.
+This is expected to be fixed in a future release of
+.Fx .
+.Pp
+If another process, such as
+.Xr syncer 4 ,
+attempts to flush dirty pages on an NFS-backed file, but lacks
+permissions on the server to do so, it may fail.  If this happens,
+future calls to
+.Fn msync
+may not have any effect.  This is not a bug in
+.Fn msync ,
+although it may appear to be; it is actually a bug in NFS.
--- mmap-doc.patch ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:

