memcntl(2) System Calls Manual 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 );
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 pattern 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 additional 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 following 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 per-
mission. Process Data. When used, it provides all privately mapped segments 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 operate.
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. However, 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 specified 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 opera-
tion. 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 operation. 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 storage, and if specified, invalidate the cache copies.
For modified pages mapped shared (MAP_SHARED), the backing storage 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. Invali-
dates 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 applications that require a memory object to be in a known state. Unlocks all pages
in the range that have the attributes specified 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 func-
tion subsumes the operations of plock and mctl.
The parameters, addr, arg, len and mask are unused, but an argument of NULL must be specified for addr, with the other fields speci-
fying 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 specified 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.
Indicates 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)