memcntl man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

MEMCNTL(2)							    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 <sys/mman.h>  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;  how‐
	   ever, 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  map‐
	   ping	 in  the  locking  process) is locked in memory as long as the
	   locking process does neither an implicit nor explicit unlock opera‐
	   tion.  If a locked mapping is removed, or a page is deleted through
	   file removal or truncation, an unlock operation is implicitly  per‐
	   formed.  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 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 modified MAP_SHARED mapping is the file
	   the page is mapped to; the backing storage for a modified  MAP_PRI‐
	   VATE	 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	sched‐
	   uled;  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  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	 argu‐
	   ment is not used, but must be 0 to ensure compatibility with poten‐
	   tial 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 argu‐
	   ments 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 map‐
	   ping	 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 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.

		 The cmd is MC_LOCK or MC_LOCKAS and locking the memory	 iden‐
		 tified	 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 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 specified.

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),    mlockall(3C),    msync(3C),    plock(3C),	  sysconf(3C),
       attributes(5), privileges(5)

				 Apr 10, 2007			    MEMCNTL(2)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net