mmap(2) CLIX mmap(2)
NAME
mmap - Maps pages of memory
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
caddr_t pa;
pa = caddr_t mmap(
caddr_t addr ,
size_t len ,
int prot ,
int flags ,
int fd ,
off_t off );
PARAMETERS
addr Specifies a page-aligned address at which to place the mapping.
len Specifies the number of bytes to map.
prot Determines whether read, write, execute, or some combination of
accesses are permitted to the pages being mapped.
flags Provides additional information about the handling of the mapped
pages.
fd Specifies a valid, open file descriptor obtained with the open()
call.
off Specifies an offset within the file where the mapping should
start.
DESCRIPTION
The mmap() function establishes a mapping between the process's address
space at an address pa for len bytes to the memory object represented by
fd for len bytes. The value of pa is an implementation-dependent function
of the parameter addr and values of flags, described below. A successful
mmap() call returns pa as its result. The address ranges covered by [pa,
pa + len] and [off, off + len] must be legitimate for the possible address
space of a process and the object in question, respectively.
2/94 - Intergraph Corporation 1
mmap(2) CLIX mmap(2)
The prot parameter determines whether read, write, execute, or some
combination of accesses are permitted to the pages being mapped. The
protection options are defined in the <sys/mman.h> header file as follows:
PROT_READ /* page can be read */
PROT_WRITE /* page can be written */
PROT_EXEC /* page can be executed */
PROT_NONE /* page can not be accessed */
Not all implementations literally provide all possible combinations. The
PROT_WRITE option is often implemented as PROT_READ | PROTWRITE and
PROT_EXEC as PROT_READ | PROT_EXEC. However, no implementation shall
permit a write to succeed where a PROT_WRITE has not been set. The
behavior of PROT_WRITE can be influenced by setting MAP_PRIVATE in the
flags parameter.
The flags parameter provides other information about the handling of the
mapped pages. Valid options for flags, defined in the <sys/mman.h> header
file are as follows:
MAP_SHARED /* Share changes */
MAP_PRIVATE /* Changes are private */
MAP_FIXED /* Interpret address exactly */
The MAP_SHARED and MAP_PRIVATE options describe the disposition of write
references to the memory object. If MAP_SHARED is specified, write
references will change the memory object. If MAP_PRIVATE is specified,
the initial write reference will create a private copy of the memory
object and redirect the mapping to the copy. The mapping type is retained
across a fork.
The MAP_FIXED option informs the system that the value pa must be addr
exactly. The use of MAP_FIXED is discouraged, since it may prevent an
implementation from making the most effective use of system resources.
When MAPPED_FIXED is not set, the system uses addr in an implementation-
defined manner to arrive at pa. The pa chosen will be an area of the
address space which the system deems suitable for a mapping of len bytes
to the specified object. All implementations interpret an addr value of 0
as granting the system complete freedom in selecting pa, subject to
constraints described below. A nonzero value of addr is taken to be a
suggestion of a process address that the mapping should be placed near.
When the system selects a value for pa, it will never place a mapping at
address 0, not will it replace any extant mapping, not map into areas
considered part of the potential data, text, or stack segments.
The system will always zero-fill any partial page at the end of an object.
However, the system will never write out any modified portions of the last
page of an object which are beyond its end. References to whole pages
following the end of an object will result in the delivery of a SIGSEGV
signal.
2 Intergraph Corporation - 2/94
mmap(2) CLIX mmap(2)
RETURN VALUES
A successful mmap() function call returns the address at which the mapping
was placed. A unsuccessful mmap() call returns -1 and sets errno to the
following errors.
ERRORS
The mmap() function fails if any of the following are true:
[EAGAIN]
The mapping could not be locked in memory.
[EAGAIN]
The fd parameter is already mapped with arguments off and len that
are different than the current invocation.
[EBADF]
The fd parameter is not open.
[EACCESS]
The fd parameter is not open for read, regardless of the
protections specified, or fd is not open for writing and PROT_WRITE
was specified.
[ENXIO]
The addresses in the range [off, off + len] are invalid for fd.
[EINVAL]
The parameter addr (if MAP_FIXED was specified) or off are not
multiples of the page size as returned by getpagesize().
[EINVAL]
The field in flags is invalid (neither MAP_PRIVATE or MAP_SHARED is
specified).
[ENODEV]
The fd parameter refers to an object for which mmap() is
meaningless, such as a terminal.
[ENOMEM]
MAPPED_FIXED was specified and the range [addr, addr + len] exceeds
that allowed for the address space of the process. Or, if
MAPPED_FIXED was not specified and there is insufficient room in
the address space to effect the mapping.
RELATED INFORMATION
Functions: getpagesize(2), munmap(2), msync(2), fork(2), open(2)
2/94 - Intergraph Corporation 3