unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



memcntl(2)							   memcntl(2)



NAME

  memcntl - memory management control

SYNOPSIS

  #include <&lt;sys/types.h>&gt;
  #include <&lt;sys/mman.h>&gt;

  int memcntl(
	  caddr_t addr,
	  size_t len,
	  int cmd,
	  caddr_t arg,
	  int attr,
	  int mask );

PARAMETERS

  addr
      Specifies	a multiple of pagesize as returned by the sysconf routine
      where implemented; otherwise, addr must contain the value	NULL.  Where
      used, control operations can be further defined with the bit pattern
      contained	in attr.

  len Must specify 0 (zero) for	the MC_LOCKALL and MC_UNLOCKALL	commands.

  cmd Specifies	the operation to be performed.	See the	Operations section
      for a list of the	symbolic names used for	the operations as they are
      defined by <&lt;sys/mman.h>&gt;.

  arg Specifies	a bit pattern built from the flags used	to control the
      behavior of the operation	where implemented; otherwise, arg must con-
      tain the value 0 (zero).

  attr
      Specifies	the page attributes.  If an operation is not to	be controlled
      by these attributes, the attr argument must contain the value 0 (zero).

  mask
      Must specify 0 (zero).  Reserved for future use.

DESCRIPTION

  The memcntl function enables the calling process to exercise various con-
  trol operations over the address space which is identified by	the mappings
  set for the address range [addr, addr, + len].







  Selection Criteria


  The scope of the control operations can be further specified with addi-
  tional selection criteria (in	the form of attributes)	according to the bits
  contained in the attr	parameter.

  To specify the selection criteria for	page mapping, use the following
  attributes:

  SHARED
      Page is mapped shared.

  PRIVATE
      Page is mapped private.

  To specify the selection criteria for	page protection, use the following
  attributes:

  PROT_READ
      Page is readable.

  PROT_WRITE
      Page is writable.

  PROT_EXEC
      Page is executable.

  Additional criteria includes the following:

  PROC_TEXT
      Process Text.  When used,	it provides all	privately mapped segments
      with read	and execute permission.

  PROC_DATA
      Process Data.  When used,	it provides all	privately mapped segments
      with read	and write permissions.

  The selection	criteria are constructed by an OR of the attributes bits and
  must match exactly.  The selection criteria can be used to describe many
  abstract memory objects with the address space on which to operate.

  Operations


  This section lists the symbolic names	for operations as defined in
  <&lt;sys/mman.h>&gt;:

  MC_LOCK
      Lock in memory all pages in the range with attributes defined by the
      attr parameter.  Although	a specified page may be	locked multiple	times
      through different	mappings, page locks do	not nest within	a specified
      mapping.

      A	single unlock operation	removes	multiple lock operations that occur
      on a page	with the same address in the same process.  If a page is
      locked in	one process, but mapped	in another, or visible through a dif-
      ferent mapping in	the locking process, the lock remains in memory	until
      the locking process completes either implicit or explicit	unlock opera-
      tion.

      Removing a locked	mapping	or deleting a page through file	removal	or
      truncation causes	an implicit unlock operation.  However,	if a writable
      MAP_PRIVATE page in the address range is changed,	the lock is
      transferred to the private page.

      The arg parameter	is currently unused; however, it must be specified as
      0	(zero) for future compatibility.

  MC_LOCKAS
      Lock in memory all pages mapped by the address space with	attributes
      defined by attr.	The arg	parameter controls whether the locked pages
      will be those mapped by the current address space, those that will be
      mapped later, or both.  The arg is a bit pattern built from the follow-
      ing flags:

      MCL_CURRENT
	  Locks	the current mappings, according	to the value of	the attr
	  parameter.

      MCL_FUTURE
	  Locks	the future mappings.  That is, all mappings subsequently
	  added	to the address space are locked	if sufficient memory is
	  available. The attr parameter	is not used in this operation.

      MCL_FUTURE_SELECTIVE
	  Locks	future mappings	according to the selection criteria specified
	  in the attr parameter. This flag only	applies	to PROT_READ,
	  PROT_WRITE, PROT_EXEC, PROC_TEXT, and	PROC_DATA.

      The addr and len parameters currently are	not used in this operation.
      However, their values must be specified as NULL and 0 (zero) respec-
      tively.

      MC_LOCKAS	alters the calling process's swap state	to permanently
      resident when MCL_CURRENT	and MCL_FUTURE are specified or	when
      MCL_CURRENT and MCL_FUTURE_SELECTIVE are specified with attr set to
      PROT_READ, PROT_WRITE, and PROT_EXEC.

  MC_SYNC
      Write all	modified pages with the	attributes defined by attr to their
      backing storage, and if specified, invalidate the	cache copies.

      For modified pages mapped	shared (MAP_SHARED), the backing storage is
      the file to which	the page is mapped. For	modified pages mapped private
      (MAP_PRIVATE), the backing storage is its	swap area.

      The arg parameter	is a bit pattern built from the	following flags:

      MS_ASYNC
	  Performs asynchronous	write operations, and returns once all write
	  operations are scheduled.

      MS_SYNC
	  Performs synchronous write operations	and returns after all write
	  operations are complete.

      MS_INVALIDATE
	  Invalidates the mappings of cache copies in memory, forcing all
	  future references of the pages to be obtained	from the backing
	  storage location by the system.  Use this operation for applica-
	  tions	that require a memory object to	be in a	known state.

  MC_UNLOCK
      Unlocks all pages	in the range that have the attributes specified	by
      attr.

      The arg parameter	is unused, but it must specify 0 (zero).

  MC_UNLOCKAS
      Removes address space memory locks and locks on all pages	in the
      address space that have the attributes specified by the attr parameter.
      Clears all future	lock bits, thus	preventing future mapped pages from
      being locked. In addition, if the	process	was permanently	resident,
      makes the	process	swappable by removing the permanently resident
      characteristic.

      After fork, the child process does not inherit locks established with
      lock operations.	The memcntl function fails if memory locks exceed a
      system specific limit.

      With the exception of MC_SYNC, all operations are	restricted to
      processes	that have superuser effective user ID.	The memcntl function
      subsumes the operations of plock and mctl.

      The parameters, addr, arg, len and mask are unused, but an argument of
      NULL must	be specified for addr, with the	other fields specifying	0
      (zero).

