Standard C Library Functions                            mlock(3C)



NAME
     mlock, munlock - lock or unlock pages in memory

SYNOPSIS
     #include 

     int mlock(caddrt addr, sizet len);


     int munlock(caddrt addr, sizet len);


  Standard conforming
     #include 

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


     int munlock(const void * addr, sizet 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
     MAPRIVATE 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.


     The contents of the locked pages will not be transferred  to
     or  from disk except when explicitly requested by one of the
     locking processes. This guarantee applies only to the mapped



SunOS 5.11          Last change: 10 Apr 2007                    1






Standard C Library Functions                            mlock(3C)



     data,  and  not  to  any  associated  data  structures (file
     descriptors and on-disk metadata, among others).


     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.


     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.

ERORS
     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
               interface.


     EPERM     The  {PRIVPROCLOCKMEMORY}  privilege   is   not
               asserted  in the effective set of the calling pro-
               cess.



     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  or  because  of  a
               limit or resource control on locked memory.




SunOS 5.11          Last change: 10 Apr 2007                    2






Standard C Library Functions                            mlock(3C)



USAGE
     Because of the  impact  on  system  resources,  the  use  of
     mlock()  and  munlock()  is  restricted  to  users  with the
     {PRIVPROCLOCKMEMORY} privilege.

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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     MT-Safe                     
    


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
































SunOS 5.11          Last change: 10 Apr 2007                    3