NAME

mlockall, munlockall − POSIX 1003.4 Process Memory Locking

SYNOPSIS

#include <sys/mman.h>

int mlockall(flags)

int flags

int munlockall(void)

DESCRIPTION

The mlockall() function causes all of the process’ virtual address space to be memory resident until unlocked, or until the process exits or execs another process image.  The flags argument determines whether the space to be locked would be limited to the process’ current virtual address space or the process’ current virtual address space plus any future expansion.  Flags is constructed from the OR of one or more of the following symbolic constants, defined in <sys/mman.h>:

MCL_CURRENT

Lock all of the process’ virtual address space, not including subsequent expansion of this space. 

MCL_FUTURE

Lock all new virtual pages added to the process’ virtual address space after the call to mlockall(). 

MCL_CURRENT must be specified. 

If MCL_FUTURE is specified:

If the automatic locking of future mappings causes the minimum number of real memory pages in global memory available to the kernel to fall below a system limit, the new mappings are not locked and the process is notified.  Each page in global memory that is locked causes the number of real memory pages available to the kernel to decrease. 

If the new mapping is due to the growth of the stack region then error notification consists of a SIGSEGV signal being sent to the process.  A process’ user stack is automatically extended when the process accesses a location beyond the the current end of the stack region, but within the extendable stack space. 

If the new mapping is due to the growth of the data region or to the allocation of a shared memory segment region, then error notification is handled by the system call the process made to get the new mapping, e.g. sbrk() and shmat(). 

The munlockall() function unlocks all of the process’ virtual address space.  Any pages that become mapped into the process’s address space after a call to munlockall() are not locked, unless there is an intervening call to mlockall().  If pages mapped into the process’s address space are also mapped into other process’s address spaces and are locked by those processes, the locks established by the other processes are unaffected by this process’s call to munlockall(). 

Locks are not nested. The process address space may be locked several times with mlockall() but will be unlocked by a single call to munlockall(). 

Per-process memory locks are not inherited across a fork(), and all memory locks owned by a process are unlocked upon exec() or process termination. 

To use both of these library calls, the caller must either be a superuser or have the ACC_PLOCK bit set in its access vector. 

These interfaces should not be used to lock memory regions which will be used for direct I/O. See userdma(2) for an interface that can be used for this purpose. 

RETURN VALUE

Upon successful completion, the mlockall() function returns a value of zero.  Otherwise, no memory is locked, a value of -1 is returned and errno is set to indicate the error. 

The munlockall() function always returns a value of zero. 

If any of the following conditions occur, the mlockall() function returns -1 and sets errno to the corresponding value:

[EAGAIN] Some or all of the memory identified by the operation could not be locked when the call was made. 

[EINVAL] The flags argument is zero, or includes unimplemented flags.  MCL_CURRENT and MCL_CURRENT|MCL_FUTURE are supported.  MCL_FUTURE is not supported. 

[EPERM] The effective user ID of the calling process is not super-user or the user does not have the ACC_PLOCK access vector (If access vectors are configured). 

FILES

/usr/lib/libposix4.a

SEE ALSO

mlock(3P4), fork(2), exec(2), exit(2). 

BUGS

The current implementation requires the user to specify MCL_CURRENT. Specifying MCL_FUTURE by itself is illegal. 

A call to mlockall() with only the MCL_CURRENT flag specified is supported with a slight variation from the implementation specified by POSIX 1003.4.  When MCL_CURRENT is specified, all pages in the regions currently held by a process are locked. Pages allocated in the future to those regions are implicitly locked. Regions which are subsequently added to the process’ address space are not locked. 

WARNING

The interfaces to mlockall() and munlockall() are based on IEEE Draft Standard P1003.4/D12.  This is an unapproved draft, subject to change.  Use of information contained in this unapproved draft is at your own risk.  This interface will change to reflect any changes made by future drafts of POSIX 1003.4. 

CX/UX Programmer’s Reference Manual