1MSYNC(3P)                  POSIX Programmer's Manual                 MSYNC(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       msync — synchronize memory with physical storage
14

SYNOPSIS

16       #include <sys/mman.h>
17
18       int msync(void *addr, size_t len, int flags);
19

DESCRIPTION

21       The msync() function shall write all modified data to permanent storage
22       locations,  if  any,  in  those  whole pages containing any part of the
23       address space of the process starting at address  addr  and  continuing
24       for  len  bytes.  If  no such storage exists, msync() need not have any
25       effect. If requested, the msync() function shall then invalidate cached
26       copies of data.
27
28       The implementation may require that addr be a multiple of the page size
29       as returned by sysconf().
30
31       For mappings to files, the msync() function shall ensure that all write
32       operations are completed as defined for synchronized I/O data integrity
33       completion. It is unspecified whether the  implementation  also  writes
34       out  other  file  attributes.  When  the  msync() function is called on
35       MAP_PRIVATE mappings, any modified data shall not  be  written  to  the
36       underlying  object  and shall not cause such data to be made visible to
37       other processes. It is unspecified whether data in MAP_PRIVATE mappings
38       has any permanent storage locations.  The effect of msync() on a shared
39       memory object or a typed memory object is unspecified.  The behavior of
40       this  function  is  unspecified if the mapping was not established by a
41       call to mmap().
42
43       The flags argument is constructed from the bitwise-inclusive OR of  one
44       or more of the following flags defined in the <sys/mman.h> header:
45
46                 ┌──────────────────┬──────────────────────────────┐
47Symbolic Constant Description          
48                 ├──────────────────┼──────────────────────────────┤
49                 │MS_ASYNC          │ Perform asynchronous writes. │
50                 │MS_SYNC           │ Perform synchronous writes.  │
51                 │MS_INVALIDATE     │ Invalidate cached data.      │
52                 └──────────────────┴──────────────────────────────┘
53       When  MS_ASYNC  is specified, msync() shall return immediately once all
54       the write operations  are  initiated  or  queued  for  servicing;  when
55       MS_SYNC  is  specified, msync() shall not return until all write opera‐
56       tions are completed as defined for synchronized I/O data integrity com‐
57       pletion. Either MS_ASYNC or MS_SYNC shall be specified, but not both.
58
59       When  MS_INVALIDATE  is  specified, msync() shall invalidate all cached
60       copies of mapped data that are inconsistent with the permanent  storage
61       locations  such  that  subsequent references shall obtain data that was
62       consistent with the permanent storage locations  sometime  between  the
63       call to msync() and the first subsequent memory reference to the data.
64
65       If  msync()  causes any write to a file, the file's last data modifica‐
66       tion and last file status change timestamps shall be marked for update.
67

RETURN VALUE

69       Upon successful completion, msync() shall return 0; otherwise, it shall
70       return −1 and set errno to indicate the error.
71

ERRORS

73       The msync() function shall fail if:
74
75       EBUSY  Some  or  all of the addresses in the range starting at addr and
76              continuing for len bytes are locked, and MS_INVALIDATE is speci‐
77              fied.
78
79       EINVAL The value of flags is invalid.
80
81       ENOMEM The  addresses  in the range starting at addr and continuing for
82              len bytes are outside the range allowed for the address space of
83              a process or specify one or more pages that are not mapped.
84
85       The msync() function may fail if:
86
87       EINVAL The value of addr is not a multiple of the page size as returned
88              by sysconf().
89
90       The following sections are informative.
91

EXAMPLES

93       None.
94

APPLICATION USAGE

96       The msync() function is only supported if the  Synchronized  Input  and
97       Output  option  is  supported,  and  thus  need not be available on all
98       implementations.
99
100       The msync() function should be used by programs that require  a  memory
101       object  to  be  in  a known state; for example, in building transaction
102       facilities.
103
104       Normal system activity can cause pages to be written to  disk.   There‐
105       fore,  there  are  no  guarantees that msync() is the only control over
106       when pages are or are not written to disk.
107

RATIONALE

109       The msync() function writes out data in a mapped region to  the  perma‐
110       nent  storage  for  the  underlying object. The call to msync() ensures
111       data integrity of the file.
112
113       After the data is written out, any cached data may  be  invalidated  if
114       the MS_INVALIDATE flag was specified. This is useful on systems that do
115       not support read/write consistency.
116

FUTURE DIRECTIONS

118       None.
119

SEE ALSO

121       mmap(), sysconf()
122
123       The Base Definitions volume of POSIX.1‐2008, <sys_mman.h>
124
126       Portions of this text are reprinted and reproduced in  electronic  form
127       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
128       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
129       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
130       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
131       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
132       event of any discrepancy between this version and the original IEEE and
133       The  Open Group Standard, the original IEEE and The Open Group Standard
134       is the referee document. The original Standard can be  obtained  online
135       at http://www.unix.org/online.html .
136
137       Any  typographical  or  formatting  errors that appear in this page are
138       most likely to have been introduced during the conversion of the source
139       files  to  man page format. To report such errors, see https://www.ker
140       nel.org/doc/man-pages/reporting_bugs.html .
141
142
143
144IEEE/The Open Group                  2013                            MSYNC(3P)
Impressum