*** UNIX MANUAL PAGE BROWSER ***

memcntl(2) System Calls Manual 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 ); 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 behav- ior 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 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: Page is mapped shared. Page is mapped private. To specify the selection criteria for page protection, use the follow- ing attributes: Page is readable. Page is writable. Page is exe- cutable. Additional criteria includes the following: Process Text. When used, it provides all privately mapped segments with read and execute permis- sion. Process Data. When used, it provides all privately mapped seg- ments 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 oper- ate. 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 de- fined 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 re- mains in memory until the locking process completes either im- plicit or explicit unlock operation. Removing a locked mapping or deleting a page through file re- moval or truncation causes an implicit unlock operation. How- ever, 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 spec- ified 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 ad- dress space are locked if sufficient memory is available. The addr and len are not currently used in this operation. How- ever, their values must be specified as NULL and zero (0) re- spectively. Write all modified pages with the attributes de- fined by attr to their backing storage, and if specified, inval- idate the cache copies. For modified pages mapped shared (MAP_SHARED), the backing stor- age 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 applica- tions that require a memory object to be in a known state. Un- locks all pages in the range that have the attributes specified by attr. The arg parameter is unused, but it must specify zero (0). Re- moves 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 argu- ment 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_UN- LOCKAS 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 spec- ified as zero (0), or both. Indicates that the arg parameter is in- valid 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 ad- dress space of the process or pages not mapped are specified. Indi- cates 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 ad- dress 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. RELATED INFORMATION Functions: mmap(2), mprotect(2), plock(2), msync(2). Routines: mlock(3), mlockall(3), sysconf(3). delim off memcntl(2)