Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for memcntl (opensolaris section 2)

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) according 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 crite-
       ria 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 per-
       mission, 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  selec-
       tion 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 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 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 with attributes  attr.	The  addr
	   and len arguments are not used, but must be NULL and 0 respectively, to ensure compat-
	   ibility 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 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 modi-
	   fied 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 refer-
	   ences 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 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:

	     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 appropriate hardware address transla-
	   tion 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 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.

       Due  to	the  potential	impact	on  system  resources, the operations 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 applications 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 per-
       formance 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.

		 The cmd is MC_LOCK or MC_LOCKAS and locking the memory identified by this opera-
		 tion 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 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 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	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 speci-
		 fied.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

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

SunOS 5.11				   10 Apr 2007				       memcntl(2)


All times are GMT -4. The time now is 10:52 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password