MLOCK(3C) Standard C Library Functions MLOCK(3C)
NAME
mlock,
munlock - lock or unlock pages in memory
SYNOPSIS
#include <sys/mman.h> int mlock(
const void *addr,
size_t len);
int munlock(
const void *addr,
size_t len);
DESCRIPTION
The
mlock() function uses the mappings established for the address range
[
addr,
addr +
len) to identify pages to be locked in memory. If the page
identified by a mapping changes, such as occurs when a copy of a writable
MAP_PRIVATE page is made upon the first store, the lock will be transferred
to the newly copied private page.
The
munlock() function removes locks established with
mlock().
A given page may be locked multiple times by executing an
mlock() through
different mappings. That is, if two different processes lock the same
page, then the page will remain locked until both processes remove their
locks. However, within a given mapping, page locks do not nest -- multiple
mlock() operations on the same address in the same process will all be
removed with a single
munlock(). Of course, a page locked in one process
and mapped in another (or visible through a different mapping in the
locking process) is still locked in memory. This fact can be used to
create applications that do nothing other than lock important data in
memory, thereby avoiding page I/O faults on references from other processes
in the system.
The contents of the locked pages will not be transferred to or from disk
except when explicitly requested by one of the locking processes. This
guarantee applies only to the mapped data, and not to any associated data
structures (file descriptors and on-disk metadata, among others).
If the mapping through which an
mlock() has been performed is removed, an
munlock() is implicitly performed. An
munlock() is also performed
implicitly when a page is deleted through file removal or truncation.
Locks established with
mlock() are not inherited by a child process after a
fork(2) and are not nested.
Attempts to
mlock() more memory than a system-specific limit will fail.
RETURN VALUES
Upon successful completion, the
mlock() and
munlock() functions return
0.
Otherwise, no changes are made to any locks in the address space of the
process, the functions return
-1 and set
errno to indicate the error.
ERRORS
The
mlock() and
munlock() functions will fail if:
EINVAL The
addr argument is not a multiple of the page size as
returned by
sysconf(3C).
ENOMEM Addresses in the range [
addr,
addr +
len) are invalid
for the address space of a process, or specify one or
more pages which are not mapped.
ENOSYS The system does not support this memory locking
interface.
EPERM The {PRIV_PROC_LOCK_MEMORY} privilege is not asserted in
the effective set of the calling process.
The
mlock() function will fail if:
EAGAIN Some or all of the memory identified by the range [
addr,
addr +
len) could not be locked because of insufficient
system resources or because of a limit or resource
control on locked memory.
USAGE
Because of the impact on system resources, the use of
mlock() and
munlock()
is restricted to users with the {PRIV_PROC_LOCK_MEMORY} privilege.
INTERFACE STABILITY
CommittedMT-LEVEL MT-SafeSEE ALSO
fork(2),
memcntl(2),
mmap(2),
mlockall(3C),
plock(3C),
sysconf(3C),
attributes(7),
standards(7)illumos March 13, 2022 illumos