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