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

NAME
       mlockall - disable paging for calling process

SYNOPSIS
       #include <sys/mman.h>

       int mlockall(int flags);

DESCRIPTION
       mlockall  disables  paging  for  all pages mapped into the
       address space of the calling process.  This  includes  the
       pages  of  the  code,  data  and stack segment, as well as
       shared libraries, user space kernel  data,  shared  memory
       and  memory  mapped files. All mapped pages are guaranteed
       to be resident  in  RAM  when  the  mlockall  system  call
       returns  successfully  and  they are guaranteed to stay in
       RAM until the pages  are  unlocked  again  by  munlock  or
       munlockall  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 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.  For  security
       applications,  only  small  parts  of  memory  have  to be
       locked, for which mlock is available.

       The flags parameter can be constructed from the logical OR
       of the following constants:

       MCL_CURRENT Lock all pages which are currently mapped into
                   the address space of the process.

       MCL_FUTURE  Lock all pages which will become  mapped  into
                   the  address  space  of  the  process  in  the
                   future. These could be for instance new  pages
                   required  by  a growing heap and stack as well
                   as new memory mapped files  or  shared  memory
                   regions.

       If  MCL_FUTURE has been specified and the number of locked
       pages exceeds the upper limit  of  allowed  locked  pages,
       then  the  system  call  which caused the new mapping will
       fail with ENOMEM.  If these new pages have been mapped  by
       the  the  growing  stack,  then the kernel will deny stack
       expansion and send a SIGSEGV.

       Real-time processes should  reserve  enough  locked  stack
       pages  before  entering the time-critical section, so that
       no page fault can be caused by function calls. This can be
       achieved  by  calling  a function which has a sufficiently
       large automatic variable and which writes  to  the  memory
       occupied by this large array in order to touch these stack
       pages. This way, enough pages will be mapped for the stack
       and  can  be locked into RAM. The dummy writes ensure that
       not even copy-on-write page faults can occur in the criti-
       cal section.

       Memory  locks  do  not  stack, i.e., pages which have been
       locked several times by calls to mlockall or mlock will be
       unlocked  by a single call to 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  mlockall  and  munlockall  are
       available, _POSIX_MEMLOCK is defined in <unistd.h>.

RETURN VALUE
       On  success,  mlockall  returns  zero.   On  error,  -1 is
       returned, errno is set appropriately.

ERRORS
       ENOMEM 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 Unknown flags were specified.

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

SEE ALSO
       munlockall(2), mlock(2), and munlock(2).

Linux 1.3.43                1995-11-26                          1