memcntl(2)
NAME
memcntl - memory management control
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
int memcntl(caddr_t addr, size_t len, int cmd, caddr_t arg,
int attr, int mask);
DESCRIPTION
The memcntl() function allows the calling process to apply a
variety of control operations over the address space identi-
fied by the mappings established for the address range
[addr, addr + len).
The addr argument must be a multiple of the pagesize as
returned by sysconf(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 attr.
The following attributes specify page mapping selection cri-
teria:
SHARED
Page is mapped shared.
PRIVATE
Page is mapped private.
The following attributes specify page protection selection
criteria. The selection criteria are constructed by a bit-
wise OR operation on the attribute bits and must match
exactly.
PROT_READ
Page can be read.
PROT_WRITE
Page can be written.
PROT_EXEC
Page can be executed.
The following criteria may also be specified:
PROC_TEXT
Process text.
PROC_DATA
Process data.
The PROC_TEXT attribute specifies all privately mapped seg-
ments with read and execute permission, and the PROC_DATA
attribute specifies all privately mapped segments with write
permission.
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, attr must have the value 0.
The operation to be performed is identified by the argument
cmd. The symbolic names for the operations are defined in
<sys/mman.h> as follows:
MC_LOCK
Lock in memory all pages in the range with attributes
attr. A given page may be locked multiple times
through different mappings; however, within a given
mapping, page locks do not nest. Multiple lock opera-
tions 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 visi-
ble through a different mapping in the locking pro-
cess) is locked in memory as long as the locking pro-
cess 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 writ-
able MAP_PRIVATE page in the address range is changed,
the lock will be transferred to the private page.
The arg argument is not used, but must be 0 to ensure
compatibility with potential future enhancements.
MC_LOCKAS
Lock in memory all pages mapped by the address space
with attributes attr. The addr and len arguments are
not used, but must be NULL and 0 respectively, to
ensure compatibility with potential future enhance-
ments. The arg argument is a bit pattern built from
the flags:
MCL_CURRENT
Lock current mappings.
MCL_FUTURE
Lock future mappings.
The value of arg 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 MCL_FUTURE is specified, then all mappings
subsequently added to the address space will be
locked, provided sufficient memory is available.
MC_SYNC
Write to their backing storage locations all modified
pages in the range with attributes attr. Optionally,
invalidate cache copies. The backing storage for a
modified MAP_SHARED mapping is the file the page is
mapped to; the backing storage for a modified
MAP_PRIVATE mapping is its swap area. The arg argument
is a bit pattern built from the flags used to control
the behavior of the operation:
MS_ASYNC
Perform asynchronous writes.
MS_SYNC
Perform synchronous writes.
MS_INVALIDATE
Invalidate mappings.
MS_ASYNC Return immediately once all write operations are
scheduled; with MS_SYNC the function will not return until
all write operations are completed.
MS_INVALIDATE 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 applica-
tions that require a memory object to be in a known
state.
MC_UNLOCK
Unlock all pages in the range with attributes attr.
The arg argument is not used, but must be 0 to ensure
compatibility with potential future enhancements.
MC_UNLOCKAS
Remove address space memory locks and locks on all
pages in the address space with attributes attr. The
addr, len, and arg arguments are not used, but must be
NULL, 0 and 0, respectively, to ensure compatibility
with potential future enhancements.
MC_HAT_ADVISE
Advise system how a region of user-mapped memory will
be accessed. The arg argument is interpreted as a
"struct memcntl_mha *". The following members are
defined in a struct memcntl_mha:
uint_t mha_cmd;
uint_t mha_flags;
size_t mha_pagesize;
The accepted values for mha_cmd are:
MHA_MAPSIZE_VA
MHA_MAPSIZE_STACK
MHA_MAPSIZE_BSSBRK
The mha_flags member is reserved for future use and
must always be set to 0. The mha_pagesize member must
be a valid size as obtained from getpagesizes(3C) or
the constant value 0 to allow the system to choose an
appropriate hardware address translation mapping size.
MHA_MAPSIZE_VA sets the preferred hardware address
translation mapping size of the region of memory from
addr to addr + len. Both addr and len must be aligned
to an mha_pagesize boundary. The entire virtual
address region from addr to addr + len must not have
any holes. Permissions within each mha_pagesize-
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 con-
siderations.
MHA_MAPSIZE_STACK sets the preferred hardware address
translation mapping size of the process main thread
stack segment. The addr and len arguments must be NULL
and 0, respectively.
MHA_MAPSIZE_BSSBRK sets the preferred hardware address
translation mapping size of the process heap. The addr
and len arguments must be NULL and 0, respectively.
See the NOTES section of the ppgsz(1) manual page for
additional information on process heap alignment.
The attr argument must be 0 for all MC_HAT_ADVISE
operations.
The mask argument must be 0; it is reserved for future use.
Locks established with the lock operations are not inherited
by a child process after fork(2). The memcntl() function
fails if it attempts to lock more memory than a system-
specific limit.
Due to the potential impact on system resources, all opera-
tions except MC_SYNC are restricted to processes with
superuser effective user ID.
USAGE
The memcntl() function subsumes the operations of plock(3C)
and mctl(3UCB).
MC_HAT_ADVISE is intended to improve performance of applica-
tions 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 perfor-
mance or available memory. Using large sizes for one appli-
cation may reduce available resources for other applications
and result in slower system wide performance.
RETURN VALUES
Upon successful completion, memcntl() returns 0; otherwise,
it returns -1 and sets errno to indicate an error.
ERRORS
The memcntl() function will fail if:
EAGAIN
When the selection criteria match, some or all of the
memory identified by the operation could not be locked
when MC_LOCK or MC_LOCKAS was specified, some or all
mappings in the address range [addr, addr + len) are
locked for I/O when MC_HAT_ADVISE was specified, or
the system has insufficient resources when
MC_HAT_ADVISE was specified.
EBUSY When the selection criteria match, some or all of the
addresses in the range [addr, addr + len) are locked
and MC_SYNC with the MS_INVALIDATE option was speci-
fied.
EINVAL
The addr argument specifies invalid selection criteria
or is not a multiple of the page size as returned by
sysconf(3C); the addr and/or len argument does not
have the value 0 when MC_LOCKAS or MC_UNLOCKAS is
specified; the arg argument is not valid for the func-
tion specified; mha_pagesize or mha_cmd is invalid; or
MC_HAT_ADVISE is specified and not all pages in the
specified region have the same access permissions
within the given size boundaries.
ENOMEM
When the selection criteria match, some or all of the
addresses in the range [addr, addr + len) are invalid
for the address space of a process or specify one or
more pages which are not mapped.
EPERM The process's effective user ID is not superuser and
MC_LOCK, MC_LOCKAS, MC_UNLOCK, or MC_UNLOCKAS was
specified.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
ppgsz(1), fork(2) mmap(2), mprotect(2), getpagesizes(3C),
mctl(3UCB), mlock(3C), mlockall(3C), msync(3C), plock(3C),
sysconf(3C), attributes(5)
Man(1) output converted with
man2html