mlockall()

Updated: October 26, 2022

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.

Description:

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. The pages that are locked depend on the flags argument.

The exception is any page with a PROT_NONE access setting; mlockall() skips those pages because there is no need to lock a page that can't be accessed.

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.

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

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).

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:

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
Not enough memory was available.
EPERM
The calling process doesn't have the required permission; see procmgr_ability().

Classification:

POSIX 1003.1 ML

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