dlopen.3: tfix

[thirdparty/man-pages.git] / man2 / msync.2

diff --git a/man2/msync.2 b/man2/msync.2
index 85557060b8d3dc476407f3063db785f72d482097..ae8ffba53fc82f235283a8087278f4b06cf856ad 100644 (file)
--- a/man2/msync.2
+++ b/man2/msync.2
@@ -22,20 +22,20 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.TH MSYNC 2 2008-04-22 "Linux" "Linux Programmer's Manual"
+.TH MSYNC 2 2017-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
 msync \- synchronize a file with a memory map
 .SH SYNOPSIS
 .B #include <sys/mman.h>
-.sp
+.PP
 .BI "int msync(void *" addr ", size_t " length ", int " flags );
 .SH DESCRIPTION
 .BR msync ()
 flushes changes made to the in-core copy of a file that was mapped
 into memory using
 .BR mmap (2)
-back to disk.
-Without use of this call
+back to the filesystem.
+Without use of this call,
 there is no guarantee that changes are written back before
 .BR munmap (2)
 is called.
@@ -45,25 +45,28 @@ corresponds to the memory area starting at
 and having length
 .I length
 is updated.
-
+.PP
 The
 .I flags
-argument may have the bits
-.BR MS_ASYNC ,
-.BR MS_SYNC ,
+argument should specify exactly one of
+.BR MS_ASYNC
 and
+.BR MS_SYNC ,
+and may additionally include the
 .B MS_INVALIDATE
-set, but not both
-.B MS_ASYNC
-and
-.BR MS_SYNC .
+bit.
+These bits have the following meanings:
+.TP
 .B MS_ASYNC
-specifies that an update be scheduled, but the call
-returns immediately.
+Specifies that an update be scheduled, but the call returns immediately.
+.TP
 .B MS_SYNC
-asks for an update and waits for it to complete.
+Requests an update and waits for it to complete.
+.TP
 .B MS_INVALIDATE
-asks to invalidate other mappings of the same file
+.\" Since Linux 2.4, this seems to be a no-op (other than the
+.\" EBUSY check for VM_LOCKED).
+Asks to invalidate other mappings of the same file
 (so that they can be updated with the fresh values just written).
 .SH RETURN VALUE
 On success, zero is returned.
@@ -94,13 +97,13 @@ are set in
 .B ENOMEM
 The indicated memory (or part of it) was not mapped.
 .SH CONFORMING TO
-POSIX.1-2001.
-
+POSIX.1-2001, POSIX.1-2008.
+.PP
 This call was introduced in Linux 1.3.21, and then used
 .B EFAULT
 instead of
 .BR ENOMEM .
-In Linux 2.4.19 this was changed to the POSIX value
+In Linux 2.4.19, this was changed to the POSIX value
 .BR ENOMEM .
 .SH AVAILABILITY
 On POSIX systems on which
@@ -109,13 +112,42 @@ is available, both
 .B _POSIX_MAPPED_FILES
 and
 .B _POSIX_SYNCHRONIZED_IO
-are defined in \fI<unistd.h>\fP to a value greater than 0.
+are defined in
+.I <unistd.h>
+to a value greater than 0.
 (See also
 .BR sysconf (3).)
 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 .\" -1: unavailable, 0: ask using sysconf().
 .\" glibc defines them to 1.
+.SH NOTES
+According to POSIX, either
+.BR MS_SYNC
+or
+.BR MS_ASYNC
+must be specified in
+.IR flags ,
+and indeed failure to include one of these flags will cause
+.BR msync ()
+to fail on some systems.
+However, Linux permits a call to
+.BR msync ()
+that specifies neither of these flags,
+with semantics that are (currently) equivalent to specifying
+.BR MS_ASYNC .
+(Since Linux 2.6.19,
+.\" commit 204ec841fbea3e5138168edbc3a76d46747cc987
+.BR MS_ASYNC
+is in fact a no-op, since the kernel properly tracks dirty
+pages and flushes them to storage as necessary.)
+Notwithstanding the Linux behavior,
+portable, future-proof applications should ensure that they specify either
+.BR MS_SYNC
+or
+.BR MS_ASYNC
+in
+.IR flags .
 .SH SEE ALSO
 .BR mmap (2)
-
-B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391.
+.PP
+B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391.