memcntl(2) 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);
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:
Copyright 1994 Novell, Inc. Page 1
memcntl(2) memcntl(2)
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. 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. 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:
Copyright 1994 Novell, Inc. Page 2
memcntl(2) memcntl(2)
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. At present arg is unused, but must be 0
to ensure compatibility with potential future
enhancements.
Copyright 1994 Novell, Inc. Page 3
memcntl(2) memcntl(2)
MC_UNLOCKAS Remove address space memory locks, and locks
on all pages in the address space with
attributes attr. 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.
Copyright 1994 Novell, Inc. Page 4
memcntl(2) memcntl(2)
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.
Copyright 1994 Novell, Inc. Page 5