1madvise(3C) Standard C Library Functions madvise(3C)
2
6 madvise - provide advice to VM system
7
9 #include <sys/types.h>
10 #include <sys/mman.h>
11 int madvise(caddr_t addr, size_t len, int advice);
13
16 The madvise() function advises the kernel that a region of user mapped
17 memory in the range [addr, addr + len) will be accessed following a
18 type of pattern. The kernel uses this information to optimize the pro‐
19 cedure for manipulating and maintaining the resources associated with
20 the specified mapping range.
21 Values for advice are defined in <sys/mman.h> as:
24 #define MADV_NORMAL 0x0 /* No further special treatment */
26 #define MADV_RANDOM 0x1 /* Expect random page references */
27 #define MADV_SEQUENTIAL 0x2 /* Expect sequential page references */
28 #define MADV_WILLNEED 0x3 /* Will need these pages */
29 #define MADV_DONTNEED 0x4 /* Don't need these pages */
30 #define MADV_FREE 0x5 /* Contents can be freed */
31 #define MADV_ACCESS_DEFAULT 0x6 /* default access */
32 #define MADV_ACCESS_LWP 0x7 /* next LWP to access heavily */
33 #define MADV_ACCESS_MANY 0x8 /* many processes to access heavily */
34 MADV_NORMAL This is the default system characteristic where
37 accessing memory within the address range causes
38 the system to read data from the mapped file.
39 The kernel reads all data from files into pages
40 which are retained for a period of time as a
41 "cache." System pages can be a scarce resource,
42 so the kernel steals pages from other mappings
43 when needed. This is a likely occurrence, but
44 adversely affects system performance only if a
45 large amount of memory is accessed.
46 MADV_RANDOM Tell the kernel to read in a minimum amount of
49 data from a mapped file on any single particular
50 access. If MADV_NORMAL is in effect when an
51 address of a mapped file is accessed, the system
52 tries to read in as much data from the file as
53 reasonable, in anticipation of other accesses
54 within a certain locality.
55 MADV_SEQUENTIAL Tell the system that addresses in this range are
58 likely to be accessed only once, so the system
59 will free the resources mapping the address
60 range as quickly as possible.
61 MADV_WILLNEED Tell the system that a certain address range is
64 definitely needed so the kernel will start read‐
65 ing the specified range into memory. This can
66 benefit programs wanting to minimize the time
67 needed to access memory the first time, as the
68 kernel would need to read in from the file.
69 MADV_DONTNEED Tell the kernel that the specified address range
72 is no longer needed, so the system starts to
73 free the resources associated with the address
74 range.
75 MADV_FREE Tell the kernel that contents in the specified
78 address range are no longer important and the
79 range will be overwritten. When there is demand
80 for memory, the system will free pages associ‐
81 ated with the specified address range. In this
82 instance, the next time a page in the address
83 range is referenced, it will contain all zeroes.
84 Otherwise, it will contain the data that was
85 there prior to the MADV_FREE call. References
86 made to the address range will not make the sys‐
87 tem read from backing store (swap space) until
88 the page is modified again.
89 This value cannot be used on mappings that have
91 underlying file objects.
92 MADV_ACCESS_LWP Tell the kernel that the next LWP to touch the
95 specified address range will access it most
96 heavily, so the kernel should try to allocate
97 the memory and other resources for this range
98 and the LWP accordingly.
99 MADV_ACCESS_MANY Tell the kernel that many processes and/or LWPs
102 will access the specified address range randomly
103 across the machine, so the kernel should try to
104 allocate the memory and other resources for this
105 range accordingly.
106 MADV_ACCESS_DEFAULT Reset the kernel's expectation for how the spec‐
109 ified range will be accessed to the default.
110 The madvise() function should be used by applications with specific
114 knowledge of their access patterns over a memory object, such as a
115 mapped file, to increase system performance.
116
118 Upon successful completion, madvise() returns 0; otherwise, it returns
119 −1 and sets errno to indicate the error.
120
122 EAGAIN Some or all mappings in the address range [addr, addr +
123 len) are locked for I/O.
124 EBUSY Some or all of the addresses in the range [addr, addr + len)
127 are locked and MS_SYNC with the MS_INVALIDATE option is spec‐
128 ified.
129 EFAULT Some or all of the addresses in the specified range could not
132 be read into memory from the underlying object when perform‐
133 ing MADV_WILLNEED. The madvise() function could return prior
134 to this condition being detected, in which case errno will
135 not be set to EFAULT.
136 EINVAL The addr argument is not a multiple of the page size as
139 returned by sysconf(3C), the length of the specified address
140 range is equal to 0, or the advice argument was invalid.
141 EIO An I/O error occurred while reading from or writing to the
144 file system.
145 ENOMEM Addresses in the range [addr, addr + len) are outside the
148 valid range for the address space of a process, or specify
149 one or more pages that are not mapped.
150 ESTALE Stale NFS file handle.
153
156 See attributes(5) for descriptions of the following attributes:
157 ┌─────────────────────────────┬─────────────────────────────┐
162 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
163 ├─────────────────────────────┼─────────────────────────────┤
164 │Interface Stability │Stable │
165 ├─────────────────────────────┼─────────────────────────────┤
166 │MT-Level │MT-Safe │
167 └─────────────────────────────┴─────────────────────────────┘
168
170 meminfo(2), mmap(2), sysconf(3C), attributes(5)
171SunOS 5.11 23 Feb 2005 madvise(3C)