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 );
PARAMETERS
Specifies a multiple of pagesize as returned by the sysconf routine
where implemented; otherwise, addr must contain the value NULL. Where
used, control operations can be further defined with the bit pattern
contained in attr. Must specify 0 (zero) for the MC_LOCKALL and
MC_UNLOCKALL commands. Specifies the operation to be performed. See
the Operations section for a list of the symbolic names used for the
operations as they are defined by <sys/mman.h>. Specifies a bit pat‐
tern built from the flags used to control the behavior of the operation
where implemented; otherwise, arg must contain the value 0 (zero).
Specifies the page attributes. If an operation is not to be controlled
by these attributes, the attr argument must contain the value 0 (zero).
Must specify 0 (zero). Reserved for future use.
DESCRIPTION
The memcntl function enables the calling process to exercise various
control operations over the address space which is identified by the
mappings set for the address range [addr, addr, + len].
Selection Criteria
The scope of the control operations can be further specified with addi‐
tional selection criteria (in the form of attributes) according to the
bits contained in the attr parameter.
To specify the selection criteria for page mapping, use the following
attributes: Page is mapped shared. Page is mapped private.
To specify the selection criteria for page protection, use the follow‐
ing attributes: Page is readable. Page is writable. Page is exe‐
cutable.
Additional criteria includes the following: Process Text. When used,
it provides all privately mapped segments with read and execute permis‐
sion. Process Data. When used, it provides all privately mapped seg‐
ments with read and write permissions.
The selection criteria are constructed by an OR of the attributes bits
and must match exactly. The selection criteria can be used to describe
many abstract memory objects with the address space on which to oper‐
ate.
Operations
This section lists the symbolic names for operations as defined in
<sys/mman.h>: Lock in memory all pages in the range with attributes
defined by the attr parameter. Although a specified page may be locked
multiple times through different mappings, page locks do not nest
within a specified mapping.
A single unlock operation removes multiple lock operations that
occur on a page with the same address in the same process. If a
page is locked in one process, but mapped in another, or visible
through a different mapping in the locking process, the lock
remains in memory until the locking process completes either
implicit or explicit unlock operation.
Removing a locked mapping or deleting a page through file
removal or truncation causes an implicit unlock operation. How‐
ever, if a writable MAP_PRIVATE page in the address range is
changed, the lock is transferred to the private page.
The arg parameter is currently unused; however, it must be spec‐
ified as 0 (zero) for future compatibility. Lock in memory all
pages mapped by the address space with attributes defined by
attr. The arg parameter controls whether the locked pages will
be those mapped by the current address space, those that will be
mapped later, or both. The arg is a bit pattern built from the
following flags: Locks the current mappings, according to the
value of the attr parameter. Locks the future mappings. That
is, all mappings subsequently added to the address space are
locked if sufficient memory is available. The attr parameter is
not used in this operation. Locks future mappings according to
the selection criteria specified in the attr parameter. This
flag only applies to PROT_READ, PROT_WRITE, PROT_EXEC,
PROC_TEXT, and PROC_DATA.
The addr and len parameters currently are not used in this oper‐
ation. However, their values must be specified as NULL and 0
(zero) respectively.
MC_LOCKAS alters the calling process's swap state to permanently
resident when MCL_CURRENT and MCL_FUTURE are specified or when
MCL_CURRENT and MCL_FUTURE_SELECTIVE are specified with attr set
to PROT_READ, PROT_WRITE, and PROT_EXEC. Write all modified
pages with the attributes defined by attr to their backing stor‐
age, and if specified, invalidate the cache copies.
For modified pages mapped shared (MAP_SHARED), the backing stor‐
age is the file to which the page is mapped. For modified pages
mapped private (MAP_PRIVATE), the backing storage is its swap
area.
The arg parameter is a bit pattern built from the following
flags: Performs asynchronous write operations, and returns once
all write operations are scheduled. Performs synchronous write
operations and returns after all write operations are complete.
Invalidates the mappings of cache copies in memory, forcing all
future references of the pages to be obtained from the backing
storage location by the system. Use this operation for applica‐
tions that require a memory object to be in a known state.
Unlocks all pages in the range that have the attributes speci‐
fied by attr.
The arg parameter is unused, but it must specify 0 (zero).
Removes address space memory locks and locks on all pages in the
address space that have the attributes specified by the attr
parameter. Clears all future lock bits, thus preventing future
mapped pages from being locked. In addition, if the process was
permanently resident, makes the process swappable by removing
the permanently resident characteristic.
After fork, the child process does not inherit locks established
with lock operations. The memcntl function fails if memory
locks exceed a system specific limit.
With the exception of MC_SYNC, all operations are restricted to
processes that have superuser effective user ID. The memcntl
function subsumes the operations of plock and mctl.
The parameters, addr, arg, len and mask are unused, but an argu‐
ment of NULL must be specified for addr, with the other fields
specifying 0 (zero).
NOTES
MS_SYNC can only be used on nonprivately mapped files.
RETURN VALUES
On successful completion, the memcntl function returns zero (0). To
indicate error, errno is set and a value of -1 is returned.
ERRORS
One or more of the following may be returned on failure: Indicates that
part or all of the memory specified by the operation could not be
locked by MC_LOCK or MC_LOCKAS, or unlocked when MC_UNLOCK or
MC_UNLOCKAS is specified. Indicates that part or all of the addresses
in the range [addr, addr, + len) are locked, and MC_SYNC was specified
with MC_INVALIDATE or MC_INVALIDATE. Indicates that the addr parameter
does not specify a multiple of the page size as returned by the sysconf
routine. Indicates that MC_LOCKAS or MC_UNLOCKAS was specified and the
addr parameter is not specified as NULL, the len parameter is not spec‐
ified as 0 (zero), or both. Indicates that the arg parameter is
invalid for the operation specified. Indicates that the attr parameter
contains the invalid selection criteria. Indicates that part or all of
the addresses in the range [addr, addr + len) are invalid as the
address space of the process or pages not mapped are specified. Indi‐
cates that there was insufficient system storage available when
MC_LOCK, MC_LOCKAS, MC_UNLOCK, or MC_UNLOCKAS was specified. Indicates
that cmd parameter specified with MC_SYNC is not supported on the
address space specified. Indicates that the effective user ID of the
process is not superuser and one of the following was specified:
MC_LOCK, MC_LOCKAS, MC_UNLOCK, or MC_UNLOCKAS.
SEE ALSO
Functions: mmap(2), mprotect(2), plock(2), msync(2)
Routines: mlock(3), mlockall(3), sysconf(3)memcntl(2)