1memcntl(2) System Calls memcntl(2)
2
6 memcntl - memory management control
7
9 #include <sys/types.h>
10 #include <sys/mman.h>
11 int memcntl(caddr_t addr, size_t len, int cmd, caddr_t arg,
13 int attr, int mask);
14
17 The memcntl() function allows the calling process to apply a variety of
18 control operations over the address space identified by the mappings
19 established for the address range [addr, addr + len).
20 The addr argument must be a multiple of the pagesize as returned by
23 sysconf(3C). The scope of the control operations can be further defined
24 with additional selection criteria (in the form of attributes) accord‐
25 ing to the bit pattern contained in attr.
26 The following attributes specify page mapping selection criteria:
29 SHARED Page is mapped shared.
31 PRIVATE Page is mapped private.
34 The following attributes specify page protection selection criteria.
38 The selection criteria are constructed by a bitwise OR operation on the
39 attribute bits and must match exactly.
40 PROT_READ Page can be read.
42 PROT_WRITE Page can be written.
45 PROT_EXEC Page can be executed.
48 The following criteria may also be specified:
52 PROC_TEXT Process text.
54 PROC_DATA Process data.
57 The PROC_TEXT attribute specifies all privately mapped segments with
61 read and execute permission, and the PROC_DATA attribute specifies all
62 privately mapped segments with write permission.
63 Selection criteria can be used to describe various abstract memory
66 objects within the address space on which to operate. If an operation
67 shall not be constrained by the selection criteria, attr must have the
68 value 0.
69 The operation to be performed is identified by the argument cmd. The
72 symbolic names for the operations are defined in <sys/mman.h> as fol‐
73 lows:
74 MC_LOCK
76 Lock in memory all pages in the range with attributes attr. A given
78 page may be locked multiple times through different mappings; how‐
79 ever, within a given mapping, page locks do not nest. Multiple lock
80 operations on the same address in the same process will all be
81 removed with a single unlock operation. A page locked in one
82 process and mapped in another (or visible through a different map‐
83 ping in the locking process) is locked in memory as long as the
84 locking process does neither an implicit nor explicit unlock opera‐
85 tion. If a locked mapping is removed, or a page is deleted through
86 file removal or truncation, an unlock operation is implicitly per‐
87 formed. If a writable MAP_PRIVATE page in the address range is
88 changed, the lock will be transferred to the private page.
89 The arg argument is not used, but must be 0 to ensure compatibility
91 with potential future enhancements.
92 MC_LOCKAS
95 Lock in memory all pages mapped by the address space with
97 attributes attr. The addr and len arguments are not used, but must
98 be NULL and 0 respectively, to ensure compatibility with potential
99 future enhancements. The arg argument is a bit pattern built from
100 the flags:
101 MCL_CURRENT Lock current mappings.
103 MCL_FUTURE Lock future mappings.
106 The value of arg determines whether the pages to be locked are
108 those currently mapped by the address space, those that will be
109 mapped in the future, or both. If MCL_FUTURE is specified, then all
110 mappings subsequently added to the address space will be locked,
111 provided sufficient memory is available.
112 MC_SYNC
115 Write to their backing storage locations all modified pages in the
117 range with attributes attr. Optionally, invalidate cache copies.
118 The backing storage for a modified MAP_SHARED mapping is the file
119 the page is mapped to; the backing storage for a modified MAP_PRI‐
120 VATE mapping is its swap area. The arg argument is a bit pattern
121 built from the flags used to control the behavior of the operation:
122 MS_ASYNC Perform asynchronous writes.
124 MS_SYNC Perform synchronous writes.
127 MS_INVALIDATE Invalidate mappings.
130 MS_ASYNC Return immediately once all write operations are sched‐
132 uled; with MS_SYNC the function will not return until all write
133 operations are completed.
134 MS_INVALIDATE Invalidate all cached copies of data in memory, so
136 that further references to the pages will be obtained by the system
137 from their backing storage locations. This operation should be used
138 by applications that require a memory object to be in a known
139 state.
140 MC_UNLOCK
143 Unlock all pages in the range with attributes attr. The arg argu‐
145 ment is not used, but must be 0 to ensure compatibility with poten‐
146 tial future enhancements.
147 MC_UNLOCKAS
150 Remove address space memory locks and locks on all pages in the
152 address space with attributes attr. The addr, len, and arg argu‐
153 ments are not used, but must be NULL, 0 and 0, respectively, to
154 ensure compatibility with potential future enhancements.
155 MC_HAT_ADVISE
158 Advise system how a region of user-mapped memory will be accessed.
160 The arg argument is interpreted as a "struct memcntl_mha *". The
161 following members are defined in a struct memcntl_mha:
162 uint_t mha_cmd;
164 uint_t mha_flags;
165 size_t mha_pagesize;
166 The accepted values for mha_cmd are:
168 MHA_MAPSIZE_VA
170 MHA_MAPSIZE_STACK
171 MHA_MAPSIZE_BSSBRK
172 The mha_flags member is reserved for future use and must always be
174 set to 0. The mha_pagesize member must be a valid size as obtained
175 from getpagesizes(3C) or the constant value 0 to allow the system
176 to choose an appropriate hardware address translation mapping size.
177 MHA_MAPSIZE_VA sets the preferred hardware address translation map‐
179 ping size of the region of memory from addr to addr + len. Both
180 addr and len must be aligned to an mha_pagesize boundary. The
181 entire virtual address region from addr to addr + len must not have
182 any holes. Permissions within each mha_pagesize-aligned portion of
183 the region must be consistent. When a size of 0 is specified, the
184 system selects an appropriate size based on the size and alignment
185 of the memory region, type of processor, and other considerations.
186 MHA_MAPSIZE_STACK sets the preferred hardware address translation
188 mapping size of the process main thread stack segment. The addr and
189 len arguments must be NULL and 0, respectively.
190 MHA_MAPSIZE_BSSBRK sets the preferred hardware address translation
192 mapping size of the process heap. The addr and len arguments must
193 be NULL and 0, respectively. See the NOTES section of the ppgsz(1)
194 manual page for additional information on process heap alignment.
195 The attr argument must be 0 for all MC_HAT_ADVISE operations.
197 The mask argument must be 0; it is reserved for future use.
201 Locks established with the lock operations are not inherited by a child
204 process after fork(2). The memcntl() function fails if it attempts to
205 lock more memory than a system-specific limit.
206 Due to the potential impact on system resources, the operations
209 MC_LOCKAS, MC_LOCK, MC_UNLOCKAS, and MC_UNLOCK are restricted to privi‐
210 leged processes.
211
213 The memcntl() function subsumes the operations of plock(3C) and
214 mctl(3UCB).
215 MC_HAT_ADVISE is intended to improve performance of applications that
218 use large amounts of memory on processors that support multiple hard‐
219 ware address translation mapping sizes; however, it should be used with
220 care. Not all processors support all sizes with equal efficiency. Use
221 of larger sizes may also introduce extra overhead that could reduce
222 performance or available memory. Using large sizes for one application
223 may reduce available resources for other applications and result in
224 slower system wide performance.
225
227 Upon successful completion, memcntl() returns 0; otherwise, it returns
228 −1 and sets errno to indicate an error.
229
231 The memcntl() function will fail if:
232 EAGAIN When the selection criteria match, some or all of the memory
234 identified by the operation could not be locked when MC_LOCK
235 or MC_LOCKAS was specified, some or all mappings in the
236 address range [addr, addr + len) are locked for I/O when
237 MC_HAT_ADVISE was specified, or the system has insufficient
238 resources when MC_HAT_ADVISE was specified.
239 The cmd is MC_LOCK or MC_LOCKAS and locking the memory iden‐
241 tified by this operation would exceed a limit or resource
242 control on locked memory.
243 EBUSY When the selection criteria match, some or all of the
246 addresses in the range [addr, addr + len) are locked and
247 MC_SYNC with the MS_INVALIDATE option was specified.
248 EINVAL The addr argument specifies invalid selection criteria or is
251 not a multiple of the page size as returned by sysconf(3C);
252 the addr and/or len argument does not have the value 0 when
253 MC_LOCKAS or MC_UNLOCKAS is specified; the arg argument is
254 not valid for the function specified; mha_pagesize or mha_cmd
255 is invalid; or MC_HAT_ADVISE is specified and not all pages
256 in the specified region have the same access permissions
257 within the given size boundaries.
258 ENOMEM When the selection criteria match, some or all of the
261 addresses in the range [addr, addr + len) are invalid for the
262 address space of a process or specify one or more pages which
263 are not mapped.
264 EPERM The {PRIV_PROC_LOCK_MEMORY} privilege is not asserted in the
267 effective set of the calling process and MC_LOCK, MC_LOCKAS,
268 MC_UNLOCK, or MC_UNLOCKAS was specified.
269
272 See attributes(5) for descriptions of the following attributes:
273 ┌─────────────────────────────┬─────────────────────────────┐
278 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
279 ├─────────────────────────────┼─────────────────────────────┤
280 │MT-Level │MT-Safe │
281 └─────────────────────────────┴─────────────────────────────┘
282
284 ppgsz(1), fork(2), mmap(2), mprotect(2), getpagesizes(3C), mctl(3UCB),
285 mlock(3C), mlockall(3C), msync(3C), plock(3C), sysconf(3C),
286 attributes(5), privileges(5)
287SunOS 5.11 10 Apr 2007 memcntl(2)