msync(3c) - osol9

1msync(3C)                Standard C Library Functions                msync(3C)
2
3
4

NAME

6       msync - synchronize memory with physical storage
7

SYNOPSIS

9       #include <sys/mman.h>
10
11       int msync(void *addr, size_t len, int flags);
12
13

DESCRIPTION

15       The   msync()  function  writes  all  modified copies of pages over the
16       range [addr, addr + len) to the underlying hardware, or invalidates any
17       copies  so that further references to the pages will be obtained by the
18       system from their permanent storage locations.  The  permanent  storage
19       for  a  modified  MAP_SHARED mapping is the file the page is mapped to;
20       the permanent storage for a modified MAP_PRIVATE mapping  is  its  swap
21       area.
22
23
24       The flags argument is a bit pattern built from the following values:
25
26       MS_ASYNC         perform asynchronous writes
27
28
29       MS_SYNC          perform synchronous writes
30
31
32       MS_INVALIDATE    invalidate mappings
33
34
35
36       If  flags  is  MS_ASYNC  or MS_SYNC, the function synchronizes the file
37       contents to match the current contents of the memory region.
38
39           o      All write references to the memory region made prior to  the
40                  call are visible by subsequent read operations on the file.
41
42           o      All writes to the same portion of the file prior to the call
43                  may or may not be visible by read references to  the  memory
44                  region.
45
46           o      Unmodified  pages  in the specified range are not written to
47                  the underlying hardware.
48
49
50       If flags is MS_ASYNC, the function  may  return  immediately  once  all
51       write  operations are scheduled; if flags is MS_SYNC, the function does
52       not return until all write operations are completed.
53
54
55       If flags is MS_INVALIDATE, the function synchronizes  the  contents  of
56       the memory region to match the current file contents.
57
58           o      All  writes  to the mapped portion of the file made prior to
59                  the call are visible by subsequent read  references  to  the
60                  mapped memory region.
61
62           o      All  write  references prior to the call, by any process, to
63                  memory regions mapped to the same portion of the file  using
64                  MAP_SHARED, are visible by read references to the region.
65
66
67       If  msync()  causes any write to the file, then the file's st_ctime and
68       st_mtime fields are marked for update.
69

RETURN VALUES

71       Upon successful completion, msync() returns 0; otherwise, it returns −1
72       and sets errno to indicate the error.
73

ERRORS

75       The msync() function will fail if:
76
77       EBUSY     Some  or all of the addresses in the range [addr, addr + len)
78                 are locked and MS_SYNC with the MS_INVALIDATE option is spec‐
79                 ified.
80
81
82       EAGAIN    Some  or  all  pages  in  the  range [addr,  addr +  len) are
83                 locked for I/O.
84
85
86       EINVAL    The addr argument is not a multiple  of  the   page  size  as
87                 returned by sysconf(3C).
88
89                 The  flags  argument  is not some combination of MS_ASYNC and
90                 MS_INVALIDATE.
91
92
93       EIO       An I/O error occurred while reading from or  writing  to  the
94                 file system.
95
96
97       ENOMEM    Addresses  in  the  range  [addr, addr + len) are outside the
98                 valid range for the address space of a  process,  or  specify
99                 one or more pages that are not mapped.
100
101
102       EPERM     MS_INVALIDATE  was  specified and one or more of the pages is
103                 locked in memory.
104
105

USAGE

107       The msync() function should be used by programs that require  a  memory
108       object  to  be  in  a  known state, for example in building transaction
109       facilities.
110
111
112       Normal system activity can cause pages to be written to  disk.   There‐
113       fore,  there  are  no  guarantees that msync() is the only control over
114       when pages are or are not written to disk.
115

ATTRIBUTES

117       See attributes(5) for descriptions of the following attributes:
118
119
120
121
122       ┌─────────────────────────────┬─────────────────────────────┐
123       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
124       ├─────────────────────────────┼─────────────────────────────┤
125       │Interface Stability          │Standard                     │
126       ├─────────────────────────────┼─────────────────────────────┤
127       │MT-Level                     │MT-Safe                      │
128       └─────────────────────────────┴─────────────────────────────┘
129