MEMCNTL(2) System Calls MEMCNTL(2)

NAME

memcntl - memory management control

SYNOPSIS

#include <sys/types.h>
#include <sys/mman.h>

int
memcntl(void *addr, size_t len, int cmd, void *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)
according to the bit pattern contained in attr.

The following attributes specify page mapping selection criteria:

MEMCNTL_SHARED
Page is mapped shared.

MEMCNTL_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
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 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 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 NULL 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_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. The function
returns immediately once all write operations are
scheduled (unless MS_SYNC is also specified).

MS_SYNC
Perform synchronous writes. 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 argument is not used, but must be NULL 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 NULL, 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 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
privileged processes.

USAGE

The memcntl() function subsumes the operations of plock(3C).

MC_HAT_ADVISE 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.

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 identified 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.

MT-LEVEL
MT-Safe

SEE ALSO

ppgsz(1), fork(2), mmap(2), mprotect(2), getpagesizes(3C), mlock(3C),
mlockall(3C), msync(3C), plock(3C), sysconf(3C), attributes(7),
privileges(7)

illumos March 13, 2022 illumos