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