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



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 resi-
       dent in RAM when the mlock system  call  returns  success-
       fully  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 termi-
       nates or starts another program  with  exec.   Child  pro-
       cesses do not inherit page locks across a fork.

       Memory  locking has two main applications: real-time algo-
       rithms and high-security data processing. Real-time appli-
       cations  require  deterministic timing, and, like schedul-
       ing, paging is one major cause of unexpected program  exe-
       cution  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 transfered onto
       a persistent swap store medium, where they might be acces-
       sible  to  the  enemy long after the security software has
       erased the secrets in RAM and terminated.

       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 corre-
              spond 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 priv-
              ileges.  Only  root  processes  are allowed to lock
              pages.

       EINVAL len was not a positive number.

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

SEE ALSO
       mlockall(l),  munlock(k),  munlockall(l), munmap(p), setr-
       limit(t)



Linux 1.3.43                1995-11-26                   MLOCK(K)