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
A multiple of page size 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 be
0
for the
MC_LOCKALL
and
MC_UNLOCKALL
operations.
- cmd
The operation to be performed.
See the
Operations
subsection in
DESCRIPTION
for a list of the symbolic names used for the operations,
as they are defined in
<sys/mman.h>.
- arg
A bit pattern built from the flags
used to control the behavior of the operation, where implemented;
otherwise,
arg
must be
0.
- attr
The page attributes.
If an operation is not to be controlled by these attributes, the
attr
argument must be
0.
- mask
Must be
0.
Reserved for future use.
DESCRIPTION
To use this function, compile with the option
-I/usr/include/ep
and link in the libcext library by specifying
-lcext,
for example:
cc -I/usr/include/ep [flag]... cfile[...] -lcext [...]
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 protection,
use the following attributes:
- PROT_READ
Page is readable.
- PROT_WRITE
Page is writable.
- PROT_EXEC
Page is executable.
Additional criteria include the following:
- PROC_TEXT
Process Text.
When used,
it provides all privately mapped segments with read and execute permission.
This criterion is applicable for IPF-based systems only.
- 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 attribute 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
The following are 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
an 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.
This operation is currently not supported.
- 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 that are mapped as shared
(MAP_SHARED),
the backing storage is the file to which the page is mapped.
For modified pages that are mapped as 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 be
0.
- 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.
This operation is currently not supported.
Notes
The address range specified by
addr
must be created by a successful call to
mmap().
The page mapping selection attributes
SHARED
and
PRIVATE
are currently not supported.
RETURN VALUES
The
memcntl
function returns
- 0
Success.
- -1
Failure.
errno
is set to indicate the error.
ERRORS
If
memcntl()
fails,
errno
may be set to one of the following values.
- EAGAIN
There is not enough lockable memory in the system to satisfy
the locking request.
- EINVAL
The
addr
parameter does not specify a multiple of the page size as returned by the
sysconf()
routine.
- EINVAL
The
len
parameter was specified as zero.
- EINVAL
The address range specified by
addr
and
len
was not created by a successful call to
mmap().
- 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.
- ENOSYS
An invalid or unsupported
cmd
parameter was specified.
- EPERM
The effective user ID of the process is not superuser and
MC_LOCK
or
MC_UNLOCK
was specified.
WARNINGS
Users of
memcntl()
should note that the
libcext
library will not be available in future releases of HP-UX.
However this function will be available as part of the C library
libc.
AUTHOR
memcntl()
was developed by HP.