mlock.2

MLOCK(2)                    Linux Programmer's Manual                   MLOCK(2)



NAME
       mlock - disable paging for some parts of memory

SYNOPSIS
       #include <sys/mman.h>

       int mlock(const void *addr, size_t len);

DESCRIPTION
       mlock disables paging for the memory in the range starting at addr with
       length len bytes. All pages which contain a part of the specified memory
       range are guaranteed be resident in RAM when the mlock system call
       returns successfully and they are guaranteed to stay in RAM until the
       pages are unlocked by munlock or munlockall, until the pages are unmapped
       via munmap, or until the process terminates or starts another program
       with exec.  Child processes do not inherit page locks across a fork.

       Memory locking has two main applications: real-time algorithms and high-
       security data processing. Real-time applications require deterministic
       timing, and, like scheduling, paging is one major cause of unexpected
       program execution delays. Real-time applications will usually also switch
       to a real-time scheduler with sched_setscheduler.  Cryptographic security
       software often handles critical bytes like passwords or secret keys as
       data structures. As a result of paging, these secrets could be
       transferred onto a persistent swap store medium, where they might be
       accessible to the enemy long after the security software has erased the
       secrets in RAM and terminated.  (But be aware that the suspend mode on
       laptops and some desktop computers will save a copy of the system's RAM
       to disk, regardless of memory locks.)

       Memory locks do not stack, i.e., pages which have been locked several
       times by calls to mlock or mlockall will be unlocked by a single call to
       munlock for the corresponding range or by munlockall.  Pages which are
       mapped to several locations or by several processes stay locked into RAM
       as long as they are locked at least at one location or by at least one
       process.

       On POSIX systems on which mlock and munlock are available,
       _POSIX_MEMLOCK_RANGE is defined in <unistd.h> and the value PAGESIZE from
       <limits.h> indicates the number of bytes per page.

NOTES
       With the Linux system call, addr is automatically rounded down to the
       nearest page boundary.  However, POSIX 1003.1-2001 allows an
       implementation to require that addr is page aligned, so portable
       applications should ensure this.

RETURN VALUE
       On success, mlock returns zero.  On error, -1 is returned, errno is set
       appropriately, and no changes are made to any locks in the address space
       of the process.

ERRORS
       ENOMEM Some of the specified address range does not correspond to mapped
              pages in the address space of the process or the process tried to
              exceed the maximum number of allowed locked pages.

       EPERM  The calling process does not have appropriate privileges. Only
              root processes are allowed to lock pages.

       EINVAL (Not on Linux) addr was not a multiple of the page size.

       Linux adds

       EINVAL len was negative.

CONFORMING TO
       POSIX.1b, SVr4.  SVr4 documents an additional EAGAIN error code.

SEE ALSO
       mlockall(2), munlock(2), munlockall(2), munmap(2), setrlimit(2)



Linux 1.3.43                       1995-11-26                           MLOCK(2)