Caution: 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.

Description:

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.


Note: 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.


Note: 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
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

See also:

mlockall(), mmap(), munlock()