MMAP(2)             RISC/os Reference Manual              MMAP(2)



NAME
     mmap, munmap - map or unmap pages of memory

SYNOPSIS
     For -systype sysv and -systype bsd43:

     #include <sys/mman.h>
     #include <sys/types.h>

     mmap(addr, len, prot, share, fd, off)
     caddrt addr;
     int len, prot, share, fd;
     offt off;

     munmap (addr, len)
     caddrt addr;
     int len;

DESCRIPTION
     mmap maps pages of memory from the memory device associated
     with the file fd into the address space of the calling pro-
     cess, one page at a time.  Pages are mapped from the memory
     device, beginning at off, and into the caller's address
     space, beginning at addr, and continuing for len bytes.  fd
     is a file descriptor obtained by opening the device from
     which to map pages.  Only character-special devices are
     currently supported.

     share specifies whether modifications made to mapped-in
     copies of pages are to be kept "private" or are to be
     "shared" with other references.  Currently, it must be set
     to MAP_SHARED.

     The parameter prot specifies the read/write accessibility of
     the mapped pages.  The addr and len parameters, and the sum
     of the current position in fd and off parameters, must be
     multiples of pagesize (found using the getpagesize(2) call).
     malloc(3) returns a properly aligned buffer if the request
     is for pagesize or larger bytes.

     Currently, only 1 device may be mapped by a process. The
     file descriptor must be closed to allow mapping of another
     device.

     All pages are automatically unmapped when fd is closed.
     Specific pages can be unmapped explicitly using munmap.

     mmap can sometimes be used to install memory-mapped devices
     without writing a device driver.  However, this does not
     always work.  In particular, devices that are mmap'ed into
     user space and then accessed by user programs will see those
     accesses in user mode.  If the device contains registers



                         Printed 1/15/91                   Page 1

MMAP(2)             RISC/os Reference Manual              MMAP(2)



     that must be accessed in supervisor mode, mmap cannot be
     used to drive it.

     The virtual pages mapped by mmap may not be part of a region
     shared with any other process.  If a caller attempts to mmap
     shared pages, the request will be rejected with error EIN-
     VAL.

     munmap unmaps previously mapped pages starting at addr and
     continuing for len bytes.  Unmapped pages refer, once again,
     to private pages within the caller's address space.
     Unmapped pages are initialized to zero.

RETURN VALUE
     Each call returns 0 on success, -1 on failure.

ERRORS
     Both calls fail when:

     EINVAL The argument address or length is not a multiple of
            the page size as returned by getpagesize(2), or the
            length is negative.

     EINVAL The entire range of pages specified in the call is
            not part of data space.

     In addition mmap fails when:

     EINVAL The specified fd does not refer to a character spe-
            cial device which supports mapping (e.g. a frame
            buffer).

     EINVAL The specified fd is not open for reading and read
            access is requested, or not open for writing when
            write access is requested.

     EINVAL The sharing mode was not specified as MAP_SHARED.

     EINVAL Another file mapped by mmap is open.

     EINVAL An attempt was made to map a page that is being
            shared with another process.

SEE ALSO
     close(2), getpagesize(2), malloc(3).










 Page 2                  Printed 1/15/91