Reformatting page.  Please Wait... done


System Calls                                           MEMCNTL(2)


NAME
     memcntl - memory management control

SYNOPSIS
     #include <sys/types.h>
     #include <sys/mman.h>

     int memcntl(caddr_t addr, size_t len, int cmd, caddr_t arg,
          int attr, int mask);


DESCRIPTION
     The memcntl() function allows the calling process to apply a
     variety of control operations over the address space identi-
     fied by the  mappings  established  for  the  address  range
     [addr, addr + len).


     The addr argument must be a  multiple  of  the  pagesize  as
     returned by sysconf(3C). The scope of the control operations
     can be further defined with  additional  selection  criteria
     (in  the  form  of  attributes) according to the bit pattern
     contained in attr.


     The following attributes specify page mapping selection cri-
     teria:

     SHARED
                Page is mapped shared.


     PRIVATE
                Page is mapped private.


     The following attributes specify page  protection  selection
     criteria.  The  selection criteria are constructed by a bit-
     wise OR operation on  the  attribute  bits  and  must  match
     exactly.

     PROT_READ
                   Page can be read.


     PROT_WRITE
                   Page can be written.


     PROT_EXEC
                   Page can be executed.


Illumos             Last change: Apr 10, 2007                   1


System Calls                                           MEMCNTL(2)


     The following criteria may also be specified:

     PROC_TEXT
                  Process text.


     PROC_DATA
                  Process data.


     The PROC_TEXT attribute specifies all privately mapped  seg-
     ments  with  read  and execute permission, and the PROC_DATA
     attribute specifies all privately mapped segments with write
     permission.


     Selection criteria can be used to describe various  abstract
     memory objects within the address space on which to operate.
     If an operation shall not be constrained  by  the  selection
     criteria, attr must have the value 0.


     The operation to be performed is identified by the  argument
     cmd.  The  symbolic  names for the operations are defined in
     <sys/mman.h> as follows:

     MC_LOCK

         Lock in memory all pages in the  range  with  attributes
         attr.  A given page may be locked multiple times through
         different mappings; however,  within  a  given  mapping,
         page  locks do not nest. Multiple lock operations on the
         same address in the same process  will  all  be  removed
         with  a  single  unlock operation.  A page locked in one
         process and mapped in another (or visible through a dif-
         ferent  mapping  in  the  locking  process) is locked in
         memory as long as the locking process  does  neither  an
         implicit nor explicit unlock operation. If a locked map-
         ping is removed, or a page is deleted through file remo-
         val  or  truncation,  an  unlock operation is implicitly
         performed. If a writable MAP_PRIVATE page in the address
         range  is  changed,  the lock will be transferred to the
         private page.

         The arg argument is not used, but must be  0  to  ensure
         compatibility with potential future enhancements.


     MC_LOCKAS

         Lock in memory all pages mapped  by  the  address  space


Illumos             Last change: Apr 10, 2007                   2


System Calls                                           MEMCNTL(2)


         with attributes attr. The addr and len arguments are not
         used, but must be NULL and  0  respectively,  to  ensure
         compatibility  with  potential future enhancements.  The
         arg argument is a bit pattern built from the flags:

         MCL_CURRENT
                        Lock current mappings.


         MCL_FUTURE
                        Lock future mappings.

         The value of arg determines  whether  the  pages  to  be
         locked  are those currently mapped by the address space,
         those that will be mapped in the  future,  or  both.  If
         MCL_FUTURE  is specified, then all mappings subsequently
         added to the address space will be locked, provided suf-
         ficient memory is available.


     MC_SYNC

         Write to their backing storage  locations  all  modified
         pages  in  the  range  with attributes attr. Optionally,
         invalidate cache copies. The backing storage for a modi-
         fied  MAP_SHARED  mapping is the file the page is mapped
         to; the backing storage for a modified MAP_PRIVATE  map-
         ping is its swap area. The arg argument is a bit pattern
         built from the flags used to control the behavior of the
         operation:

         MS_ASYNC
                          Perform asynchronous writes.


         MS_SYNC
                          Perform synchronous writes.


         MS_INVALIDATE
                          Invalidate mappings.

         MS_ASYNC Return immediately once  all  write  operations
         are scheduled; with MS_SYNC the function will not return
         until all write operations are completed.

         MS_INVALIDATE Invalidate all cached copies  of  data  in
         memory,  so that further references to the pages will be
         obtained by the system from their backing storage  loca-
         tions.  This  operation  should  be used by applications
         that require a memory object to be in a known state.


Illumos             Last change: Apr 10, 2007                   3


