memcntl(2)


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 function memcntl 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 notation [start, end) denotes the interval from start to end, including start but excluding end.)

addr 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:


SHARED
Page is mapped shared.

PRIVATE
Page is mapped private.

The following attributes specify page protection selection criteria:


PROT_READ
Page can be read.

PROT_WRITE
Page can be written.

PROT_EXEC
Page can be executed.

The selection criteria are constructed by an OR of the attribute bits and must match exactly.

In addition, the following criteria may be specified:


PROC_TEXT
process text

PROC_DATA
process data

where PROC_TEXT specifies all privately mapped segments with read and execute permission, and PROC_DATA 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. The calling process must have the P_PLOCK privilege.

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

At present arg is unused, but must be 0 to ensure compatibility with potential future enhancements.


MC_LOCKAS
Lock in memory all pages mapped by the address space with attributes attr. The calling process must have the P_PLOCK privilege.

At present addr and len are unused, but must be NULL and 0 respectively, to ensure compatibility with potential future enhancements. arg 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. arg is a bit pattern built from the flags used to control the behavior of the operation:

MS_ASYNC
perform asynchronous writes

MS_SYNC
perform synchronous writes

MS_INVALIDATE
invalidate mappings

MS_ASYNC returns immediately once all write operations are scheduled; with MS_SYNC the system call will not return until all write operations are completed.

MS_INVALIDATE invalidates 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 calling process must have the P_PLOCK privilege. At present arg is unused, but must be 0 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 calling process must have the P_PLOCK privilege. At present addr, len, and arg are unused, but must be NULL, 0 and 0 respectively, to ensure compatibility with potential future enhancements.

The mask argument must be zero; it is reserved for future use.

Locks established with the lock operations are not inherited by a child process after fork. memcntl fails if it attempts to lock more memory than a system-specific limit.

Due to the potential impact on system resources, all operations, with the exception of MC_SYNC, are restricted to processes with appropriate privileges (P_PLOCK).

The memcntl function subsumes the operations of plock and mctl.

Return values

On success, memcntl returns 0. On failure, memcntl returns -1 and sets errno to identify the error.

Errors

In the following conditions, memcntl fails and sets errno to:

EAGAIN
Some or all of the memory identified by the operation could not be locked when MC_LOCK or MC_LOCKAS is specified.

EBUSY
Some or all the addresses in the range [addr, addr + len) are locked and MC_SYNC with MS_INVALIDATE option is specified.

EFAULT
The page to be locked has been aborted (for example, by a file truncate operation), or pages following the end of an object are not allocated.

EINVAL
addr is not a multiple of the page size as returned by sysconf.

EINVAL
addr and/or len do not have the value 0 when MC_LOCKAS or MC_UNLOCKAS is specified.

EINVAL
arg is not valid for the function specified.

EINVAL
Invalid selection criteria are specified in attr.

EIO
An I/O error occurred when attempting to read the page from a device or a network.

ENOMEM
The argument len has a value less than or equal to 0.

ENOMEM
Some or all the addresses in the range [addr, addr + len) are invalid for the address space of the process or pages not mapped are specified.

EPERM
The process does not have appropriate privilege (P_PLOCK) and one of MC_LOCK, MC_LOCKAS, MC_UNLOCK, MC_UNLOCKAS was specified.

References

mlock(3C), mlockall(3C), mmap(2), mprotect(2), msync(3C), plock(2), sysconf(3C)

Notices

Considerations for threads programming

Sibling threads share (by definition) the same address space; modifications to the address space by one can be perceived by the others.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004