mmap(2)

map pages of memory

From the original Amiga UNIX 2.1 manual. Some things it mentions may not be in this release.

NAME

mmap - map pages of memory

SYNOPSIS

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

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

DESCRIPTION

The function mmap establishes a mapping between a  process's
address  space  and  a virtual memory object.  The format of
the call is as follows:
     pa = mmap(addr, len, prot, flags, fd, off);
mmap establishes a mapping  between  the  process's  address
space  at  an  address pa for len bytes to the memory object
represented by the file descriptor fd at offset off for  len
bytes.  The value of pa is an implementation-dependent func-
tion of the parameter addr  and  values  of  flags,  further
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 (not
necessarily current) address space  of  a  process  and  the
object  in question, respectively.  mmap cannot grow a file.
The mapping established by mmap replaces any  previous  map-
pings  for  the process's pages in the range [pa, pa + len).
The parameter prot determines whether read, write,  execute,
or  some  combination of accesses are permitted to the pages
being  mapped.  The  protection  options  are   defined   in
<sys/mman.h> as:

     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  com-
binations.     PROT_WRITE    is    often    implemented   as
PROT_READ|PROT_WRITE and PROT_EXEC  as  PROT_READ|PROT_EXEC.
However,  no  implementation  will permit a write to succeed
where  PROT_WRITE  has  not  been  set.   The  behavior   of
PROT_WRITE  can  be influenced by setting MAP_PRIVATE in the
flags parameter, described below.  The parameter flags  pro-
vides  other  information  about  the handling of the mapped
pages.  The options are defined in <sys/mman.h> as:
     MAP_SHARED               Share changes.
     MAP_PRIVATE              Changes are private.
     MAP_FIXED                Interpret addr exactly.
MAP_SHARED and MAP_PRIVATE describe the disposition of write
references  to  the  memory object.  If MAP_SHARED is speci-
fied, 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 page and redirect
the  mapping  to  the copy. Either MAP_SHARED or MAP_PRIVATE
must be specified,  but  not  both.   The  mapping  type  is
retained  across  a  fork(2).  Note that the private copy is
not created until the first write; until then,  other  users
who have the object mapped MAP_SHARED can change the object.
MAP_FIXED informs the system that the value of  pa  must  be
addr,  exactly.   The use of MAP_FIXED is discouraged, as it
may prevent an implementation from making the most effective
use  of  system  resources.   When MAP_FIXED is not set, the
system uses addr  in  an  implementation-defined  manner  to
arrive  at  pa.   The  pa  so  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 zero as granting the system  com-
plete  freedom  in  selecting  pa,  subject  to  constraints
described below.  A non-zero value of addr is taken to be  a
suggestion  of  a  process  address  near  which the mapping
should be placed.  When the system selects a value  for  pa,
it  will  never  place  a  mapping at address 0, nor will it
replace any extant mapping, nor map  into  areas  considered
part of the potential data or stack segments.  The parameter
off is constrained to be aligned and sized according to  the
value returned by sysconf.  When MAP_FIXED is specified, the
parameter addr must also meet these constraints.  The system
performs  mapping  operations over whole pages.  Thus, while
the parameter len need not meet a  size  or  alignment  con-
straint,  the system will include, in any mapping operation,
any partial page specified by the range [pa, pa + len).  The
system  will always zero-fill any partial page at the end of
an object.  Further, 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 SIGBUS signal.
SIGBUS signals may also be delivered on various file  system
conditions, including quota exceeded errors.

RETURN VALUE

On success, mmap returns the address at which the mapping was placed (pa). On failure it returns (caddr_t)-1 and sets errno to indicate an error.

ERRORS

Under the following conditions, mmap fails and sets errno to:

EAGAIN The mapping could not be locked in memory.

EBADF  fd is not open.

EACCES fd is not open for read, regardless of the protection
       specified, or fd is not open for write and PROT_WRITE
       was specified for a MAP_SHARED type mapping.

ENXIO Addresses in the range [off, off + len) are invalid for fd.

EINVAL The arguments addr (if MAP_FIXED  was  specified)  or
       off are not multiples of the page size as returned by
       sysconf.

EINVAL The field in flags is invalid (neither MAP_PRIVATE or
       MAP_SHARED).

EINVAL The argument len has a value less than or equal to 0.

ENODEV fd refers to an object for which mmap is meaningless,
       such as a terminal.

ENOMEM MAP_FIXED was specified and the range [addr,  addr  +
       len)  exceeds that allowed for the address space of a
       process, or MAP_FIXED was not specified and there  is
       insufficient  room in the address space to effect the
       mapping.

NOTES

mmap allows access to resources via address space  manipula-
tions  instead  of the read/write interface.  Once a file is
mapped, all a process has to do to access it is use the data
at the address to which the object was mapped.  Consider the
following pseudo-code:
     fd = open(...)
     lseek(fd, offset)
     read(fd, buf, len)
     /* use data in buf */
Here is a rewrite using mmap:
     fd = open(...)
     address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
                    MAP_PRIVATE, fd, offset)
     /* use data at address */