NOTES

  MS_SYNC can only be used on nonprivately mapped files.

RETURN VALUES

  On successful	completion, the	memcntl	function returns zero (0).  To indi-
  cate error, errno is set and a value of -1 is	returned.

ERRORS

  One or more of the following may be returned on failure:

  [EAGAIN]
      Indicates	that part or all of the	memory specified by the	operation
      could not	be locked by MC_LOCK or	MC_LOCKAS, or unlocked when MC_UNLOCK
      or MC_UNLOCKAS is	specified.

  [EBUSY]
      Indicates	that part or all of the	addresses in the range [addr, addr, +
      len) are locked, and MC_SYNC was specified with MC_INVALIDATE or
      MC_INVALIDATE.

  [EINVAL]
      Indicates	that the addr parameter	does not specify a multiple of the
      page size	as returned by the sysconf routine.

  [EINVAL]
      Indicates	that MC_LOCKAS or MC_UNLOCKAS was specified and	the addr
      parameter	is not specified as NULL, the len parameter is not specified
      as 0 (zero), or both.

  [EINVAL]
      Indicates	that the arg parameter is invalid for the operation speci-
      fied.

  [EINVAL]
      Indicates	that the attr parameter	contains the invalid selection cri-
      teria.

  [ENOMEM]
      Indicates	that part or all of the	addresses in the range [addr, addr +
      len) are invalid as the address space of the process or pages not
      mapped are specified.

  [ENOMEM]
      Indicates	that there was insufficient system storage available when
      MC_LOCK, MC_LOCKAS, MC_UNLOCK, or	MC_UNLOCKAS was	specified.

  [ENOSYS]
      Indicates	that cmd parameter specified with MC_SYNC is not supported on
      the address space	specified.

  [EPERM]
      Indicates	that the effective user	ID of the process is not superuser
      and one of the following was specified: MC_LOCK, MC_LOCKAS, MC_UNLOCK,
      or MC_UNLOCKAS.

SEE ALSO

  Functions:  mmap(2), mprotect(2), plock(2), msync(2)

  Routines:  mlock(3), mlockall(3), sysconf(3)