mlock()

Lock a range of process address space in physical memory

Synopsis:

#include <sys/mman.h>

int mlock(const void * addr, 
          size_t len);

Arguments:

addr: The starting address for the range of process address space.
len: The amount of the memory to lock, in bytes. There's no limit on the amount of memory that a process may lock, other than the amount of physical memory in the system.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The mlock() function causes the whole pages containing any part of the address space of the process starting at address addr and continuing for len bytes to be memory-resident until unlocked or until the process exits or execs another process image. The addr must be a multiple of PAGESIZE, which depends on the target platform.

Note: In order to lock memory, your process must have the PROCMGR_AID_MEM_LOCK ability enabled. For more information, see procmgr_ability().

Memory-resident is a term used to indicate that the addresses always reside in physical memory. For more information, see “Locking memory” in the Process Manager chapter of the System Architecture guide.

Memory that's mapped from a typed-memory file descriptor is implicitly locked. Shared memory objects that are populated with shm_ctl() are implicitly locked, unless you use the SHMCTL_LAZY flag.

If you use MAP_LAZY, there may not be an immediate effect on the mappings.

Returns:

0: Success.
-1: An error occurred (errno is set).

Errors:

ENOMEM

Some or all of the address range specified by the addr and len arguments doesn't correspond to valid mapped pages in the address space of the process.
Not enough memory was available.
A memory region in the address range specified by addr and len is marked as PROT_NONE, meaning it can't be accessed.

EAGAIN

Some or all of the memory identified by the operation couldn't be locked when the call was made.

EPERM

The calling process doesn't have the required permission; see procmgr_ability().

Classification:

POSIX 1003.1 MLR

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes