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