Standard C Library Functions                            mlock(3C)

NAME
     mlock, munlock - lock or unlock pages in memory

SYNOPSIS
  Default
     #include <sys/mman.h>

     int mlock(caddr_t addr, size_t len);

     int munlock(caddr_t addr, size_t len);

  Standard-conforming
     #include <sys/mman.h>

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

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

DESCRIPTION
     The  mlock() function uses the mappings established for  the
     address  range  [addr,  addr  + len) to identify pages to be
     locked in memory.  If  the  page  identified  by  a  mapping
     changes,   such   as  occurs  when  a  copy  of  a  writable
     MAP_PRIVATE page is made upon the first store, the lock will
     be transferred to the newly copied private page.

     The  munlock()  function  removes  locks  established   with
     mlock().

     A given page may be locked multiple times  by  executing  an
     mlock()  through  different  mappings.  That is, if two dif-
     ferent processes lock the same  page,  then  the  page  will
     remain  locked until both processes remove their locks. How-
     ever, within a given mapping, page locks do not nest -  mul-
     tiple  mlock()  operations  on  the same address in the same
     process will all be removed  with  a  single  munlock().  Of
     course,  a  page locked in one process and mapped in another
     (or visible through a different mapping in the locking  pro-
     cess)  is  still locked in memory.  This fact can be used to
     create applications that do nothing other than  lock  impor-
     tant  data  in  memory,  thereby avoiding page I/O faults on
     references from other processes in the system.

     If the mapping through which an mlock() has  been  performed
     is  removed,  an  munlock() is implicitly performed. An mun-
     lock() is also performed implicitly when a page  is  deleted
     through file removal or truncation.

     Locks established with mlock() are not inherited by a  child
     process after a  fork() and are not nested.

SunOS 5.8           Last change: 29 Dec 1996                    1

Standard C Library Functions                            mlock(3C)

     Attempts to mlock() more memory than a system-specific limit
     will fail.

RETURN VALUES
     Upon successful  completion,  the   mlock()  and   munlock()
     functions  return  0.  Otherwise, no changes are made to any
     locks in the address space of  the  process,  the  functions
     return -1 and set errno to indicate the error.

ERRORS
     The mlock() and  munlock() functions will fail if:

     EINVAL
           The addr argument is not a multiple of the  page  size
           as returned by sysconf(3C).

     ENOMEM
           Addresses in the range [addr, addr + len) are  invalid
           for  the address space of a process, or specify one or
           more pages which are not mapped.

     ENOSYS
           The system does not support this memory locking inter-
           face.

     EPERM The process's effective user ID is not super-user.

     The mlock() function will fail if:

     EAGAIN
           Some or all of the  memory  identified  by  the  range
           [addr,  addr  +  len)  could  not be locked because of
           insufficient system resources.

USAGE
     Because of the  impact  on  system  resources,  the  use  of
     mlock() and munlock() is restricted to the super-user.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO
     fork(2),  memcntl(2),  mmap(2),   plock(3C),   mlockall(3C),
     sysconf(3C), attributes(5), standards(5)

SunOS 5.8           Last change: 29 Dec 1996                    2