mlockall and munlockall Subroutine

Edit online

Purpose

Locks or unlocks the address space of a process.

Library

Standard C Library (libc.a)

Syntax

#include <sys/mman.h>

int mlockall (flags)
int flags;

int munlockall (void);

Description

The mlockall subroutine causes all of the pages mapped by the address space of a process to be memory-resident until unlocked or until the process exits or executes another process image. The flags parameter determines whether the pages to be locked are those currently mapped by the address space of the process, those that are mapped in the future, or both. The flags parameter is constructed from the bitwise-inclusive OR of one or more of the following symbolic constants, defined in the sys/mman.h header file:
MCL_CURRENT
Lock all of the pages currently mapped into the address space of the process.
MCL_FUTURE
Lock all of the pages that become mapped into the address space of the process in the future, when those mappings are established.

When MCL_FUTURE is specified, the future mapping functions might fail if the system is not able to lock this amount of memory because of lack of resources, for example.

The munlockall subroutine unlocks all currently mapped pages of the address space of the process. Any pages that become mapped into the address space of the process after a call to the munlockall subroutine are not locked, unless there is an intervening call to the mlockall subroutine specifying MCL_FUTURE or a subsequent call to the mlockall subroutine specifying MCL_CURRENT. If pages mapped into the address space of the process are also mapped into the address spaces of other processes and are locked by those processes, the locks established by the other processes are unaffected by a call to the munlockall subroutine.

Regarding libraries that are pinned, a distinction has been made internally between a user referencing memory to perform a task related to the application and the system referencing memory on behalf of the application. The former is pinned, and the latter is not. The user-addressable loader data that remains unlocked includes:
  • loader entries
  • user loader entries
  • page-descriptor segment
  • usla heap segment
  • usla text segment
  • all the global segments related to the 64-bit shared library loadlist (shlib heap segment, shlib le segment, shlib text and data heap segments).
This limit affects implementation only, and it does not cause the API to fail.

Upon successful return from a mlockall subroutine that specifies MCL_CURRENT, all currently mapped pages of the process' address space are memory-resident and locked. Upon return from the munlockall subroutine, all currently mapped pages of the process' address space are unlocked with respect to the process' address space.

The calling process must have the root user authority to use this subroutine.

Parameters

Item Description
flags Determines whether the pages to be locked are those currently mapped by the address space of the process, those that are mapped in the future, or both.

Return Values

Upon successful completion, the mlockall subroutine returns 0. Otherwise, no additional memory is locked, and the subroutine returns -1 and sets errno to indicate the error.

Upon successful completion, the munlockall subroutine returns 0. Otherwise, no additional memory is unlocked, and the subroutine returns -1 and sets errno to indicate the error.

Error Codes

The mlockall subroutine fails if:
Item Description
EINVAL The flags parameter is 0, or includes unimplemented flags or the process has already some plocked memory.
ENOMEM Locking all of the pages currently mapped into the address space of the process would exceed the limit on the amount of memory that the process may lock.
EPERM The calling process does not have the appropriate authority to perform the requested operation.

The munlockall subroutine fails if:

Item Description
EINVAL The process has already some plocked memory
EPERM The calling process does not have the appropriate privilege to perform the requested operation