MPIN(2)                                                                MPIN(2)


NAME
     mpin, munpin - lock pages in memory

SYNOPSIS
     int mpin (void *addr, size_t);

     int munpin (void *addr, size_t);

DESCRIPTION
     mpin reads into memory all pages over the range (addr, addr + len), and
     locks the pages into memory.  Associated with each locked page is a
     counter which is incremented each time the page is locked.  The super-
     user can lock as many pages as it wishes, other users are limited to a
     configurable per process maximum.

     munpin decrements the lock counter associated with the pages over the
     range (addr, addr + len).  Pages whose counters are zero are available to
     be swapped out at the system's discretion.

     mpin or munpin will fail if one or more of the following are true:

     [EINVAL]       The addresses specified by (addr, addr + len) are not
                    mapped into the user's address space.

     [EAGAIN]       There was insufficient lockable memory to lock the entire
                    address range (addr, addr + len).  This may occur even
                    though the amount requested was less than the system-
                    imposed maximum number of locked pages.

     [EBUSY]        munpin will fail with this error if the address range
                    specified has some active I/O initiated by some other
                    process belonging to same share group.

     [ENOMEM]       The caller was not super-user and the number of pages to
                    be locked exceeded the per process limit {PLOCK_MAX} [see
                    intro(2)].

     [ENOMEM]       The total number of pages locked by the caller would
                    exceed the maximum resident size for the process [see
                    setrlimit(2)].

     [ENOSPC]       The address range (addr, addr + len) contains a memory-
                    mapped file, and there is insufficient space on the device
                    to allocate the entire file.

SEE ALSO
     intro(2), getrlimit(2), mlock(3C), mlockall(3C), plock(2), ulimit(2).

DIAGNOSTICS
     Upon successful completion, mpin and munpin return 0.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.


WARNING
     The functions mpin/munpin and mlock/munlock provide similar
     functionality.  The major difference between the two sets is that
     mpin/munpin maintains a per page lock counter and mlock/munlock does not.
     Developers should choose the set that best suites their application and
     stick with it, as mixing the interfaces may result in unexpected
     behavior.


                                                                        Page 2