summaryrefslogtreecommitdiffstats
path: root/man2/msync.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/msync.2')
-rw-r--r--man2/msync.2140
1 files changed, 140 insertions, 0 deletions
diff --git a/man2/msync.2 b/man2/msync.2
new file mode 100644
index 0000000..baa328d
--- /dev/null
+++ b/man2/msync.2
@@ -0,0 +1,140 @@
+.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH msync 2 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+msync \- synchronize a file with a memory map
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/mman.h>
+.PP
+.BI "int msync(void " addr [. length "], size_t " length ", int " flags );
+.fi
+.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 the filesystem.
+Without use of this call,
+there is no guarantee that changes are written back before
+.BR munmap (2)
+is called.
+To be more precise, the part of the file that
+corresponds to the memory area starting at
+.I addr
+and having length
+.I length
+is updated.
+.PP
+The
+.I flags
+argument should specify exactly one of
+.B MS_ASYNC
+and
+.BR MS_SYNC ,
+and may additionally include the
+.B MS_INVALIDATE
+bit.
+These bits have the following meanings:
+.TP
+.B MS_ASYNC
+Specifies that an update be scheduled, but the call returns immediately.
+.TP
+.B MS_SYNC
+Requests an update and waits for it to complete.
+.TP
+.B MS_INVALIDATE
+.\" 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.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EBUSY
+.B MS_INVALIDATE
+was specified in
+.IR flags ,
+and a memory lock exists for the specified address range.
+.TP
+.B EINVAL
+.I addr
+is not a multiple of PAGESIZE; or any bit other than
+.BR MS_ASYNC " | " MS_INVALIDATE " | " MS_SYNC
+is set in
+.IR flags ;
+or both
+.B MS_SYNC
+and
+.B MS_ASYNC
+are set in
+.IR flags .
+.TP
+.B ENOMEM
+The indicated memory (or part of it) was not mapped.
+.SH VERSIONS
+According to POSIX, either
+.B MS_SYNC
+or
+.B 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
+.B 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
+.B MS_SYNC
+or
+.B MS_ASYNC
+in
+.IR flags .
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.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
+.BR ENOMEM .
+.PP
+On POSIX systems on which
+.BR msync ()
+is available, both
+.B _POSIX_MAPPED_FILES
+and
+.B _POSIX_SYNCHRONIZED_IO
+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 SEE ALSO
+.BR mmap (2)
+.PP
+B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391.