'\" te .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved .\" Copyright 1989 AT&T .\" 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. .\" 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. .\" 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] .TH memcntl 2 "10 Apr 2007" "SunOS 5.11" "System Calls" .SH NAME memcntl \- memory management control .SH SYNOPSIS .LP .nf #include #include \fBint\fR \fBmemcntl\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIcmd\fR, \fBcaddr_t\fR \fIarg\fR, \fBint\fR \fIattr\fR, \fBint\fR \fImask\fR); .fi .SH DESCRIPTION .sp .LP The \fBmemcntl()\fR function allows the calling process to apply a variety of control operations over the address space identified by the mappings established for the address range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR). .sp .LP The \fIaddr\fR argument must be a multiple of the pagesize as returned by \fBsysconf\fR(3C). The scope of the control operations can be further defined with additional selection criteria (in the form of attributes) according to the bit pattern contained in \fIattr\fR. .sp .LP The following attributes specify page mapping selection criteria: .sp .ne 2 .mk .na \fB\fBSHARED\fR\fR .ad .RS 11n .rt Page is mapped shared. .RE .sp .ne 2 .mk .na \fB\fBPRIVATE\fR\fR .ad .RS 11n .rt Page is mapped private. .RE .sp .LP The following attributes specify page protection selection criteria. The selection criteria are constructed by a bitwise OR operation on the attribute bits and must match exactly. .sp .ne 2 .mk .na \fB\fBPROT_READ\fR\fR .ad .RS 14n .rt Page can be read. .RE .sp .ne 2 .mk .na \fB\fBPROT_WRITE\fR\fR .ad .RS 14n .rt Page can be written. .RE .sp .ne 2 .mk .na \fB\fBPROT_EXEC\fR\fR .ad .RS 14n .rt Page can be executed. .RE .sp .LP The following criteria may also be specified: .sp .ne 2 .mk .na \fB\fBPROC_TEXT\fR\fR .ad .RS 13n .rt Process text. .RE .sp .ne 2 .mk .na \fB\fBPROC_DATA\fR\fR .ad .RS 13n .rt Process data. .RE .sp .LP The \fBPROC_TEXT\fR attribute specifies all privately mapped segments with read and execute permission, and the \fBPROC_DATA\fR attribute specifies all privately mapped segments with write permission. .sp .LP Selection criteria can be used to describe various abstract memory objects within the address space on which to operate. If an operation shall not be constrained by the selection criteria, \fIattr\fR must have the value \fB0\fR. .sp .LP The operation to be performed is identified by the argument \fIcmd\fR. The symbolic names for the operations are defined in <\fBsys/mman.h\fR> as follows: .sp .ne 2 .mk .na \fB\fBMC_LOCK\fR\fR .ad .sp .6 .RS 4n Lock in memory all pages in the range with attributes \fIattr\fR. A given page may be locked multiple times through different mappings; however, within a given mapping, page locks do not nest. Multiple lock operations on the same address in the same process will all be removed with a single unlock operation. A page locked in one process and mapped in another (or visible through a different mapping in the locking process) is locked in memory as long as the locking process does neither an implicit nor explicit unlock operation. If a locked mapping is removed, or a page is deleted through file removal or truncation, an unlock operation is implicitly performed. If a writable \fBMAP_PRIVATE\fR page in the address range is changed, the lock will be transferred to the private page. .sp The \fIarg\fR argument is not used, but must be 0 to ensure compatibility with potential future enhancements. .RE .sp .ne 2 .mk .na \fB\fBMC_LOCKAS\fR\fR .ad .sp .6 .RS 4n Lock in memory all pages mapped by the address space with attributes \fIattr\fR. The \fIaddr\fR and \fIlen\fR arguments are not used, but must be \fINULL\fR and \fB0\fR respectively, to ensure compatibility with potential future enhancements. The \fIarg\fR argument is a bit pattern built from the flags: .sp .ne 2 .mk .na \fB\fBMCL_CURRENT\fR\fR .ad .RS 15n .rt Lock current mappings. .RE .sp .ne 2 .mk .na \fB\fBMCL_FUTURE\fR\fR .ad .RS 15n .rt Lock future mappings. .RE The value of \fIarg\fR determines whether the pages to be locked are those currently mapped by the address space, those that will be mapped in the future, or both. If \fBMCL_FUTURE\fR is specified, then all mappings subsequently added to the address space will be locked, provided sufficient memory is available. .RE .sp .ne 2 .mk .na \fB\fBMC_SYNC\fR\fR .ad .sp .6 .RS 4n Write to their backing storage locations all modified pages in the range with attributes \fIattr\fR. Optionally, invalidate cache copies. The backing storage for a modified \fBMAP_SHARED\fR mapping is the file the page is mapped to; the backing storage for a modified \fBMAP_PRIVATE\fR mapping is its swap area. The \fIarg\fR argument is a bit pattern built from the flags used to control the behavior of the operation: .sp .ne 2 .mk .na \fB\fBMS_ASYNC\fR\fR .ad .RS 17n .rt Perform asynchronous writes. .RE .sp .ne 2 .mk .na \fB\fBMS_SYNC\fR\fR .ad .RS 17n .rt Perform synchronous writes. .RE .sp .ne 2 .mk .na \fB\fBMS_INVALIDATE\fR\fR .ad .RS 17n .rt Invalidate mappings. .RE \fBMS_ASYNC\fR Return immediately once all write operations are scheduled; with \fBMS_SYNC\fR the function will not return until all write operations are completed. .sp \fBMS_INVALIDATE\fR Invalidate all cached copies of data in memory, so that further references to the pages will be obtained by the system from their backing storage locations. This operation should be used by applications that require a memory object to be in a known state. .RE .sp .ne 2 .mk .na \fB\fBMC_UNLOCK\fR\fR .ad .sp .6 .RS 4n Unlock all pages in the range with attributes \fIattr\fR. The \fIarg\fR argument is not used, but must be \fB0\fR to ensure compatibility with potential future enhancements. .RE .sp .ne 2 .mk .na \fB\fBMC_UNLOCKAS\fR\fR .ad .sp .6 .RS 4n Remove address space memory locks and locks on all pages in the address space with attributes \fIattr\fR. The \fIaddr\fR, \fIlen\fR, and \fIarg\fR arguments are not used, but must be \fINULL\fR, 0 and 0, respectively, to ensure compatibility with potential future enhancements. .RE .sp .ne 2 .mk .na \fB\fBMC_HAT_ADVISE\fR\fR .ad .sp .6 .RS 4n Advise system how a region of user-mapped memory will be accessed. The \fIarg\fR argument is interpreted as a "\fBstruct memcntl_mha *\fR". The following members are defined in a \fBstruct memcntl_mha\fR: .sp .in +2 .nf uint_t mha_cmd; uint_t mha_flags; size_t mha_pagesize; .fi .in -2 The accepted values for \fBmha_cmd\fR are: .sp .in +2 .nf MHA_MAPSIZE_VA MHA_MAPSIZE_STACK MHA_MAPSIZE_BSSBRK .fi .in -2 The \fBmha_flags\fR member is reserved for future use and must always be set to 0. The \fBmha_pagesize\fR member must be a valid size as obtained from \fBgetpagesizes\fR(3C) or the constant value 0 to allow the system to choose an appropriate hardware address translation mapping size. .sp \fBMHA_MAPSIZE_VA\fR sets the preferred hardware address translation mapping size of the region of memory from \fIaddr\fR to \fIaddr\fR + \fIlen\fR. Both \fIaddr\fR and \fIlen\fR must be aligned to an \fBmha_pagesize\fR boundary. The entire virtual address region from \fIaddr\fR to \fIaddr\fR + \fIlen\fR must not have any holes. Permissions within each \fBmha_pagesize\fR-aligned portion of the region must be consistent. When a size of 0 is specified, the system selects an appropriate size based on the size and alignment of the memory region, type of processor, and other considerations. .sp \fBMHA_MAPSIZE_STACK\fR sets the preferred hardware address translation mapping size of the process main thread stack segment. The \fIaddr\fR and \fIlen\fR arguments must be \fINULL\fR and 0, respectively. .sp \fBMHA_MAPSIZE_BSSBRK\fR sets the preferred hardware address translation mapping size of the process heap. The \fIaddr\fR and \fIlen\fR arguments must be \fINULL\fR and 0, respectively. See the NOTES section of the \fBppgsz\fR(1) manual page for additional information on process heap alignment. .sp The \fIattr\fR argument must be 0 for all \fBMC_HAT_ADVISE\fR operations. .RE .sp .LP The \fImask\fR argument must be \fB0\fR; it is reserved for future use. .sp .LP Locks established with the lock operations are not inherited by a child process after \fBfork\fR(2). The \fBmemcntl()\fR function fails if it attempts to lock more memory than a system-specific limit. .sp .LP Due to the potential impact on system resources, the operations \fBMC_LOCKAS\fR, \fBMC_LOCK\fR, \fBMC_UNLOCKAS\fR, and \fBMC_UNLOCK\fR are restricted to privileged processes. .SH USAGE .sp .LP The \fBmemcntl()\fR function subsumes the operations of \fBplock\fR(3C) and \fBmctl\fR(3UCB). .sp .LP \fBMC_HAT_ADVISE\fR is intended to improve performance of applications that use large amounts of memory on processors that support multiple hardware address translation mapping sizes; however, it should be used with care. Not all processors support all sizes with equal efficiency. Use of larger sizes may also introduce extra overhead that could reduce performance or available memory. Using large sizes for one application may reduce available resources for other applications and result in slower system wide performance. .SH RETURN VALUES .sp .LP Upon successful completion, \fBmemcntl()\fR returns \fB0\fR; otherwise, it returns \fB\(mi1\fR and sets \fBerrno\fR to indicate an error. .SH ERRORS .sp .LP The \fBmemcntl()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEAGAIN\fR\fR .ad .RS 10n .rt When the selection criteria match, some or all of the memory identified by the operation could not be locked when \fBMC_LOCK\fR or \fBMC_LOCKAS\fR was specified, some or all mappings in the address range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) are locked for I/O when \fBMC_HAT_ADVISE\fR was specified, or the system has insufficient resources when \fBMC_HAT_ADVISE\fR was specified. .sp The \fIcmd\fR is \fBMC_LOCK\fR or \fBMC_LOCKAS\fR and locking the memory identified by this operation would exceed a limit or resource control on locked memory. .RE .sp .ne 2 .mk .na \fB\fBEBUSY\fR\fR .ad .RS 10n .rt When the selection criteria match, some or all of the addresses in the range [\fIaddr, addr + len\fR) are locked and \fBMC_SYNC\fR with the \fBMS_INVALIDATE\fR option was specified. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 10n .rt The \fIaddr\fR argument specifies invalid selection criteria or is not a multiple of the page size as returned by \fBsysconf\fR(3C); the \fIaddr\fR and/or \fIlen\fR argument does not have the value \fB0\fR when \fBMC_LOCKAS\fR or \fBMC_UNLOCKAS\fR is specified; the \fIarg\fR argument is not valid for the function specified; \fBmha_pagesize\fR or \fBmha_cmd\fR is invalid; or \fBMC_HAT_ADVISE\fR is specified and not all pages in the specified region have the same access permissions within the given size boundaries. .RE .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt When the selection criteria match, some or all of the addresses in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) are invalid for the address space of a process or specify one or more pages which are not mapped. .RE .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 10n .rt The {\fBPRIV_PROC_LOCK_MEMORY\fR} privilege is not asserted in the effective set of the calling process and \fBMC_LOCK\fR, \fBMC_LOCKAS\fR, \fBMC_UNLOCK\fR, or \fBMC_UNLOCKAS\fR was specified. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ MT-LevelMT-Safe .TE .SH SEE ALSO .sp .LP \fBppgsz\fR(1), \fBfork\fR(2), \fBmmap\fR(2), \fBmprotect\fR(2), \fBgetpagesizes\fR(3C), \fBmctl\fR(3UCB), \fBmlock\fR(3C), \fBmlockall\fR(3C), \fBmsync\fR(3C), \fBplock\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBprivileges\fR(5)