mctl(3-BSD)       MISC. REFERENCE MANUAL PAGES        mctl(3-BSD)



NAME
     mctl - memory management control

SYNOPSIS
     cc [ flag... ] file ...  -lucb
     #include <sys/types.h>
     #include <sys/mman.h>
     mctl(caddrt addr, sizet len, int function, void *arg);

DESCRIPTION
     mctl applies a variety of control functions over pages iden-
     tified  by  the  mappings  established for the address range
     [addr, addr + len).  The function to be performed is identi-
     fied  by the argument function.  Valid functions are defined
     in mman.h as follows.

     MCLOCK
          Lock the pages in the range in memory. This function is
          used  to support mlock.  See mlock(3) for semantics and
          usage.  arg is ignored.

     MCLOCKAS
          Lock the pages in the address  space  in  memory.  This
          function  is used to support mlockall.  See mlockall(3)
          for semantics and usage.  addr  and  len  are  ignored.
          arg is an integer built from the flags:
                    MCLCURRENT   Lock current mappings
                    MCLFUTURE    Lock future mappings

     MCSYNC
          Synchronize the pages in the range with  their  backing
          storage.   Optionally  invalidate  cache  copies.  This
          function is used to support msync.   See  msync(3)  for
          semantics  and  usage.   arg  is  used to represent the
          flags argument to msync.  It is constructed from an  OR
          of the following values:
                    MSSYNC         Synchronized write
                    MSASYNC        Return immediately
                    MSINVALIDATE   Invalidate mappings

          MSASYNC  returns  after   all   I/O   operations   are
          scheduled.   MSSYNC  does  not  return  until  all I/O
          operations  are  complete.   Specify  exactly  one   of
          MSASYNC  or  MSSYNC.   MSINVALIDATE  invalidates all
          cached copies of data from memory, requiring them to be
          re-obtained  from  the object's permanent storage loca-
          tion upon the next reference.

     MCUNLOCK
          Unlock the pages in the range.  This function  is  used
          to  support  munlock.  See munlock(3) for semantics and
          usage.  arg is ignored.



                                                                1

mctl(3-BSD)       MISC. REFERENCE MANUAL PAGES        mctl(3-BSD)



     MCUNLOCKAS
          Remove address space memory  lock,  and  locks  on  all
          current  mappings.   This  function  is used to support
          munlockall(3).  addr and len must  have  the  value  0.
          arg is ignored.

RETURN VALUE
     mctl returns 0 on success, -1 on failure.

ERRORS
     mctl fails if:

     EAGAIN              Some or all of the memory identified  by
                         the operation could not be locked due to
                         insufficient system resources.

     EBUSY               MSINVALIDATE was specified and  one  or
                         more of the pages is locked in memory.

     EINVAL              addr is not a multiple of the page  size
                         as returned by getpagesize.

     EINVAL              addr and/or len do not have the value  0
                         when MCLOCKAS or MCUNLOCKAS are speci-
                         fied.

     EINVAL              arg is not valid for the function speci-
                         fied.

     EIO                 An I/O error occurred while reading from
                         or writing to the file system.

     ENOMEM              Addresses in the  range  [addr,  addr  +
                         len)  are  invalid for the address space
                         of a process, or  specify  one  or  more
                         pages which are not mapped.

     EPERM               The process's effective user ID  is  not
                         super-user    and    one   of   MCLOCK,
                         MCLOCKAS, MCUNLOCK, or MCUNLOCKAS was
                         specified.

SEE ALSO
     getpagesize(3).  mmap(2), mlock(3C), mlockall(3C), msync(3C)
     in the Programmer's Reference Manual.










                                                                2