memcntl(2) memcntl(2)
NAME
memcntl - control memory management
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
int memcntl(caddrt addr, sizet len, int cmd, caddrt arg,
int attr, int mask);
DESCRIPTION
The function memcntl() allows the calling process to apply a variety
of control operations over the address space specified by the mappings
[addr, addr + len).
addr must be a multiple of the pagesize as returned by sysconf(3C).
The scope of the control operations can be further defined with addi-
tional 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:
PROTREAD Page can be read.
PROTWRITE Page can be written.
PROTEXEC 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:
PROCTEXT Process text
PROCDATA Process data
where PROCTEXT specifies all privately mapped segments with read and
execute permission, and PROCDATA specifies all privately mapped seg-
ments 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.
Page 1 Reliant UNIX 5.44 Printed 11/98
memcntl(2) memcntl(2)
The operation to be performed is identified by the argument cmd. The
symbolic names for the operations are defined in the file sys/mman.h
as follows:
MCLOCK Locks in memory all pages in the range with the 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 until the
locking process does either an implicit or an explicit
unlock operation. If a locked mapping is removed, or a
page is deleted through file removal or truncation, an
unlock operation is implicitly performed. If a writable
MAPPRIVATE 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 compati-
bility with potential future enhancements.
MCLOCKAS Locks in memory all pages mapped by the address space with
the attributes attr. At present addr and len are unused,
but must be NULL and 0 respectively, to ensure compatibil-
ity with potential future enhancements. arg is a bit pat-
tern built from the flags:
MCLCURRENT Lock current mappings
MCLFUTURE 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 MCLFUTURE
is specified, then all mappings subsequently added to the
address space will be locked, provided sufficient memory
is available.
MCSYNC Saves all modified pages in the range with attributes
attr. Optionally, invalidates cache copies. The backing
storage for a modified MAPSHARED mapping is the file the
page is mapped to; the backing storage for a modified
MAPPRIVATE mapping is its swap area. arg is a bit pattern
built from the flags used to control the behavior of the
operation:
MSASYNC Perform asynchronous writes
MSSYNC Perform synchronous writes
MSINVALIDATE Invalidate mappings
Page 2 Reliant UNIX 5.44 Printed 11/98
memcntl(2) memcntl(2)
MSASYNC returns immediately once all write operations are
scheduled; with MSSYNC the system call will not return
until all write operations are completed.
MSINVALIDATE 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 loca-
tions. This operation should be used by applications that
require a memory object to be in a known state.
MCUNLOCK Unlocks all pages in the range with attributes attr. At
present arg is unused, but must be 0 to ensure compatibil-
ity with potential future enhancements.
MCUNLOCKAS Removes 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 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(). emcntl() 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 MCSYNC, are restricted to processes with superuser
effective user ID. The memcntl() function subsumes the operations of
plock() and mctl.
Under the following conditions, the function memcntl() fails and sets
errno to:
EAGAIN if some or all of the memory identified by the operation
could not be locked when MCLOCK or MCLOCKAS is speci-
fied.
EBUSY if some or all the addresses in the range [addr, addr +
len) are locked and the option MCSYNC is specified with
MSINVALIDATE.
EINVAL if addr is not a multiple of the page size as returned by
sysconf().
EINVAL if addr and/or len do not have the value 0 when MCLOCKAS
or MCUNLOCKAS is specified.
EINVAL if arg is not valid for the function specified.
EINVAL if invalid selection criteria are specified in attr.
Page 3 Reliant UNIX 5.44 Printed 11/98
memcntl(2) memcntl(2)
ENOMEM if 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 if the process' effective user ID is not superuser and one
of the options MCLOCK, MCLOCKAS, MCUNLOCK or
MCUNLOCKAS was specified.
RESULT
Upon successful completion, the function memcntl() returns a value of
0; otherwise, it returns a value of -1 and sets errno to indicate an
error.
SEE ALSO
mmap(2), mprotect(2), plock(2), mlock(3C), mlockall(3C), msync(3C),
sysconf(3C).
Page 4 Reliant UNIX 5.44 Printed 11/98