| 1 |
.\" Copyright 1996, Andries E. Brouwer <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH msync 2 2026-02-11 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
msync \- synchronize a file with a memory map |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B #include <sys/mman.h> |
| 15 |
.P |
| 16 |
.BR "int msync(" "size_t length;" |
| 17 |
.BI " void " addr [ length "], size_t " length ", int " flags ); |
| 18 |
.fi |
| 19 |
.SH DESCRIPTION |
| 20 |
.BR msync () |
| 21 |
flushes changes made to the in-core copy of a file that was mapped |
| 22 |
into memory using |
| 23 |
.BR mmap (2) |
| 24 |
back to the filesystem. |
| 25 |
Without use of this call, |
| 26 |
there is no guarantee that changes are written back before |
| 27 |
.BR munmap (2) |
| 28 |
is called. |
| 29 |
To be more precise, the part of the file that |
| 30 |
corresponds to the memory area starting at |
| 31 |
.I addr |
| 32 |
and having length |
| 33 |
.I length |
| 34 |
is updated. |
| 35 |
.P |
| 36 |
The |
| 37 |
.I flags |
| 38 |
argument should specify exactly one of |
| 39 |
.B MS_ASYNC |
| 40 |
and |
| 41 |
.BR MS_SYNC , |
| 42 |
and may additionally include the |
| 43 |
.B MS_INVALIDATE |
| 44 |
bit. |
| 45 |
These bits have the following meanings: |
| 46 |
.TP |
| 47 |
.B MS_ASYNC |
| 48 |
Specifies that an update be scheduled, but the call returns immediately. |
| 49 |
.TP |
| 50 |
.B MS_SYNC |
| 51 |
Requests an update and waits for it to complete. |
| 52 |
.TP |
| 53 |
.B MS_INVALIDATE |
| 54 |
.\" Since Linux 2.4, this seems to be a no-op (other than the |
| 55 |
.\" EBUSY check for VM_LOCKED). |
| 56 |
Asks to invalidate other mappings of the same file |
| 57 |
(so that they can be updated with the fresh values just written). |
| 58 |
.SH RETURN VALUE |
| 59 |
On success, zero is returned. |
| 60 |
On error, \-1 is returned, and |
| 61 |
.I errno |
| 62 |
is set to indicate the error. |
| 63 |
.SH ERRORS |
| 64 |
.TP |
| 65 |
.B EBUSY |
| 66 |
.B MS_INVALIDATE |
| 67 |
was specified in |
| 68 |
.IR flags , |
| 69 |
and a memory lock exists for the specified address range. |
| 70 |
.TP |
| 71 |
.B EINVAL |
| 72 |
.I addr |
| 73 |
is not a multiple of PAGESIZE; |
| 74 |
or any bit other than |
| 75 |
.BR MS_ASYNC " | " MS_INVALIDATE " | " MS_SYNC |
| 76 |
is set in |
| 77 |
.IR flags ; |
| 78 |
or both |
| 79 |
.B MS_SYNC |
| 80 |
and |
| 81 |
.B MS_ASYNC |
| 82 |
are set in |
| 83 |
.IR flags . |
| 84 |
.TP |
| 85 |
.B ENOMEM |
| 86 |
The indicated memory (or part of it) was not mapped. |
| 87 |
.SH VERSIONS |
| 88 |
According to POSIX, either |
| 89 |
.B MS_SYNC |
| 90 |
or |
| 91 |
.B MS_ASYNC |
| 92 |
must be specified in |
| 93 |
.IR flags , |
| 94 |
and indeed failure to include one of these flags will cause |
| 95 |
.BR msync () |
| 96 |
to fail on some systems. |
| 97 |
However, Linux permits a call to |
| 98 |
.BR msync () |
| 99 |
that specifies neither of these flags, |
| 100 |
with semantics that are (currently) equivalent to specifying |
| 101 |
.BR MS_ASYNC . |
| 102 |
(Since Linux 2.6.19, |
| 103 |
.\" commit 204ec841fbea3e5138168edbc3a76d46747cc987 |
| 104 |
.B MS_ASYNC |
| 105 |
is in fact a no-op, since the kernel properly tracks dirty |
| 106 |
pages and flushes them to storage as necessary.) |
| 107 |
Notwithstanding the Linux behavior, |
| 108 |
portable, future-proof applications should ensure that they specify either |
| 109 |
.B MS_SYNC |
| 110 |
or |
| 111 |
.B MS_ASYNC |
| 112 |
in |
| 113 |
.IR flags . |
| 114 |
.SH STANDARDS |
| 115 |
POSIX.1-2024. |
| 116 |
.SH HISTORY |
| 117 |
SUSv1, |
| 118 |
POSIX.1-1996. |
| 119 |
.P |
| 120 |
This call was introduced in Linux 1.3.21, and then used |
| 121 |
.B EFAULT |
| 122 |
instead of |
| 123 |
.BR ENOMEM . |
| 124 |
In Linux 2.4.19, this was changed to the POSIX value |
| 125 |
.BR ENOMEM . |
| 126 |
.P |
| 127 |
On POSIX systems on which |
| 128 |
.BR msync () |
| 129 |
is available, both |
| 130 |
.B _POSIX_MAPPED_FILES |
| 131 |
and |
| 132 |
.B _POSIX_SYNCHRONIZED_IO |
| 133 |
are defined in |
| 134 |
.I <unistd.h> |
| 135 |
to a value greater than 0. |
| 136 |
(See also |
| 137 |
.BR sysconf (3).) |
| 138 |
.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. |
| 139 |
.\" -1: unavailable, 0: ask using sysconf(). |
| 140 |
.\" glibc defines them to 1. |
| 141 |
.SH SEE ALSO |
| 142 |
.BR mmap (2) |
| 143 |
.P |
| 144 |
B.O.\& Gallmeister, POSIX.4, O'Reilly, pp.\& 128\[en]129 and 389\[en]391. |