Content-type: text/html Man page of memcntl

memcntl

Section: System Calls (2)
Index Return to Main Contents
 

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

PARAMETERS

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. Must specify zero (0). 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 <sys/mman.h>. Specifies a bit pattern built from the flags used to control the behavior of the operation where implemented; otherwise, arg must contain the value zero (0). Specifies the page attributes. If an operation is not to be controlled by these attributes, the attr argument must contain the value zero (0). Must specify zero (0). Reserved for future use.
 

DESCRIPTION

The memcntl function enables the calling process to exercise various control 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 additional 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: Page is mapped shared. Page is mapped private.

To specify the selection criteria for page protection, use the following attributes: Page is readable. Page is writable. Page is executable.

Additional criteria includes the following: Process Text. When used, it provides all privately mapped segments with read and execute permission. Process Data. When used, it provides all privately mapped segments with 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 <sys/mman.h>: 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 different mapping in the locking process, the lock remains in memory until the locking process completes either implicit or explicit unlock operation.
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 zero (0) for future compatibility. 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 following flags: Locks the current mappings. Locks the future mappings. That is, all mappings subsequently added to the address space are locked if sufficient memory is available.
The addr and len are not currently used in this operation. However, their values must be specified as NULL and zero (0) respectively. 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: Performs asynchronous write operations, and returns once all write operations are scheduled. Performs synchronous write operations and returns after all write operations are complete. 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 applications that require a memory object to be in a known state. Unlocks all pages in the range that have the attributes specified by attr.
The arg parameter is unused, but it must specify zero (0). Removes address space memory locks and locks on all pages in the address space that have the attributes specified by attr.
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 zero (0).
 

NOTES

MS_SYNC can only be used on nonprivately mapped files.
 

RETURN VALUES

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

ERRORS

One or more of the following may be returned on failure: 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. 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. Indicates that the addr parameter does not specify a multiple of the page size as returned by the sysconf routine. 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 zero (0), or both. Indicates that the arg parameter is invalid for the operation specified. Indicates that the attr parameter contains the invalid selection criteria. 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. Indicates that there was insufficient system storage available when MC_LOCK, MC_LOCKAS, MC_UNLOCK, or MC_UNLOCKAS was specified. Indicates that cmd parameter specified with MC_SYNC is not supported on the address space specified. 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)


 

Index

NAME
SYNOPSIS
PARAMETERS
DESCRIPTION
Selection Criteria
Operations
NOTES
RETURN VALUES
ERRORS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:40:17 GMT, October 02, 2010