]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da | 24 | .\" |
bffbb22f | 25 | .TH MSYNC 2 2020-06-09 "Linux" "Linux Programmer's Manual" |
fea681da MK |
26 | .SH NAME |
27 | msync \- synchronize a file with a memory map | |
28 | .SH SYNOPSIS | |
c7db92b9 | 29 | .nf |
fea681da | 30 | .B #include <sys/mman.h> |
68e4db0a | 31 | .PP |
14f5ae6d | 32 | .BI "int msync(void *" addr ", size_t " length ", int " flags ); |
c7db92b9 | 33 | .fi |
fea681da | 34 | .SH DESCRIPTION |
e511ffb6 | 35 | .BR msync () |
fea681da MK |
36 | flushes changes made to the in-core copy of a file that was mapped |
37 | into memory using | |
38 | .BR mmap (2) | |
840324c0 | 39 | back to the filesystem. |
44a48411 | 40 | Without use of this call, |
fea681da MK |
41 | there is no guarantee that changes are written back before |
42 | .BR munmap (2) | |
c13182ef MK |
43 | is called. |
44 | To be more precise, the part of the file that | |
fea681da | 45 | corresponds to the memory area starting at |
14f5ae6d | 46 | .I addr |
fea681da MK |
47 | and having length |
48 | .I length | |
c13182ef | 49 | is updated. |
efeece04 | 50 | .PP |
9f339d4e | 51 | The |
fea681da | 52 | .I flags |
31f0e8c8 MK |
53 | argument should specify exactly one of |
54 | .BR MS_ASYNC | |
c13182ef | 55 | and |
31f0e8c8 MK |
56 | .BR MS_SYNC , |
57 | and may additionally include the | |
9f339d4e | 58 | .B MS_INVALIDATE |
31f0e8c8 MK |
59 | bit. |
60 | These bits have the following meanings: | |
61 | .TP | |
c13182ef | 62 | .B MS_ASYNC |
31f0e8c8 MK |
63 | Specifies that an update be scheduled, but the call returns immediately. |
64 | .TP | |
c13182ef | 65 | .B MS_SYNC |
31f0e8c8 MK |
66 | Requests an update and waits for it to complete. |
67 | .TP | |
c13182ef | 68 | .B MS_INVALIDATE |
31f0e8c8 MK |
69 | .\" Since Linux 2.4, this seems to be a no-op (other than the |
70 | .\" EBUSY check for VM_LOCKED). | |
71 | Asks to invalidate other mappings of the same file | |
fea681da | 72 | (so that they can be updated with the fresh values just written). |
47297adb | 73 | .SH RETURN VALUE |
c13182ef MK |
74 | On success, zero is returned. |
75 | On error, \-1 is returned, and | |
fea681da | 76 | .I errno |
f6a4078b | 77 | is set to indicate the error. |
fea681da MK |
78 | .SH ERRORS |
79 | .TP | |
0daa9e92 | 80 | .B EBUSY |
2f0af33b MK |
81 | .B MS_INVALIDATE |
82 | was specified in | |
c13182ef | 83 | .IR flags , |
9f339d4e MK |
84 | and a memory lock exists for the specified address range. |
85 | .TP | |
0daa9e92 | 86 | .B EINVAL |
14f5ae6d | 87 | .I addr |
24bd9a49 | 88 | is not a multiple of PAGESIZE; or any bit other than |
682edefb MK |
89 | .BR MS_ASYNC " | " MS_INVALIDATE " | " MS_SYNC |
90 | is set in | |
24bd9a49 | 91 | .IR flags ; |
c13182ef | 92 | or both |
682edefb MK |
93 | .B MS_SYNC |
94 | and | |
95 | .B MS_ASYNC | |
96 | are set in | |
a5e0a0e4 | 97 | .IR flags . |
fea681da MK |
98 | .TP |
99 | .B ENOMEM | |
100 | The indicated memory (or part of it) was not mapped. | |
47297adb | 101 | .SH CONFORMING TO |
c27fa8cc | 102 | POSIX.1-2001, POSIX.1-2008. |
efeece04 | 103 | .PP |
682edefb MK |
104 | This call was introduced in Linux 1.3.21, and then used |
105 | .B EFAULT | |
106 | instead of | |
107 | .BR ENOMEM . | |
82e683e6 | 108 | In Linux 2.4.19, this was changed to the POSIX value |
682edefb | 109 | .BR ENOMEM . |
bd168648 | 110 | .PP |
fea681da | 111 | On POSIX systems on which |
e511ffb6 | 112 | .BR msync () |
fea681da MK |
113 | is available, both |
114 | .B _POSIX_MAPPED_FILES | |
115 | and | |
116 | .B _POSIX_SYNCHRONIZED_IO | |
509e2056 MK |
117 | are defined in |
118 | .I <unistd.h> | |
119 | to a value greater than 0. | |
405f0560 | 120 | (See also |
fea681da | 121 | .BR sysconf (3).) |
97c1eac8 | 122 | .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. |
fea681da MK |
123 | .\" -1: unavailable, 0: ask using sysconf(). |
124 | .\" glibc defines them to 1. | |
433e3408 | 125 | .SH NOTES |
b60d9859 | 126 | According to POSIX, either |
433e3408 | 127 | .BR MS_SYNC |
b60d9859 | 128 | or |
433e3408 | 129 | .BR MS_ASYNC |
fe8b1358 | 130 | must be specified in |
b1c5c4ec MK |
131 | .IR flags , |
132 | and indeed failure to include one of these flags will cause | |
133 | .BR msync () | |
134 | to fail on some systems. | |
433e3408 MK |
135 | However, Linux permits a call to |
136 | .BR msync () | |
137 | that specifies neither of these flags, | |
138 | with semantics that are (currently) equivalent to specifying | |
139 | .BR MS_ASYNC . | |
140 | (Since Linux 2.6.19, | |
141 | .\" commit 204ec841fbea3e5138168edbc3a76d46747cc987 | |
142 | .BR MS_ASYNC | |
143 | is in fact a no-op, since the kernel properly tracks dirty | |
144 | pages and flushes them to storage as necessary.) | |
145 | Notwithstanding the Linux behavior, | |
b1c5c4ec | 146 | portable, future-proof applications should ensure that they specify either |
433e3408 | 147 | .BR MS_SYNC |
b60d9859 | 148 | or |
433e3408 MK |
149 | .BR MS_ASYNC |
150 | in | |
151 | .IR flags . | |
47297adb | 152 | .SH SEE ALSO |
fea681da | 153 | .BR mmap (2) |
efeece04 | 154 | .PP |
d2fdb1e3 | 155 | B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391. |