This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

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: Length of the memory buffer in bytes.

Library:

libc

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

The mlock() function locks a range of process address space starting at address addr and continuing for length len. The addr must be a multiple of PAGESIZE, which depends on the target platform.

The full POSIX implementation for this function was added in the QNX Neutrino Core OS 6.3.2.

The successful call to mlock() function ensures memory-resident pages.

The calling process needs superuser capabilities to call the mlock() function.

You always map the memory (using mmap()) region in three locking states:

State	Result of memory mapping
Unlocked	May be paged in/out
Locked	May not be paged in/out. May still fault on access/reference to maintain usage/modification stats
Superlocked	Happens when I/O privileges are granted to a thread. No faulting allowed at all and covers the whole address space

For MAP_LAZY mappings, memory is not allocated/mapped until the memory is first referenced for any of the above types. Once it's been referenced, it obeys the above rules -- it's a programmer error to touch a MAP_LAZY area in a critical region (interrupts disabled or an ISR) that hasn't already been referenced.

The default locking state of memory is determined by the -m[~]l and -m[~]L options of the procnto manager.

Memory-resident is a term used to indicate that the addresses always reside in physical memory.

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.
Locking the pages mapped by the specified range would exceed an implementation-defined limit on the amount of memory that the process may lock. This implementation-defined limit is set by RLIMIT_MEMLOCK rlimit.

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 superuser capabilities.

Classification:

POSIX 1003.1 MLR

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