 |
Index for
Section 2 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
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
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.
len Must specify 0 (zero) for the MC_LOCKALL and MC_UNLOCKALL commands.
cmd 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>.
arg 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).
attr
Specifies the page attributes. If an operation is not to be controlled
by these attributes, the attr argument must contain the value 0 (zero).
mask
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:
SHARED
Page is mapped shared.
PRIVATE
Page is mapped private.
To specify the selection criteria for page protection, use the following
attributes:
PROT_READ
Page is readable.
PROT_WRITE
Page is writable.
PROT_EXEC
Page is executable.
Additional criteria includes the following:
PROC_TEXT
Process Text. When used, it provides all privately mapped segments
with read and execute permission.
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 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>:
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 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. 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:
MCL_CURRENT
Locks the current mappings, according to the value of the attr
parameter.
MCL_FUTURE
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.
MCL_FUTURE_SELECTIVE
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.
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 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:
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 specify 0 (zero).
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.
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 argument 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:
[EAGAIN]
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.
[EBUSY]
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.
[EINVAL]
Indicates that the addr parameter does not specify a multiple of the
page size as returned by the sysconf routine.
[EINVAL]
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.
[EINVAL]
Indicates that the arg parameter is invalid for the operation
specified.
[EINVAL]
Indicates that the attr parameter contains the invalid selection
criteria.
[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.
[ENOMEM]
Indicates that there was insufficient system storage available when
MC_LOCK, MC_LOCKAS, MC_UNLOCK, or MC_UNLOCKAS was specified.
[ENOSYS]
Indicates that cmd parameter specified with MC_SYNC is not supported on
the address space specified.
[EPERM]
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)
|
Index for
Section 2 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|