memcntl(2) DG/UX 5.4R3.00 memcntl(2)
NAME
memcntl - memory management control
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
int memcntl(caddrt addr, sizet len, int cmd, caddrt arg,
int attr, int mask);
where:
addr Starting address of the target region
len Length in bytes of the target region
cmd Operation to perform on the target region
arg Optional command arguments
attr Optional page selection criteria
mask Reserved for future use. Must be 0.
DESCRIPTION
The function memcntl allows the calling process to apply a variety of
control operations over some or all of its address space. For most
of these operations, the affected portion of the address space is
constrained to the address range [addr, addr + len).
The parameter addr must be a page aligned address. Note that the
system page size can be obtained by calling either getpagesize(2) or
sysconf(2) with the SCPAGESIZE parameter; both calls return
identical values.
The len parameter need not be a multiple of the system page size.
However, the implementation of memcntl() internally rounds len up to
the next page size multiple to determine the address range for the
target region. All further references to len refer to this rounded
quantity.
The control operation is specified by cmd. All of the following
values are legal:
MCSYNC Write back any modified pages in the target region to
their backing storage, and optionally purge pages in the
target region from primary memory.
MCLOCK Lock pages of the target region into primary memory.
MCUNLOCK Unlock pages of the target region from primary memory.
MCLOCKAS Lock the caller's entire address space into primary
memory.
Licensed material--property of copyright holder(s) 1
memcntl(2) DG/UX 5.4R3.00 memcntl(2)
MCUNLOCKAS Unlock the caller's entire address space from primary
memory.
The value of the arg parameter may affect the operation specified by
cmd. Such behavior is defined individually for each possible value
of cmd and is described further below. The descriptions of the
remaining parameters apply equally for all legal values of cmd.
The scope of the control operations can be further constrained with
selection criteria regarding the properties of the appropriate
address range. The bit patterns of the attr parameter define these
additional criteria, which include page protections and mapping type.
If the operation is desired for all pages in the target address
range, then the additional selection criteria should be disabled by
setting attr to 0.
If attr is not 0, then the operation will affect only pages whose
page protections and mapping type exactly match those specified by
attr. The mapping type is selected by specifying one of the
following values in attr:
SHARED Select pages mapped shared, e.g., shared memory segments
and file pages mapped using MAPSHARED.
PRIVATE Select pages mapped private, e.g., text, data, and stack
segments.
If attr is not 0, but neither of these values is specified, then only
private pages are selected.
The desired page protection selection criterion is formed by ORing
zero or more of the following protection flags together with the
mapping type selection in attr. Only pages whose page protection
exactly matches the specified combination of protection flags will be
selected.
PROTREAD Page can be read.
PROTWRITE Page can be written.
PROTEXEC Page can be executed.
The following shorthand selection criteria are provided for the
default page protections associated with a program's initial memory
segments. One of these may be ORed with the mapping type instead of
using the individual protection flags.
PROCTEXT Text segment's default page protection.
PROCDATA Data and stack segments' default page protection.
The mask parameter is reserved for future use and must have the value
Licensed material--property of copyright holder(s) 2
memcntl(2) DG/UX 5.4R3.00 memcntl(2)
0.
Each section below describes in detail the specific operations which
may be applied by memcntl() to the process's address space.
MCSYNC
Write to backing storage locations all modified pages in the range
which satisfy the selection criteria given by attr. Optionally,
purge all pages in the range with attributes attr from primary
memory. The backing storage for a modified file page mapped using
MAPSHARED is the file's backing storage. The backing storage for
all other modified pages is within the system's swap areas.
The arg parameter is used to alter the behavior of the operation, and
may include the following flags, ORed together:
MSASYNC Do not wait for writebacks to complete.
MSSYNC Wait for writebacks to complete.
MSINVALIDATE Purge pages from primary memory.
When MSASYNC is specified, the call returns immediately after all
required write operations are scheduled; with MSSYNC the call will
not return until all required write operations have completed. Only
one of these flags should be specified; if neither is specified,
MSSYNC is assumed.
If MSINVALIDATE is specified, then all selected pages which are
memory resident will be purged from primary memory. Subsequent
accesses to those pages will fault and cause the pages to be read in
from backing storage. The operation will fail if any of the selected
pages are locked into primary memory.
The MSINVALIDATE option overrides the standard page replacement
algorithms used by the system; it should be used with caution, as the
system has knowledge of paging demands system-wide, while the
application does not. Application and system performance may suffer
when this option is used.
Note that modified pages whose backing storage is within the swap
areas will not necessarily be written to backing storage unless
MSINVALIDATE is specified. Also, modified pages which are locked
into memory will not necessarily be written to backing storage.
All addresses specified by the interval [addr, addr + len) must be
mapped within the caller's address space. All addresses in the range
which satisfy the optional selection criteria specified by the attr
parameter will be processed.
Note that the system will write modified file pages back to the file
Licensed material--property of copyright holder(s) 3
memcntl(2) DG/UX 5.4R3.00 memcntl(2)
store periodically, so use of MCSYNC for that purpose is rarely
needed unless the application needs to confirm that its modifications
have been written to stable storage. There is a system configuration
variable used to control the maximum age a modified file page can
reach before the system writes it back.
MCLOCK
This operation makes memory resident and locks into primary memory
all pages in the range [addr, addr + len) which satisfy the
additional selection criteria in attr (if any). Locked pages are
forced to stay memory resident, i.e., they cannot be purged from
primary memory.
All addresses specified by the interval [addr, addr + len) must be
mapped within the caller's address space. All addresses in the range
which satisfy the optional selection criteria specified by the attr
parameter will be processed.
The arg parameter is reserved for future use, and must be 0.
A given page may be locked multiple times through one mapping or
multiple mappings (e.g., by multiple processes) of that page.
However, within a given mapping, a single unlock operation on a page
will negate the effect of all previous lock operations on that page.
The specified range should not include any mapped file pages which
lie beyond the end of the file. Calls to mmap(2) may succeed which
map pages beyond the end of the file, but attempts to access or lock
such pages will fail.
Page locks are removed either explicitly, via memcntl(), or
implicitly, when the locked mappings are destroyed, e.g., by
exit(2), exec(2), or munmap(2). Locks established with the lock
operations are not inherited by a child process during fork(2).
Locking a significant fraction of primary memory may negatively
affect system performance. Therefore, the system enforces a
configurable limit on the total number of primary memory pages that
may be locked at any time.
If a page locking operation fails, part of the operation may have
been completed before the failure, possibly locking some pages which
were not locked prior to the call.
MCLOCKAS
This operation makes memory resident and locks into primary memory
all mapped pages in the address space which satisfy the selection
criteria in attr and arg.
The addr and len parameters are unused, and must both be 0. The arg
Licensed material--property of copyright holder(s) 4
memcntl(2) DG/UX 5.4R3.00 memcntl(2)
parameter is used to specify selection criteria, and must contain one
or both of the following flags:
MCLCURRENT Lock all current mappings in the caller's address space
which satisfy the selection criteria in attr (if any).
MCLFUTURE Lock all future mappings in the caller's address space,
regardless of the selection criteria in attr. Future
mappings include future extensions of the data and stack
segments, as well as future mappings established via
mmap(2) and shmat(2). However, future locking is reset
when a process replaces its address space using exec(2).
Once future locking has been established, there is no
way to clear this state for the address space except to
invoke the MCUNLOCKAS operation, which will also unlock
all currently locked pages.
Please refer to above discussion of MCLOCK to understand the
remaining functional details of page locking.
MCUNLOCK
This operation removes page locks on all pages in the range [addr,
addr + len) which satisfy the additional selection criteria in attr
(if any).
The treatment of all other parameters besides cmd is identical to
that of MCLOCK. Please refer to the discussion above of that
operation.
Performing this operation on unlocked pages will not cause an error
to occur. Also, a given page may be locked multiple times through
one mapping or multiple mappings (e.g., by multiple processes) of
that page. However, within a given mapping, a single unlock
operation on a page will negate the effect of all previous lock
operations on that page.
If this operation fails, part of it may have been completed before
the failure, possibly unlocking some pages which were locked prior to
the call.
MCUNLOCKAS
This operation removes page locks on all locked pages in the caller's
address space, and resets the future locking attribute of the address
space.
A given page may be locked multiple times through one mapping or
multiple mappings (e.g., by multiple processes) of that page.
However, within a given mapping, a single unlock operation on a page
will negate the effect of all previous lock operations on that page.
Licensed material--property of copyright holder(s) 5
memcntl(2) DG/UX 5.4R3.00 memcntl(2)
The addr, len, and arg parameters are unused, and must all be 0. If
the parameters are correct, this operation will not fail.
ACCESS CONTROL
Any user process may invoke an MCSYNC operation.
Due to their impact on system resources, all the other operations
require the caller's effective user id to be superuser.
RETURN VALUE
Upon successful completion, memcntl() returns the value 0. Otherwise
it returns -1, and sets errno to indicate an error.
DIAGNOSTICS
Under the following conditions, the memcntl() fails and sets errno
to:
EINVAL if the mask parameter is not 0.
EINVAL if the addr parameter is not a page aligned address.
EINVAL if the attr parameter contains invalid selection
criteria.
EINVAL if MCLOCK, MCUNLOCK, or MCUNLOCKAS is specified and
the arg parameter is not 0.
EINVAL if MCLOCKAS is specified and the arg parameter is 0
or contains flags other than MCLFUTURE or
MCLCURRENT.
EINVAL if MCLOCKAS or MCUNLOCKAS is specified and the addr
parameter is not 0.
EINVAL if MCLOCKAS or MCUNLOCKAS is specified and the len
parameter is not 0.
ENOMEM if MCSYNC, MCLOCK, or MCUNLOCK is specified and the
len parameter is 0.
ENOMEM if MCSYNC, MCLOCK, or MCUNLOCK is specified and
some address in the target region is not mapped in the
caller's address space.
EPERM if MCLOCK, MCLOCKAS, MCUNLOCK, or MCUNLOCKAS is
specified and the calling process's effective user ID
is not superuser.
EAGAIN if MCLOCK or MCLOCKAS is specified and the limit on
primary memory available for locking would be
exceeded.
EBUSY if MCSYNC with the MSINVALIDATE option is specified
and one or more pages in the target region is locked.
Licensed material--property of copyright holder(s) 6
memcntl(2) DG/UX 5.4R3.00 memcntl(2)
EIO if MCSYNC was specified and an I/O error occurred in
writing a page.
EIO if MCLOCK or MCUNLOCK was specified and an I/O error
occurred in reading a non-resident page.
SEE ALSO
brk(2), exec(2), fork(2), getpagesize(2), mmap(2), mprotect(2),
munmap(2), shmat(2), sysconf(2), mlock(3C), mlockall(3C), msync(3C).
NOTES
The DG/UX system's memcntl() implementation does not presently
support locking pages of files which have been mapped with the
MAPSHARED attribute.
The DG/UX system's memcntl() implementation presently forces a
private copy to be made when a privately mapped page (e.g., a text,
data, or stack page) is locked.
Both of these variances from typical System V behavior will be
corrected in an upcoming revision of the DG/UX system.
Licensed material--property of copyright holder(s) 7