| blob | 0e380753d191dd783fd0b31d9b9456e5afe8e088 |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH MEMCNTL 2 "Apr 10, 2007"
8 .SH NAME
9 memcntl \- memory management control
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <sys/types.h>
14 #include <sys/mman.h>
16 \fBint\fR \fBmemcntl\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIcmd\fR, \fBcaddr_t\fR \fIarg\fR,
17 \fBint\fR \fIattr\fR, \fBint\fR \fImask\fR);
18 .fi
20 .SH DESCRIPTION
21 .sp
22 .LP
23 The \fBmemcntl()\fR function allows the calling process to apply a variety of
24 control operations over the address space identified by the mappings
25 established for the address range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR).
26 .sp
27 .LP
28 The \fIaddr\fR argument must be a multiple of the pagesize as returned by
29 \fBsysconf\fR(3C). The scope of the control operations can be further defined
30 with additional selection criteria (in the form of attributes) according to the
31 bit pattern contained in \fIattr\fR.
32 .sp
33 .LP
34 The following attributes specify page mapping selection criteria:
35 .sp
36 .ne 2
37 .na
38 \fB\fBSHARED\fR\fR
39 .ad
40 .RS 11n
41 Page is mapped shared.
42 .RE
44 .sp
45 .ne 2
46 .na
47 \fB\fBPRIVATE\fR\fR
48 .ad
49 .RS 11n
50 Page is mapped private.
51 .RE
53 .sp
54 .LP
55 The following attributes specify page protection selection criteria. The
56 selection criteria are constructed by a bitwise OR operation on the attribute
57 bits and must match exactly.
58 .sp
59 .ne 2
60 .na
61 \fB\fBPROT_READ\fR\fR
62 .ad
63 .RS 14n
64 Page can be read.
65 .RE
67 .sp
68 .ne 2
69 .na
70 \fB\fBPROT_WRITE\fR\fR
71 .ad
72 .RS 14n
73 Page can be written.
74 .RE
76 .sp
77 .ne 2
78 .na
79 \fB\fBPROT_EXEC\fR\fR
80 .ad
81 .RS 14n
82 Page can be executed.
83 .RE
85 .sp
86 .LP
87 The following criteria may also be specified:
88 .sp
89 .ne 2
90 .na
91 \fB\fBPROC_TEXT\fR\fR
92 .ad
93 .RS 13n
94 Process text.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fBPROC_DATA\fR\fR
101 .ad
102 .RS 13n
103 Process data.
104 .RE
106 .sp
107 .LP
108 The \fBPROC_TEXT\fR attribute specifies all privately mapped segments with read
109 and execute permission, and the \fBPROC_DATA\fR attribute specifies all
110 privately mapped segments with write permission.
111 .sp
112 .LP
113 Selection criteria can be used to describe various abstract memory objects
114 within the address space on which to operate. If an operation shall not be
115 constrained by the selection criteria, \fIattr\fR must have the value \fB0\fR.
116 .sp
117 .LP
118 The operation to be performed is identified by the argument \fIcmd\fR. The
119 symbolic names for the operations are defined in <\fBsys/mman.h\fR> as follows:
120 .sp
121 .ne 2
122 .na
123 \fB\fBMC_LOCK\fR\fR
124 .ad
125 .sp .6
126 .RS 4n
127 Lock in memory all pages in the range with attributes \fIattr\fR. A given page
128 may be locked multiple times through different mappings; however, within a
129 given mapping, page locks do not nest. Multiple lock operations on the same
130 address in the same process will all be removed with a single unlock operation.
131 A page locked in one process and mapped in another (or visible through a
132 different mapping in the locking process) is locked in memory as long as the
133 locking process does neither an implicit nor explicit unlock operation. If a
134 locked mapping is removed, or a page is deleted through file removal or
135 truncation, an unlock operation is implicitly performed. If a writable
136 \fBMAP_PRIVATE\fR page in the address range is changed, the lock will be
137 transferred to the private page.
138 .sp
139 The \fIarg\fR argument is not used, but must be 0 to ensure compatibility with
140 potential future enhancements.
141 .RE
143 .sp
144 .ne 2
145 .na
146 \fB\fBMC_LOCKAS\fR\fR
147 .ad
148 .sp .6
149 .RS 4n
150 Lock in memory all pages mapped by the address space with attributes
151 \fIattr\fR. The \fIaddr\fR and \fIlen\fR arguments are not used, but must be
152 \fINULL\fR and \fB0\fR respectively, to ensure compatibility with potential
153 future enhancements. The \fIarg\fR argument is a bit pattern built from the
154 flags:
155 .sp
156 .ne 2
157 .na
158 \fB\fBMCL_CURRENT\fR\fR
159 .ad
160 .RS 15n
161 Lock current mappings.
162 .RE
164 .sp
165 .ne 2
166 .na
167 \fB\fBMCL_FUTURE\fR\fR
168 .ad
169 .RS 15n
170 Lock future mappings.
171 .RE
173 The value of \fIarg\fR determines whether the pages to be locked are those
174 currently mapped by the address space, those that will be mapped in the future,
175 or both. If \fBMCL_FUTURE\fR is specified, then all mappings subsequently added
176 to the address space will be locked, provided sufficient memory is available.
177 .RE
179 .sp
180 .ne 2
181 .na
182 \fB\fBMC_SYNC\fR\fR
183 .ad
184 .sp .6
185 .RS 4n
186 Write to their backing storage locations all modified pages in the range with
187 attributes \fIattr\fR. Optionally, invalidate cache copies. The backing storage
188 for a modified \fBMAP_SHARED\fR mapping is the file the page is mapped to; the
189 backing storage for a modified \fBMAP_PRIVATE\fR mapping is its swap area. The
190 \fIarg\fR argument is a bit pattern built from the flags used to control the
191 behavior of the operation:
192 .sp
193 .ne 2
194 .na
195 \fB\fBMS_ASYNC\fR\fR
196 .ad
197 .RS 17n
198 Perform asynchronous writes.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fBMS_SYNC\fR\fR
205 .ad
206 .RS 17n
207 Perform synchronous writes.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fBMS_INVALIDATE\fR\fR
214 .ad
215 .RS 17n
216 Invalidate mappings.
217 .RE
219 \fBMS_ASYNC\fR Return immediately once all write operations are scheduled; with
220 \fBMS_SYNC\fR the function will not return until all write operations are
221 completed.
222 .sp
223 \fBMS_INVALIDATE\fR Invalidate all cached copies of data in memory, so that
224 further references to the pages will be obtained by the system from their
225 backing storage locations. This operation should be used by applications that
226 require a memory object to be in a known state.
227 .RE
229 .sp
230 .ne 2
231 .na
232 \fB\fBMC_UNLOCK\fR\fR
233 .ad
234 .sp .6
235 .RS 4n
236 Unlock all pages in the range with attributes \fIattr\fR. The \fIarg\fR
237 argument is not used, but must be \fB0\fR to ensure compatibility with
238 potential future enhancements.
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fBMC_UNLOCKAS\fR\fR
245 .ad
246 .sp .6
247 .RS 4n
248 Remove address space memory locks and locks on all pages in the address space
249 with attributes \fIattr\fR. The \fIaddr\fR, \fIlen\fR, and \fIarg\fR arguments
250 are not used, but must be \fINULL\fR, 0 and 0, respectively, to ensure
251 compatibility with potential future enhancements.
252 .RE
254 .sp
255 .ne 2
256 .na
257 \fB\fBMC_HAT_ADVISE\fR\fR
258 .ad
259 .sp .6
260 .RS 4n
261 Advise system how a region of user-mapped memory will be accessed. The
262 \fIarg\fR argument is interpreted as a "\fBstruct memcntl_mha *\fR". The
263 following members are defined in a \fBstruct memcntl_mha\fR:
264 .sp
265 .in +2
266 .nf
267 uint_t mha_cmd;
268 uint_t mha_flags;
269 size_t mha_pagesize;
270 .fi
271 .in -2
273 The accepted values for \fBmha_cmd\fR are:
274 .sp
275 .in +2
276 .nf
277 MHA_MAPSIZE_VA
278 MHA_MAPSIZE_STACK
279 MHA_MAPSIZE_BSSBRK
280 .fi
281 .in -2
283 The \fBmha_flags\fR member is reserved for future use and must always be set to
284 0. The \fBmha_pagesize\fR member must be a valid size as obtained from
285 \fBgetpagesizes\fR(3C) or the constant value 0 to allow the system to choose an
286 appropriate hardware address translation mapping size.
287 .sp
288 \fBMHA_MAPSIZE_VA\fR sets the preferred hardware address translation mapping
289 size of the region of memory from \fIaddr\fR to \fIaddr\fR + \fIlen\fR. Both
290 \fIaddr\fR and \fIlen\fR must be aligned to an \fBmha_pagesize\fR boundary. The
291 entire virtual address region from \fIaddr\fR to \fIaddr\fR + \fIlen\fR must
292 not have any holes. Permissions within each \fBmha_pagesize\fR-aligned portion
293 of the region must be consistent. When a size of 0 is specified, the system
294 selects an appropriate size based on the size and alignment of the memory
295 region, type of processor, and other considerations.
296 .sp
297 \fBMHA_MAPSIZE_STACK\fR sets the preferred hardware address translation mapping
298 size of the process main thread stack segment. The \fIaddr\fR and \fIlen\fR
299 arguments must be \fINULL\fR and 0, respectively.
300 .sp
301 \fBMHA_MAPSIZE_BSSBRK\fR sets the preferred hardware address translation
302 mapping size of the process heap. The \fIaddr\fR and \fIlen\fR arguments must
303 be \fINULL\fR and 0, respectively. See the NOTES section of the \fBppgsz\fR(1)
304 manual page for additional information on process heap alignment.
305 .sp
306 The \fIattr\fR argument must be 0 for all \fBMC_HAT_ADVISE\fR operations.
307 .RE
309 .sp
310 .LP
311 The \fImask\fR argument must be \fB0\fR; it is reserved for future use.
312 .sp
313 .LP
314 Locks established with the lock operations are not inherited by a child process
315 after \fBfork\fR(2). The \fBmemcntl()\fR function fails if it attempts to lock
316 more memory than a system-specific limit.
317 .sp
318 .LP
319 Due to the potential impact on system resources, the operations
320 \fBMC_LOCKAS\fR, \fBMC_LOCK\fR, \fBMC_UNLOCKAS\fR, and \fBMC_UNLOCK\fR are
321 restricted to privileged processes.
322 .SH USAGE
323 .sp
324 .LP
325 The \fBmemcntl()\fR function subsumes the operations of \fBplock\fR(3C) and
326 \fBmctl\fR(3UCB).
327 .sp
328 .LP
329 \fBMC_HAT_ADVISE\fR is intended to improve performance of applications that use
330 large amounts of memory on processors that support multiple hardware address
331 translation mapping sizes; however, it should be used with care. Not all
332 processors support all sizes with equal efficiency. Use of larger sizes may
333 also introduce extra overhead that could reduce performance or available
334 memory. Using large sizes for one application may reduce available resources
335 for other applications and result in slower system wide performance.
336 .SH RETURN VALUES
337 .sp
338 .LP
339 Upon successful completion, \fBmemcntl()\fR returns \fB0\fR; otherwise, it
340 returns \fB\(mi1\fR and sets \fBerrno\fR to indicate an error.
341 .SH ERRORS
342 .sp
343 .LP
344 The \fBmemcntl()\fR function will fail if:
345 .sp
346 .ne 2
347 .na
348 \fB\fBEAGAIN\fR\fR
349 .ad
350 .RS 10n
351 When the selection criteria match, some or all of the memory identified by the
352 operation could not be locked when \fBMC_LOCK\fR or \fBMC_LOCKAS\fR was
353 specified, some or all mappings in the address range [\fIaddr\fR, \fIaddr\fR +
354 \fIlen\fR) are locked for I/O when \fBMC_HAT_ADVISE\fR was specified, or the
355 system has insufficient resources when \fBMC_HAT_ADVISE\fR was specified.
356 .sp
357 The \fIcmd\fR is \fBMC_LOCK\fR or \fBMC_LOCKAS\fR and locking the memory
358 identified by this operation would exceed a limit or resource control on locked
359 memory.
360 .RE
362 .sp
363 .ne 2
364 .na
365 \fB\fBEBUSY\fR\fR
366 .ad
367 .RS 10n
368 When the selection criteria match, some or all of the addresses in the range
369 [\fIaddr, addr + len\fR) are locked and \fBMC_SYNC\fR with the
370 \fBMS_INVALIDATE\fR option was specified.
371 .RE
373 .sp
374 .ne 2
375 .na
376 \fB\fBEINVAL\fR\fR
377 .ad
378 .RS 10n
379 The \fIaddr\fR argument specifies invalid selection criteria or is not a
380 multiple of the page size as returned by \fBsysconf\fR(3C); the \fIaddr\fR
381 and/or \fIlen\fR argument does not have the value \fB0\fR when \fBMC_LOCKAS\fR
382 or \fBMC_UNLOCKAS\fR is specified; the \fIarg\fR argument is not valid for the
383 function specified; \fBmha_pagesize\fR or \fBmha_cmd\fR is invalid; or
384 \fBMC_HAT_ADVISE\fR is specified and not all pages in the specified region have
385 the same access permissions within the given size boundaries.
386 .RE
388 .sp
389 .ne 2
390 .na
391 \fB\fBENOMEM\fR\fR
392 .ad
393 .RS 10n
394 When the selection criteria match, some or all of the addresses in the range
395 [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) are invalid for the address space of a
396 process or specify one or more pages which are not mapped.
397 .RE
399 .sp
400 .ne 2
401 .na
402 \fB\fBEPERM\fR\fR
403 .ad
404 .RS 10n
405 The {\fBPRIV_PROC_LOCK_MEMORY\fR} privilege is not asserted in the effective
406 set of the calling process and \fBMC_LOCK\fR, \fBMC_LOCKAS\fR, \fBMC_UNLOCK\fR,
407 or \fBMC_UNLOCKAS\fR was specified.
408 .RE
410 .SH ATTRIBUTES
411 .sp
412 .LP
413 See \fBattributes\fR(5) for descriptions of the following attributes:
414 .sp
416 .sp
417 .TS
418 box;
419 c | c
420 l | l .
421 ATTRIBUTE TYPE ATTRIBUTE VALUE
422 _
423 MT-Level MT-Safe
424 .TE
426 .SH SEE ALSO
427 .sp
428 .LP
429 \fBppgsz\fR(1), \fBfork\fR(2), \fBmmap\fR(2), \fBmprotect\fR(2),
430 \fBgetpagesizes\fR(3C), \fBmctl\fR(3UCB), \fBmlock\fR(3C), \fBmlockall\fR(3C),
431 \fBmsync\fR(3C), \fBplock\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5),
432 \fBprivileges\fR(5)