NAME

mmap, munmap − map or unmap pages of memory

SYNOPSIS

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

mmap(addr, len, prot, share, fd, off)
caddr_t addr; int len, prot, share, fd; off_t off;

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

DESCRIPTION

Mmap

mmap maps pages of memory from the memory device associated with the file fd into the address space of the calling process, 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 the page size (found using the getpagesize(2) call).  For this reason, local memory space beginning at addr should be allocated using valloc(2), which supplies a buffer with proper page alignment.

When mapping an area of 128K or more, the kernel releases the swap area associated with it.  Consequently, when the pages are unmapped, they are marked invalid; the next call to valloc(2) returns the invalid pages, and any attempt to refer to those pages results in a segmentation violation.  To avoid this, do not free(2) such large areas; instead, call valloc(2) again without calling free(2).

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 that must be accessed in supervisor mode, mmap cannot be used to drive it.  (See Writing Device Drivers for the Sun Workstation for more information.) 

Munmap

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.  Pages are initialized to zero, unless len is greater than or equal to 128K, in which case the pages are marked invalid. 

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 special 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. 

SEE ALSO

getpagesize(2), munmap(2), close(2)

BUGS

The kernel may panic when more than 128k of memory has been unmapped with munmap(1) and mmap is subsequently called with an incorrect length value. 

If 128K of memory, or more, is unmapped as a result of closing fd, the resulting invalid pages cannot be reclaimed within the life of the calling process. 

Sun Release 3.5  —  Last change: 11 July 1986