unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

memcntl(2)                       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 identified 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)  accord-
       ing to the bit pattern contained in attr.

       The following attributes specify page mapping selection criteria:

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



       The  PROC_TEXT  attribute  specifies all privately mapped segments 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 <&lt;sys/mman.h>&gt; as fol-
       lows:

       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
                       different  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
                       mapping is removed, or a page is deleted  through  file
                       removal  or  truncation, an unlock operation is implic-
                       itly 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
                       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  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 mod-
                       ified 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  pat-
                       tern  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.


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

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

                       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 addi-
                       tional information on process heap alignment.

                       The attr argument must be 0 for all MC_HAT_ADVISE oper-
                       ations.



       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  operations
       MC_LOCKAS, MC_LOCK, MC_UNLOCKAS, and MC_UNLOCK are restricted to privi-
       leged processes.

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

       MC_HAT_ADVISE  is  intended to improve performance of applications that
       use large amounts of memory on processors that support  multiple  hard-
       ware 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
       performance or available memory.  Using large sizes for one application
       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  function  speci-
                       fied;   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
                       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  process  and
                       MC_LOCK, MC_LOCKAS, MC_UNLOCK, or MC_UNLOCKAS was spec-
                       ified.



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


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE MT-LevelMT-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)



SunOS 5.10                        1 Feb 2003                        memcntl(2)