'\"!  tbl | mmdoc
'\"macro stdmacro
.if n .pH g2.memcntl @(#)memcntl	40.12 of 11/30/89
.\" Copyright 1989 AT&T
'\" ident	"@(#)svid_rt:rt_os/memcntl	1.13"
.nr X
.if \nX=0 .ds x} memcntl 2 "" "\&"
.if \nX=1 .ds x} memcntl 2 ""
.if \nX=2 .ds x} memcntl 2 "" "\&"
.if \nX=3 .ds x} memcntl "" "" "\&"
.TH \*(x}
.SH NAME
\f4memcntl\fP \- memory management control
.SH SYNOPSIS
.nf
.na
.ft 4
#include <sys/types.h>
#include <sys/mman.h>
.ft 1
.HP
\f4int memcntl(caddr_t addr, size_t len, int cmd, caddr_t arg,
     int attr, int mask);\fP
.fi
.ad
.SH DESCRIPTION
The function \f4memcntl\f1
allows the calling process to apply a variety of control operations
over the address space identified by the mappings established for the
address range [\f2addr\f1, \f2addr\f1 + \f2len\f1). 
.P
\f2addr\f1 must be a multiple of the pagesize
as returned by \f4sysconf\f1(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 \f2attr\f1.
.P
The following attributes specify page mapping selection criteria:
.P
.RS
.TS
lw(.85i) l.
\f4SHARED\f1	Page is mapped shared.
\f4PRIVATE\f1	Page is mapped private.
.TE
.RE
.P
The following attributes specify page protection selection criteria:
.P
.RS
.TS
lw(.85i) l.
\f4PROT_READ\f1	Page can be read.
\f4PROT_WRITE\f1	Page can be written.
\f4PROT_EXEC\f1	Page can be executed.
.TE
.RE
.P
The selection criteria are constructed by an OR
of the attribute bits and must match exactly.
.P
In addition, the following criteria may be specified:
.P
.RS
.TS
lw(.85i) l.
\f4PROC_TEXT\f1	process text
\f4PROC_DATA\f1	process data
.TE
.RE
where \f4PROC_TEXT\f1 specifies all privately mapped segments
with read and execute permission, and \f4PROC_DATA\f1
specifies all privately mapped segments with write permission.
.P
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,
\f2attr\f1 must have the value \f40\fP.
.P
The operation to be performed is identified by the argument \f2cmd\f1.
The symbolic names for the operations are defined in 
\f4<sys/mman.h>\f1 as follows:
.TP 1.0i
\f4MC_LOCK\f1
Lock in memory all pages in the range with attributes \f2attr\f1.
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 removal or truncation,
an unlock operation is implicitly performed.
If a writable \f4MAP_PRIVATE\f1 page in the address range is changed,
the lock will be transferred to the private page.
.IP
At present \f2arg\f1 is unused, but must be \f40\fP
to ensure compatibility with potential future enhancements.
.TP 1.0i
\f4MC_LOCKAS\f1
Lock in memory all pages mapped by the address space with attributes \f2attr\f1.
At present \f2addr\f1 and \f2len\f1 are unused, but 
must be \f4NULL\f1 and \f40\fP respectively,
to ensure compatibility with potential future enhancements.
\f2arg\f1 is a bit pattern built from the flags:
.TS
l lw(1i) l.
	\f4MCL_CURRENT\f1	Lock current mappings
	\f4MCL_FUTURE\f1	Lock future mappings
.TE
.IP
The value of \f2arg\f1
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 \f4MCL_FUTURE\f1 is specified,
then all mappings subsequently added to the address
space will be locked,
provided sufficient memory is available.
.TP 1.0i
\f4MC_SYNC\f1
Write to their backing storage locations
all modified pages in the range with attributes \f2attr\f1.
Optionally, invalidate cache copies.
The backing storage for a modified \f4MAP_SHARED\fP mapping is the file
the page is mapped to;
the backing storage for a modified \f4MAP_PRIVATE\fP mapping is its swap area.
\f2arg\f1
is a bit pattern built from the flags used to control the behavior of the 
operation:
.TS
l lw(1i) l.
	\f4MS_ASYNC\f1	perform asynchronous writes
	\f4MS_SYNC\f1	perform synchronous writes
	\f4MS_INVALIDATE\f1	invalidate mappings
.TE
.IP
\f4MS_ASYNC\f1 returns immediately once all write operations are scheduled;
with \f4MS_SYNC\f1 
the system call will not return until all write operations are completed.
.IP
\f4MS_INVALIDATE\f1 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.
.TP 1.0i
\f4MC_UNLOCK\f1
Unlock all pages in the range with attributes \f2attr\f1.
At present \f2arg\f1 is unused, but must be \f40\fP
to ensure compatibility with potential future enhancements.
.TP 1.0i
\f4MC_UNLOCKAS\f1
Remove address space memory locks,
and locks on all pages in the address space with attributes \f2attr\f1.
At present \f2addr\f1, \f2len\f1, and \f2arg\f1 are unused, 
but must be \f4NULL\f1, \f40\fP and \f40\fP respectively,
to ensure compatibility with potential future enhancements.
.P
The
.I mask
argument must be zero; it is reserved for future use.
.P
Locks established with the lock operations are not inherited by a
child process after \f4fork\f1.
\f4memcntl\fP fails if it attempts to lock more memory than a system-specific limit.
.P
Due to the potential impact on system resources,
all operations, with the exception of \f4MC_SYNC\f1,
are restricted to processes with superuser effective user
.SM ID .
The \f4memcntl\f1
function subsumes the operations of \f4plock\f1 and \f4mctl\fP.
.SH RETURN VALUE
Upon successful completion, the function \f4memcntl\f1 returns a 
value of \f40\f1; otherwise, it returns a value of \f4\-1\f1 and 
sets \f4errno\f1 to indicate an error.
.SH ERRORS
Under the following conditions,
the function \f4memcntl\f1 fails and sets \f4errno\f1 to:
.TP 12
\f4EAGAIN\f1
if some or all of the memory identified by the operation could not be
locked when \f4MC_LOCK\f1 or \f4MC_LOCKAS\f1 is specified.
.TP 12
\f4EBUSY\f1
if some or all the addresses in the range [\f2addr, addr + len\fP) are
locked and \f4MC_SYNC\fP with \f4MS_INVALIDATE\fP option is specified.
.TP 12
\f4EINVAL\f1
if \f2addr\f1 is not a multiple of the page size as returned by 
\f4\%sysconf\f1.
.TP 12
\f4EINVAL\f1
if \f2addr\f1 and/or \f2len\f1
do not have the value \f40\fP when \f4MC_LOCKAS\f1 or \f4MC_UNLOCKAS\f1 is specified.
.TP 12
\f4EINVAL\f1
if \f2arg\f1 is not valid for the function specified.
.TP 12
\f4EINVAL\f1
if invalid selection criteria are specified in \f2attr\f1.
.TP 12
\f4ENOMEM\f1
if some or all the addresses in the range [\f2addr\f1, \f2addr\f1 + \f2len\f1) are invalid 
for the address space of the process or pages not mapped are specified.
.TP 12
\f4EPERM\f1
if the process's effective user
.SM ID
is not superuser and one of
\f4MC_LOCK\f1,
\f4MC_LOCKAS\f1,
\f4MC_UNLOCK\f1,
\f4MC_UNLOCKAS\f1
was specified.
.SH "SEE ALSO"
.na
\f4mmap\fP(2),
\f4mprotect\fP(2), 
\f4plock\fP(2),
\f4sysconf\fP(2),
\f4mlock\fP(3C),
\f4mlockall\fP(3C),
\f4msync\fP(3C). 
.ad
