System Interface Guide

Memory Management Interfaces

The virtual memory facilities are used and controlled through several sets of functions. This section summarizes these calls and provides examples of their use.

Creating and Using Mappings

mmap(2) establishes a mapping of a named file system object (or part of one) into a process address space. It is the basic memory management function and it is very simple. First open(2) the file, then mmap(2) it with appropriate access and sharing options and go about your business.

The mapping established by mmap(2) replaces any previous mappings for specified address range.

The flags MAP_SHARED and MAP_PRIVATE specify the mapping type, and one of them must be specified. MAP_SHARED specifies that writes modify the mapped object. No further operations on the object are needed to make the change. MAP_PRIVATE specifies that an initial write to the mapped area creates a copy of the page and all writes reference the copy. Only modified pages are copied.

A mapping type is retained across a fork(2).

The file descriptor used in a mmap(2) call need not be kept open after the mapping is established. If it is closed, the mapping remains until the mapping is undone by munmap(2) or be replacing it with a new mapping.

If a mapped file is shortened by a call to truncate, an access to the area of the file that no longer exists causes a SIGBUS signal.

Mapping /dev/zero gives the calling program a block of zero-filled virtual memory of the size specified in the call to mmap(2). The following code fragment demonstrates a use of this to create a block of scratch storage in a program, at an address that the system chooses.


	int fd;
 caddr_t result;

 if ((fd = open("/dev/zero", O_RDWR)) == -1)
 	return ((caddr_t)-1);
 result = mmap(0, len, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
 (void) close(fd);

Some devices or files are useful only if accessed by mapping. An example of this is frame buffer devices used to support bit-mapped displays, where display management algorithms function best if they can operate randomly on the addresses of the display directly.

Removing Mappings

munmap(2) removes all mappings of pages in the specified address range of the calling process. munmap(2) has no affect on the objects that were mapped.

Cache Control

The SunOS 5.0 through 5.8 virtual memory system is a cache system, in which processor memory buffers data from file system objects. There are interfaces to control or interrogate the status of the cache.

mincore(2)

mincore(2) determines the residency of the memory pages in the address space covered by mappings in the specified range. Because the status of a page can change after mincore(2) checks it, but before mincore(2) returns the data, returned information can be outdated. Only locked pages are guaranteed to remain in memory.

mlock(3C) and munlock(3C)

mlock(3C) causes the pages in the specified address range to be locked in physical memory. References to locked pages (in this or other processes) do not result in page faults that require an I/O operation. This operation ties up physical resources and can disrupt normal system operation, so, use of mlock(3C) is limited to the superuser. The system lets only a configuration dependent limit of pages be locked in memory. The call to mlock(3C) fails if this limit is exceeded.

munlock(3C) releases the locks on physical pages. If multiple mlock(3C) calls are made on an address range of a single mapping, a singlemunlock(3C) call is release the locks. However, if different mappings to the same pages are mlock(3C)ed, the pages are not unlocked until the locks on all the mappings are released.

Locks are also released when a mapping is removed, either through being replaced with an mmap(2) operation or removed with munmap(2).

A lock is transferred between pages on the "copy-on-write" event associated with a MAP_PRIVATE mapping, thus locks on an address range that includes MAP_PRIVATE mappings are retained transparently along with the copy-on-write redirection (see mmap(2) above for a discussion of this redirection).

mlockall(3C) and munlockall(3C)

mlockall(3C)and munlockall(3C) are similar to mlock(3C) and munlock(3C), but they operate on entire address spaces. mlockall(3C) sets locks on all pages in the address space and munlockall(3C) removes all locks on all pages in the address space, whether established by mlock(3C) or mlockall(3C).

msync(3C)

msync(3C) causes all modified pages in the specified address range to be flushed to the objects mapped by those addresses. It is similar to fsync(3C) for files.

Other Memory Control Functions

sysconf(3C)

sysconf(3C) returns the system dependent size of a memory page. For portability, applications should not embed any constants specifying the size of a page. Note that it is not unusual for page sizes to vary even among implementations of the same instruction set.

mprotect(2)

mprotect(2) assigns the specified protection to all pages in the specified address range. The protection cannot exceed the permissions allowed on the underlying object.

brk(2) and sbrk(2)

brk(2) and sbrk(2) are called to add storage to the data segment of a process.

A process can manipulate this area by calling brk(2) and sbrk(2):


caddr_t
 brk(caddr_t addr);

 caddr_t
 sbrk(intptr_t incr); 

brk(2) identifies the lowest data segment location not used by the caller as addr (rounded up to the next multiple of the system page size).

sbrk(2), the alternate function, adds incr bytes to the caller data space and returns a pointer to the start of the new data area.