memcntl()

SYNOPSIS

#include <sys/mman.h>


int memcntl(void *addr, size_t len, int cmd,
			void *arg, int attr, int mask)

DESCRIPTION

The memcntl(2) call controls and manages a mapped address space in the range [addr addr + len]. The attr argument selects the pages to be affected; it contains a bit pattern of page attributes which are ORed together.

The cmd argument specifies the actual operation. The arg argument may modify the actual command, and is usually a bit pattern ORed together. The file <sys/mman.h> defines these operations:

MC_LOCK

Lock the pages in the range that have the specified attributes. Although different mappings may cause the same page to be locked more than once, the locks do not nest within a particular mapping. One unlock operation undoes all the locks held on a page by a process, but locks held by aanother process are held in memory until the locking process has released the lock. (If a locked page is removed or deleted, that implicitly unlocks it.)

The value of arg must be 0.

MC_LOCKAS

Lock the pages in the address space that have the specified attributes. In this case, the arg value controls whether the locked pages are mapped in the current address space or ones that will be mapped later, or both.

The addr value must be NULL and the len value must be 0.

Values that can be ORed into arg are:

MCL_CURRENT

Lock the current mappings

MCL_FUTURE

Lock all mappings added to the address space, so long as there is sufficient memory

MC_SYNC

Write the pages specified by attr to storage. If a page has been modified and mapped shared with MAP_SHARED, it's written back to the file. If the page has been modified and is mapped private, it's written back to its swap space. if MS_INVALIDATE is specified, it will invalidate the cache copy in memory. The arg can be one of:

MS_ASYNC

Write asynchronously, and return once writes are scheduled.

MS_SYNC

Write synchronously, and return after writes are completed.

MS_INVALIDATE

Mark cached copy as invalid. All future references will be made to the storage copy; this is useful for applications that need to deal with a memory object in a known state.

This operation can only be used on publicly (that is, non-privately) mapped files.

MC_UNLOCK

Unlock all of the pages in the range that have the specified attributes. The value of arg must be 0.

MC_UNLOCKAS

Unlock any locks on the address space (MC_LOCKAS) and remove locks on all pages in the address space that have the specified attributes.

RETURN VALUES

The memcntl(2) utility exits with status 0 for success, and >0 if an error occurred.

ERRORS

The memcntl(2) function can fail for the following reasons:

[EAGAIN]

Insufficient resources to lock some or all of the memory.

[EBUSY]

One of the pages is locked in memory and MS_INVALIDATE was the command.

[EINVAL]

The addr is invalid. It must be a multiple of the page size. If the command is MC_LOCKAS or MC_UNLAOCKAS, the value of addr is not NULL, or the value of len is not zero. It may also mean the value of arg was not correct for the command given.

[EIO]

An I/O error occurred.

[ENOMEM]

The addresses in the range are not valid for the address space of the process, or are for pages that aren't mapped.

[EPERM]

A locking command was specified and the effective user ID does not have appropriate privileges.

SEE ALSO

fork(2)

mmap(2)

mctl(3)

msync(3)

sysconf(2)