System Calls                                           MEMCNTL(2)


     MC_UNLOCK

         Unlock all pages in the range with attributes attr.  The
         arg argument is not used, but must be 0 to ensure compa-
         tibility with potential future enhancements.


     MC_UNLOCKAS

         Remove address space memory locks and locks on all pages
         in  the  address  space  with attributes attr. The addr,
         len, and arg arguments are not used, but must be NULL, 0
         and 0, respectively, to ensure compatibility with poten-
         tial future enhancements.


     MC_HAT_ADVISE

         Advise system how a region of user-mapped memory will be
         accessed.  The  arg argument is interpreted as a "struct
         memcntl_mha *". The following members are defined  in  a
         struct memcntl_mha:

           uint_t mha_cmd;
           uint_t mha_flags;
           size_t mha_pagesize;

         The accepted values for mha_cmd are:

           MHA_MAPSIZE_VA
           MHA_MAPSIZE_STACK
           MHA_MAPSIZE_BSSBRK

         The mha_flags member is reserved for future use and must
         always  be  set  to 0. The mha_pagesize member must be a
         valid size as obtained from getpagesizes(3C) or the con-
         stant value 0 to allow the system to choose an appropri-
         ate hardware address translation mapping size.

         MHA_MAPSIZE_VA  sets  the  preferred  hardware   address
         translation  mapping  size  of the region of memory from
         addr to addr + len. Both addr and len must be aligned to
         an  mha_pagesize  boundary.  The  entire virtual address
         region from addr to addr + len must not have any  holes.
         Permissions  within each mha_pagesize-aligned portion of
         the region must be consistent.  When  a  size  of  0  is
         specified,  the system selects an appropriate size based
         on the size and alignment of the memory region, type  of
         processor, and other considerations.

         MHA_MAPSIZE_STACK sets the  preferred  hardware  address
         translation  mapping  size  of  the  process main thread


Illumos             Last change: Apr 10, 2007                   4


System Calls                                           MEMCNTL(2)


         stack segment. The addr and len arguments must  be  NULL
         and 0, respectively.

         MHA_MAPSIZE_BSSBRK sets the preferred  hardware  address
         translation  mapping  size of the process heap. The addr
         and len arguments must be NULL and 0, respectively.  See
         the  NOTES section of the ppgsz(1) manual page for addi-
         tional information on process heap alignment.

         The attr argument must be 0 for all MC_HAT_ADVISE opera-
         tions.


     The mask argument must be 0; it is reserved for future use.


     Locks established with the lock operations are not inherited
     by  a  child  process  after fork(2). The memcntl() function
     fails if it attempts to lock  more  memory  than  a  system-
     specific limit.


     Due to the potential impact on system resources, the  opera-
     tions  MC_LOCKAS,  MC_LOCK,  MC_UNLOCKAS,  and MC_UNLOCK are
     restricted to privileged processes.

USAGE
     The memcntl() function subsumes the operations of  plock(3C)
     and mctl(3UCB).


     MC_HAT_ADVISE is intended to improve performance of applica-
     tions  that  use  large amounts of memory on processors that
     support multiple hardware address translation mapping sizes;
     however,  it  should  be  used with care. Not all processors
     support all sizes with equal efficiency. Use of larger sizes
     may  also introduce extra overhead that could reduce perfor-
     mance or available memory.  Using large sizes for one appli-
     cation may reduce available resources for other applications
     and result in slower system wide performance.

RETURN VALUES
     Upon successful completion, memcntl() returns 0;  otherwise,
     it returns -1 and sets errno to indicate an error.

ERRORS
     The memcntl() function will fail if:

     EAGAIN
               When the selection criteria match, some or all  of
               the  memory  identified by the operation could not


Illumos             Last change: Apr 10, 2007                   5


System Calls                                           MEMCNTL(2)


               be locked when MC_LOCK or MC_LOCKAS was specified,
               some  or  all mappings in the address range [addr,
               addr + len) are locked for I/O when  MC_HAT_ADVISE
               was  specified,  or  the  system  has insufficient
               resources when MC_HAT_ADVISE was specified.

               The cmd is MC_LOCK or MC_LOCKAS  and  locking  the
               memory identified by this operation would exceed a
               limit or resource control on locked memory.


     EBUSY
               When the selection criteria match, some or all  of
               the  addresses in the range [addr, addr + len) are
               locked and MC_SYNC with the  MS_INVALIDATE  option
               was specified.


     EINVAL
               The addr argument specifies invalid selection cri-
               teria  or  is  not  a multiple of the page size as
               returned by   sysconf(3C);  the  addr  and/or  len
               argument  does not have the value 0 when MC_LOCKAS
               or MC_UNLOCKAS is specified; the arg  argument  is
               not valid for the function specified; mha_pagesize
               or mha_cmd is invalid; or MC_HAT_ADVISE is  speci-
               fied  and  not  all  pages in the specified region
               have the same access permissions within the  given
               size boundaries.


     ENOMEM
               When the selection criteria match, some or all  of
               the  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.


     EPERM
               The  {PRIV_PROC_LOCK_MEMORY}  privilege   is   not
               asserted  in the effective set of the calling pro-
               cess  and  MC_LOCK,   MC_LOCKAS,   MC_UNLOCK,   or
               MC_UNLOCKAS was specified.


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


Illumos             Last change: Apr 10, 2007                   6


System Calls                                           MEMCNTL(2)


     __________________________________
    | ATTRIBUTE TYPE|  ATTRIBUTE VALUE|
    |_______________|_________________|
    | MT-Level      |  MT-Safe        |
    |_______________|_________________|


SEE ALSO
     ppgsz(1)fork(2)mmap(2),  mprotect(2),  getpagesizes(3C),
     mctl(3UCB),  mlock(3C),  mlockall(3C)msync(3C)plock(3C),
     sysconf(3C)attributes(5)privileges(5)


Illumos             Last change: Apr 10, 2007                   7