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

addr: A multiple of page size 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.
len: Must be 0 for the MC_LOCKALL and MC_UNLOCKALL operations.
cmd: The operation to be performed. See the Operations subsection in DESCRIPTION for a list of the symbolic names used for the operations, as they are defined in <sys/mman.h>.
arg: A bit pattern built from the flags used to control the behavior of the operation, where implemented; otherwise, arg must be 0.
attr: The page attributes. If an operation is not to be controlled by these attributes, the attr argument must be 0.
mask: Must be 0. 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 protection, use the following attributes:

PROT_READ: Page is readable. When used, it provides mapped segments with read and execute permission.
PROT_WRITE: Page is writable. When used, it provides mapped segments with read, write and execute permission.
PROT_EXEC: Page is executable. When used, it provides mapped segments with read and execute permission.

Additional criteria include the following:

PROC_TEXT: Process Text. When used, it provides all privately mapped segments with read and execute permission. This criterion is applicable for Itanium(R)-based systems only.
PROC_DATA: 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 attribute 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

The following are the symbolic names for operations as defined in <sys/mman.h>:

MC_LOCK

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

MC_LOCKAS

Lock in memory all pages mapped by the address space with attributes defined by attr. This operation is currently not supported.

MC_SYNC

Write all modified pages with the attributes defined by attr to their backing storage, and if specified, invalidate the cache copies.

For modified pages that are mapped as shared (MAP_SHARED), the backing storage is the file to which the page is mapped. For modified pages that are mapped as private (MAP_PRIVATE), the backing storage is its swap area.

The arg parameter is a bit pattern built from the following flags:

MS_ASYNC

Performs asynchronous write operations and returns once all write operations are scheduled.

MS_SYNC

Performs synchronous write operations and returns after all write operations are complete.

MS_INVALIDATE

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 applications that require a memory object to be in a known state.

MC_UNLOCK

Unlocks all pages in the range that have the attributes specified by attr.

The arg parameter is unused, but it must be 0.

MC_UNLOCKAS

Removes address space memory locks and locks on all pages in the address space that have the attributes specified by the attr parameter. This operation is currently not supported.

Notes

The address range specified by addr must be created by a successful call to mmap(). The page mapping selection attributes SHARED and PRIVATE are currently not supported.

RETURN VALUES

The memcntl function returns

0: Success.
-1: Failure. errno is set to indicate the error.

ERRORS

If memcntl() fails, errno may be set to one of the following values.

EAGAIN: There is not enough lockable memory in the system to satisfy the locking request.
EINVAL: The addr parameter does not specify a multiple of the page size as returned by the sysconf() routine.
EINVAL: The len parameter was specified as zero.
EINVAL: The address range specified by addr and len was not created by a successful call to mmap().
ENOMEM: 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.
ENOSYS: An invalid or unsupported cmd parameter was specified.
EPERM: The effective user ID of the process is not superuser and MC_LOCK or MC_UNLOCK was specified.

AUTHOR

memcntl() was developed by HP.