Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 ob-
       jects 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; 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 en-
		       sure 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 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  re-
		       turn 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 de-
		       fined 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_AD-
		       VISE  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:

       +-----------------------------+-----------------------------+
       |      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),   at-
       tributes(5), privileges(5)

SunOS 5.10			  1 Feb	2003			    memcntl(2)

NAME | SYNOPSIS | DESCRIPTION | USAGE | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=memcntl&sektion=2&manpath=SunOS+5.10>

home | help