mlock(3P4)                                             mlock(3P4)



NAME
     mlock, munlock - lock / unlock a range of process memory

SYNOPSIS
     #include <sys/mman.h>

     int mlock(addr, len)

          caddrt *addr

          sizet len

     int munlock(addr, len)

          caddrt *addr

          sizet len

DESCRIPTION
     The function mlock causes all of the pages mapped by the
     range addr to addr + len
      - 1 inclusive to be memory resident until unlocked, or
     until the process exits or execs another process image.  The
     argument addr has to be a multiple of the page size returned
     by sysconf(2).  The area locked is a multiple of the system
     page size such that it contains the specified address range.

     The function munlock unlocks all of the pages mapped by the
     range addr to addr + len
      - 1 inclusive. The area unlocked is a multiple of the sys-
     tem page size such that it contains the specified address
     range.  Locks are nested, hence, the number of munlock calls
     required to unlock the address range is the same as the
     number of mlock calls made on that address range.

     Upon successful return from mlock, pages encompassing the
     specified range are locked and are memory resident. Upon
     successful return from munlock, the lock counts of the pages
     encompassing the specified range are decremented.

     Per-process memory locks for ranges of pages are not inher-
     ited across a fork, and all memory locks owned by a process
     are unlocked upon exec(2) 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.




Page 1                        CX/UX Programmer's Reference Manual

mlock(3P4)                                             mlock(3P4)



RETURN VALUE
     Upon successful completion, the mlock and munlock functions
     return a value of zero.  Otherwise, a value of -1 is
     returned and errno is set to indicate the error.

     If any of the following conditions occur, the mlock and mun-
     lock functions return -1 and set errno to the corresponding
     value:

     [EINVAL]       The addr argument is not a multiple of the
                    page size returned by sysconf(2).

     [ENOMEM]       Some or all of the address range specified by
                    the addr and len arguments does not
                    correspond to valid mapped pages in the
                    process's address space.

     If any of the following conditions occur, the mlock function
     shall return -1 and set 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.

     [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 vec-
                    tors are configured).

FILES
     /usr/lib/libposix4.a

SEE ALSO
     mlockall(3P4), fork(2), exec(2), exit(2).

BUGS
     If any of the pages in the range specified to a call to mun-
     lock are also mapped into another process' address spaces,
     locks established on those pages by another process may be
     affected by this process's call to munlock.  munlock decre-
     ments the lock count on a page even when the current process
     was not the one that originally locked the page in memory.

WARNING
     The interfaces to mlock and munlock 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.






Page 2                        CX/UX Programmer's Reference Manual