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

NAME

12       msync - synchronize memory with physical storage
13

SYNOPSIS

15       #include <sys/mman.h>
16
17       int msync(void *addr, size_t len, int flags);
18
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  shall  require that addr be a multiple of the page
29       size 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  map‐
38       pings  has any permanent storage locations.  The effect of msync() on a
39       shared memory object or a typed  memory  object  is  unspecified.   The
40       behavior  of this function is unspecified if the mapping was not estab‐
41       lished by a 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                   Symbolic Constant  Description
47                   MS_ASYNC           Perform asynchronous writes.
48                   MS_SYNC            Perform synchronous writes.
49                   MS_INVALIDATE      Invalidate cached data.
50
51       When  MS_ASYNC  is specified, msync() shall return immediately once all
52       the write operations  are  initiated  or  queued  for  servicing;  when
53       MS_SYNC  is  specified, msync() shall not return until all write opera‐
54       tions are completed as defined for synchronized I/O data integrity com‐
55       pletion. Either MS_ASYNC or MS_SYNC is specified, but not both.
56
57       When  MS_INVALIDATE  is  specified, msync() shall invalidate all cached
58       copies of mapped data that are inconsistent with the permanent  storage
59       locations  such  that  subsequent references shall obtain data that was
60       consistent with the permanent storage locations  sometime  between  the
61       call to msync() and the first subsequent memory reference to the data.
62
63       If msync() causes any write to a file, the file's st_ctime and st_mtime
64       fields shall be marked for update.
65

RETURN VALUE

67       Upon successful completion, msync() shall return 0; otherwise, it shall
68       return -1 and set errno to indicate the error.
69

ERRORS

71       The msync() function shall fail if:
72
73       EBUSY  Some  or  all of the addresses in the range starting at addr and
74              continuing for len bytes are locked, and MS_INVALIDATE is speci‐
75              fied.
76
77       EINVAL The value of flags is invalid.
78
79       EINVAL The value of addr is not a multiple of the page size {PAGESIZE}.
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
86       The following sections are informative.
87

EXAMPLES

89       None.
90

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

114       None.
115

SEE ALSO

117       mmap(), sysconf(), the Base Definitions volume of IEEE Std 1003.1-2001,
118       <sys/mman.h>
119
121       Portions of this text are reprinted and reproduced in  electronic  form
122       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
123       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
124       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
125       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
126       event of any discrepancy between this version and the original IEEE and
127       The Open Group Standard, the original IEEE and The Open Group  Standard
128       is  the  referee document. The original Standard can be obtained online
129       at http://www.opengroup.org/unix/online.html .
130
131
132
133IEEE/The Open Group                  2003                            MSYNC(3P)
Impressum