75 lines
2.4 KiB
Groff
75 lines
2.4 KiB
Groff
'\"macro stdmacro
|
|
.TH MPIN 2
|
|
.SH NAME
|
|
mpin, munpin \- lock pages in memory
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B "int mpin (void \(**addr, size_t);"
|
|
.PP
|
|
.B "int munpin (void \(**addr, size_t);"
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\f4mpin\fP reads into memory all pages over the range
|
|
(\f2addr, addr + len\fP\^),
|
|
and locks the pages into memory.
|
|
Associated with each locked page is a counter which
|
|
is incremented each time the page is locked.
|
|
The super-user can lock as many pages as it wishes, other users are limited
|
|
to a configurable per process maximum.
|
|
.PP
|
|
\f4munpin\fP decrements the lock counter associated with the pages
|
|
over the range (\f2addr, addr + len\fP\^).
|
|
Pages whose counters are zero are
|
|
available to be swapped out at the system's discretion.
|
|
.PP
|
|
\f4mpin\fP or \f4munpin\fP will fail if one or more of the following are true:
|
|
.TP 15
|
|
.SM
|
|
\%[EINVAL]
|
|
The addresses specified by \f2(addr, addr + len)\fP
|
|
are not mapped into the user's address space.
|
|
.TP 15
|
|
.SM
|
|
\%[EAGAIN]
|
|
There was insufficient lockable memory to lock the entire address range
|
|
\f2(addr, addr + len\fP\^).
|
|
This may occur even though the amount requested was less than the
|
|
system-imposed maximum number of locked pages.
|
|
.TP 15
|
|
.SM
|
|
\%[EBUSY]
|
|
\f4munpin\f1 will fail with this error if the address range specified has
|
|
some active \f4I/O\f1 initiated by some other process belonging to same
|
|
share group.
|
|
.TP 15
|
|
.SM
|
|
\%[ENOMEM]
|
|
The caller was not super-user and the number of pages
|
|
to be locked exceeded the per process
|
|
limit \f2{PLOCK_MAX}\fP [see \f4intro\fP(2)].
|
|
.TP 15
|
|
.SM
|
|
\%[ENOMEM]
|
|
The total number of pages locked by the caller would exceed the
|
|
maximum resident size for the process [see
|
|
.IR setrlimit (2)].
|
|
.TP
|
|
[ENOSPC]
|
|
The address range (\f2addr, addr + len\f1) contains a
|
|
memory-mapped file, and there is insufficient space on the device to
|
|
allocate the entire file.
|
|
.SH SEE ALSO
|
|
intro(2), getrlimit(2), mlock(3C), mlockall(3C), plock(2), ulimit(2).
|
|
.SH "DIAGNOSTICS"
|
|
Upon successful completion, \f4mpin\fP and \f4munpin\fP return 0.
|
|
Otherwise, a value of \-1 is returned and
|
|
.I errno\^
|
|
is set to indicate the error.
|
|
.SH WARNING
|
|
The functions \f4mpin/munpin\fP and \f4mlock/munlock\fP provide similar
|
|
functionality. The major difference between the two sets is that
|
|
\f4mpin/munpin\fP maintains a per page lock counter and \f4mlock/munlock\fP
|
|
does not. Developers should choose the set that best suites their
|
|
application and stick with it, as mixing the interfaces may result in
|
|
unexpected behavior.
|