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 success-
     fully and they are guaranteed to stay in RAM until the pages
     are  unlocked 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 applica-
     tions 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  pass-
     words or secret keys as data structures. As a result of pag-
     ing, these secrets could be  transfered  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.

     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.

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  max-
             imum number of allowed locked pages.

     EPERM   The  calling  process  does  not  have   appropriate
             privileges.  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

     munlock(2), mlockall(2), and munlockall(2).