From owner-freebsd-doc@FreeBSD.ORG Sun Mar 11 11:30:10 2012 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 953F1106564A for ; Sun, 11 Mar 2012 11:30:10 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id 6EACA8FC0A for ; Sun, 11 Mar 2012 11:30:10 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.5/8.14.5) with ESMTP id q2BBUAPM017255 for ; Sun, 11 Mar 2012 11:30:10 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.5/8.14.5/Submit) id q2BBUAtI017254; Sun, 11 Mar 2012 11:30:10 GMT (envelope-from gnats) Resent-Date: Sun, 11 Mar 2012 11:30:10 GMT Resent-Message-Id: <201203111130.q2BBUAtI017254@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Joel Ray Holveck Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 95377106566B for ; Sun, 11 Mar 2012 11:22:09 +0000 (UTC) (envelope-from joelh@thor.piquan.org) Received: from thor.piquan.org (unknown [IPv6:2001:470:1f05:1741:201:2ff:fe8b:103e]) by mx1.freebsd.org (Postfix) with ESMTP id 545E58FC12 for ; Sun, 11 Mar 2012 11:22:09 +0000 (UTC) Received: from thor.piquan.org (localhost [127.0.0.1]) by thor.piquan.org (8.14.5/8.14.5) with ESMTP id q2BBM8vc025184 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sun, 11 Mar 2012 04:22:09 -0700 (PDT) (envelope-from joelh@thor.piquan.org) Received: (from joelh@localhost) by thor.piquan.org (8.14.5/8.14.5/Submit) id q2BBM80s025183; Sun, 11 Mar 2012 04:22:08 -0700 (PDT) (envelope-from joelh) Message-Id: <201203111122.q2BBM80s025183@thor.piquan.org> Date: Sun, 11 Mar 2012 04:22:08 -0700 (PDT) From: Joel Ray Holveck To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: David Wolfskill Subject: docs/165929: msync(2) man page indicates obsolescence, but it's useful X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Joel Ray Holveck List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 11 Mar 2012 11:30:10 -0000 >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 >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@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: