MEMCNTL(2)MEMCNTL(2)NAMEmemcntl - 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 identified 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) accord‐
ing to the bit pattern contained in attr.
The following attributes specify page mapping selection criteria:
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 bitwise 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 segments 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 fol‐
lows:
MC_LOCK
Lock in memory all pages in the range with attributes attr. A given
page may be locked multiple times through different mappings; how‐
ever, 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 map‐
ping in the locking process) is locked in memory as long as the
locking process does neither an implicit nor explicit unlock opera‐
tion. If a locked mapping is removed, or a page is deleted through
file removal or truncation, an unlock operation is implicitly per‐
formed. If a writable 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 enhancements. 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_PRI‐
VATE 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 sched‐
uled; 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 applications that require a memory object to be in a known
state.
MC_UNLOCK
Unlock all pages in the range with attributes attr. The arg argu‐
ment is not used, but must be 0 to ensure compatibility with poten‐
tial 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 argu‐
ments 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 map‐
ping 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 considerations.
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, the operations
MC_LOCKAS, MC_LOCK, MC_UNLOCKAS, and MC_UNLOCK are restricted to privi‐
leged processes.
USAGE
The memcntl() function subsumes the operations of plock(3C) and
mctl(3UCB).
MC_HAT_ADVISE is intended to improve performance of applications that
use large amounts of memory on processors that support multiple hard‐
ware 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.
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.
The cmd is MC_LOCK or MC_LOCKAS and locking the memory iden‐
tified by this operation would exceed a limit or resource
control on locked memory.
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 specified.
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 function 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 {PRIV_PROC_LOCK_MEMORY} privilege is not asserted in the
effective set of the calling process and MC_LOCK, MC_LOCKAS,
MC_UNLOCK, or MC_UNLOCKAS was specified.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌───────────────┬─────────────────┐
│ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├───────────────┼─────────────────┤
│MT-Level │ MT-Safe │
└───────────────┴─────────────────┘
SEE ALSOppgsz(1), fork(2), mmap(2), mprotect(2), getpagesizes(3C), mctl(3UCB),
mlock(3C), mlockall(3C), msync(3C), plock(3C), sysconf(3C),
attributes(5), privileges(5)
Apr 10, 2007 MEMCNTL(2)