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

mlockall()

Lock all of a process's address space

Synopsis:

#include <sys/mman.h>

int mlockall(int flags);

Arguments:

flags

Flags that indicate which pages to lock; one or more of the following bits:

MCL_CURRENT: Lock the pages currently mapped into the address space of the process.
MCL_FUTURE: Lock the pages that become mapped into the address space of the process in the future, when the mappings are established.

Library:

libc

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

The mlockall() function causes all of the pages mapped by the address space of a process to be locked and made memory-resident until unlocked or the process exits or executes another process and is determined by the flags argument.

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

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

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.

You have to be a superuser to lock pages. Follow either of the following approaches when attempting to lock pages:

Tightly controlled approach

Lock the pages one by one, by calling mmap() and then mlock().

Global approach

Lock all pages at the same time, by doing one of the following:

Call mlockall(MCL_FUTURE), followed by one or more calls to mmap()
Optionally call mmap(), and then call mlockall(MCL_CURRENT)

Returns:

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

Errors:

EAGAIN: Some or all of the memory identified by the operation couldn't be locked when the call was made.
EINVAL: The flags argument is zero.
ENOMEM: Locking all of the pages currently mapped into the address space of the process would exceed an implementation-defined limit on the amount of memory that the process may lock. lock. This implementation-defined limit is set by RLIMIT_MEMLOCK rlimit.
EPERM: The calling process doesn't have the appropriate privilege to perform the requested operation.

Classification:

POSIX 1003.1 ML

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