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
       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; 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:

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

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