unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.9)
Page:
Section:
Apropos / Subsearch:
optional field



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.

     The following criteria may also be specified:

     PROC_TEXT
           Process text.

     PROC_DATA
           Process data.



SunOS 5.9           Last change: 11 Dec 2001                    1






System Calls                                           memcntl(2)



     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 opera-
           tions 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  visi-
           ble  through  a  different mapping in the locking pro-
           cess) is locked in memory as long as the locking  pro-
           cess  does  neither  an  implicit  nor explicit unlock
           operation. If a locked mapping is removed, or  a  page
           is  deleted  through  file  removal  or truncation, an
           unlock operation is implicitly performed. If  a  writ-
           able 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
           with  attributes  attr. The addr and len arguments are
           not used, but must be  NULL  and  0  respectively,  to
           ensure  compatibility  with  potential future enhance-
           ments.  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



SunOS 5.9           Last change: 11 Dec 2001                    2






System Calls                                           memcntl(2)



           both.  If  MCL_FUTURE  is specified, then all mappings
           subsequently  added  to  the  address  space  will  be
           locked, provided sufficient 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
           modified  MAP_SHARED  mapping  is the file the page is
           mapped  to;  the  backing  storage  for   a   modified
           MAP_PRIVATE mapping 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
           locations.  This  operation should be used by applica-
           tions that require a memory object to be  in  a  known
           state.

     MC_UNLOCK
           Unlock all pages in the range  with  attributes  attr.
           The  arg argument is not used, but must be 0 to ensure
           compatibility 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 potential 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:



SunOS 5.9           Last change: 11 Dec 2001                    3






System Calls                                           memcntl(2)



           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  constant value 0 to allow the system to choose an
           appropriate 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 con-
           siderations.

           MHA_MAPSIZE_STACK sets the preferred hardware  address
           translation  mapping  size  of the process main thread
           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
           additional information on process heap alignment.

           The attr argument must  be  0  for  all  MC_HAT_ADVISE
           operations.

     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.





SunOS 5.9           Last change: 11 Dec 2001                    4






System Calls                                           memcntl(2)



     Due to the potential impact on system resources, all  opera-
     tions  except  MC_SYNC  are  restricted  to  processes  with
     superuser effective user ID.

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

     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  speci-
           fied.

     EINVAL
           The addr argument specifies invalid selection criteria
           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 func-
           tion specified; mha_pagesize or mha_cmd is invalid; or
           MC_HAT_ADVISE is specified 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



SunOS 5.9           Last change: 11 Dec 2001                    5






System Calls                                           memcntl(2)



           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 process's effective user ID is not  superuser  and
           MC_LOCK,  MC_LOCKAS,  MC_UNLOCK,  or  MC_UNLOCKAS  was
           specified.

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

     ____________________________________________________________
    |       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)
































SunOS 5.9           Last change: 11 Dec 2001                    6