System Calls memcntl(2)
NAME
memcntl - memory management control
SYNOPSIS
#include
#include
int memcntl(caddrt addr, sizet len, int cmd, caddrt 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.
PROTREAD Page can be read.
PROTWRITE Page can be written.
PROTEXEC Page can be executed.
The following criteria may also be specified:
SunOS 5.11 Last change: 10 Apr 2007 1
System Calls memcntl(2)
PROCTEXT Process text.
PROCDATA Process data.
The PROCTEXT attribute specifies all privately mapped seg-
ments with read and execute permission, and the PROCDATA
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
as follows:
MCLOCK
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 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 dif-
ferent 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 map-
ping is removed, or a page is deleted through file remo-
val or truncation, an unlock operation is implicitly
performed. If a writable MAPRIVATE 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.
MCLOCKAS
Lock in memory all pages mapped by the address space
with attributes attr. The addr and len arguments are not
used, but must be NUL and 0 respectively, to ensure
compatibility with potential future enhancements. The
arg argument is a bit pattern built from the flags:
SunOS 5.11 Last change: 10 Apr 2007 2
System Calls memcntl(2)
MCLCURENT Lock current mappings.
MCLFUTURE 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
MCLFUTURE is specified, then all mappings subsequently
added to the address space will be locked, provided suf-
ficient memory is available.
MCSYNC
Write to their backing storage locations all modified
pages in the range with attributes attr. Optionally,
invalidate cache copies. The backing storage for a modi-
fied MAPSHARED mapping is the file the page is mapped
to; the backing storage for a modified MAPRIVATE map-
ping is its swap area. The arg argument is a bit pattern
built from the flags used to control the behavior of the
operation:
MSASYNC Perform asynchronous writes.
MSYNC Perform synchronous writes.
MSINVALIDATE Invalidate mappings.
MSASYNC Return immediately once all write operations
are scheduled; with MSYNC the function will not return
until all write operations are completed.
MSINVALIDATE 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 loca-
tions. This operation should be used by applications
that require a memory object to be in a known state.
MCUNLOCK
Unlock all pages in the range with attributes attr. The
arg argument is not used, but must be 0 to ensure compa-
tibility with potential future enhancements.
MCUNLOCKAS
SunOS 5.11 Last change: 10 Apr 2007 3
System Calls memcntl(2)
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 NUL, 0
and 0, respectively, to ensure compatibility with poten-
tial future enhancements.
MCHATADVISE
Advise system how a region of user-mapped memory will be
accessed. The arg argument is interpreted as a "struct
memcntlmha *". The following members are defined in a
struct memcntlmha:
uintt mhacmd;
uintt mhaflags;
sizet mhapagesize;
The accepted values for mhacmd are:
MHAMAPSIZEVA
MHAMAPSIZESTACK
MHAMAPSIZEBSBRK
The mhaflags member is reserved for future use and must
always be set to 0. The mhapagesize member must be a
valid size as obtained from getpagesizes(3C) or the con-
stant value 0 to allow the system to choose an appropri-
ate hardware address translation mapping size.
MHAMAPSIZEVA 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 mhapagesize boundary. The entire virtual address
region from addr to addr ] len must not have any holes.
Permissions within each mhapagesize-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.
MHAMAPSIZESTACK sets the preferred hardware address
translation mapping size of the process main thread
stack segment. The addr and len arguments must be NUL
and 0, respectively.
MHAMAPSIZEBSBRK sets the preferred hardware address
translation mapping size of the process heap. The addr
and len arguments must be NUL and 0, respectively. See
the NOTES section of the ppgsz(1) manual page for addi-
tional information on process heap alignment.
SunOS 5.11 Last change: 10 Apr 2007 4
System Calls memcntl(2)
The attr argument must be 0 for all MCHATADVISE opera-
tions.
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 opera-
tions MCLOCKAS, MCLOCK, MCUNLOCKAS, and MCUNLOCK are
restricted to privileged processes.
USAGE
The memcntl() function subsumes the operations of plock(3C)
and mctl(3UCB).
MCHATADVISE 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.
ERORS
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 MCLOCK or MCLOCKAS was specified,
some or all mappings in the address range [addr,
addr ] len) are locked for I/O when MCHATADVISE
was specified, or the system has insufficient
resources when MCHATADVISE was specified.
The cmd is MCLOCK or MCLOCKAS and locking the
memory identified by this operation would exceed a
limit or resource control on locked memory.
SunOS 5.11 Last change: 10 Apr 2007 5
System Calls memcntl(2)
EBUSY When the selection criteria match, some or all of
the addresses in the range [addr, addr ] len) are
locked and MCSYNC with the MSINVALIDATE option
was specified.
EINVAL The addr argument specifies invalid selection cri-
teria 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 MCLOCKAS
or MCUNLOCKAS is specified; the arg argument is
not valid for the function specified; mhapagesize
or mhacmd is invalid; or MCHATADVISE is speci-
fied 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 {PRIVPROCLOCKMEMORY} privilege is not
asserted in the effective set of the calling pro-
cess and MCLOCK, MCLOCKAS, MCUNLOCK, or
MCUNLOCKAS was specified.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE 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), privileges(5)
SunOS 5.11 Last change: 10 Apr 2007 6
|
