'\"macro stdmacro
.if n .pH g2.mmap @(#)mmap	40.16 of 10/10/89
.\" Copyright 1989 AT&T
'\" ident	"@(#)svid_rt:rt_os/mmap	1.3"
.\" @(#)mmap 1.4 88/09/26 SMI;
'\" macro stdmacro
.\" Sun's mmap.2
.nr X
.if \nX=0 .ds x} mmap 2 "" "\&"
.if \nX=1 .ds x} mmap 2 ""
.if \nX=2 .ds x} mmap 2 "" "\&"
.if \nX=3 .ds x} mmap "" "" "\&"
.TH \*(x}
.SH NAME
\f4mmap\f1 \- map pages of memory
.SH SYNOPSIS
.ft 4
.na
#include <sys/types.h>
.br
#include <sys/mman.h>
.HP
\f4caddr_t mmap(caddr_t addr, size_t len, int prot, int flags, int fd, off_t off);\fP
.ad
.fi
.SH DESCRIPTION
The function \f4mmap\f1 establishes a mapping between a process's
address space and a virtual memory object.
The format of the call is as follows:
.P
.RS
\f2pa\f1 = \f4mmap(\f2addr\f4, \f2len\f4, \f2prot\f4, \f2flags\f4, \f2fd\f4, \f2off\f4);\f1
.RE
.P
\f4mmap\f1
establishes a mapping between the process's address space
at an address
\f2pa\f1
for
\f2len\f1
bytes to the memory object represented by
the file descriptor
\f2fd\f1
at offset
\f2off\f1
for
\f2len\f1
bytes.
The value of
\f2pa\f1
is an implementation-dependent function of the parameter
\f2addr\f1
and values of
.IR flags ,
further described below.
A successful
\f4mmap\f1
call returns
\f2pa\f1
as its result.
The address ranges covered by
[\f2pa, pa + len\f1\^)
and
[\f2off, off + len\f1\^)
must be legitimate for the
possible (not necessarily current)
address space of a process and the object in question, respectively.
\f4mmap\fP cannot grow a file.
.P
The mapping established by
\f4mmap\f1
replaces any previous mappings for the
process's pages in the range
[\f2pa, pa + len\f1\^).
.P
The parameter
\f2prot\f1
determines whether read, write, execute,
or some combination of accesses are permitted to the
pages being mapped. The protection options are defined in
\f4<sys/mman.h>\f1
as:
.sp .5
.RS
.ta 25n 30n
.nf
\f4PROT_READ\fP	Page can be read.
\f4PROT_WRITE\fP	Page can be written.
\f4PROT_EXEC\fP	Page can be executed.
\f4PROT_NONE\fP	Page can not be accessed.
.fi
.RE
.P
Not all implementations literally provide all possible combinations.
\f4PROT_WRITE\f1
is often implemented as
\f4PROT_READ\^|\^PROT_WRITE\f1
and
\f4PROT_EXEC\f1
as
\f4PROT_READ\^|\^PROT_EXEC\f1.
However, no implementation will permit a write to succeed where
\f4PROT_WRITE\f1
has not been set.
The behavior of
\f4PROT_WRITE\f1
can be influenced by setting
\f4MAP_PRIVATE\f1
in the
\f2flags\f1
parameter, described below.
.P
The parameter
\f2flags\f1
provides other information about the handling of
the mapped pages.
The options are defined in
\f4<sys/mman.h>\f1
as:
.P
.RS
.ta 25n 30n
.nf
\f4MAP_SHARED\fP	Share changes.
\f4MAP_PRIVATE\fP	Changes are private.
\f4MAP_FIXED\fP	Interpret addr exactly.
.fi
.RE
.P
\f4MAP_SHARED\f1
and
\f4MAP_PRIVATE\f1
describe the disposition of write references to
the memory object.
If
\f4MAP_SHARED\f1
is specified, write references will change
the memory object.
If
\f4MAP_PRIVATE\f1
is specified, the initial write reference
will create a private copy of the memory object page and redirect the
mapping to the copy. Either \f4MAP_SHARED\f1 or
\f4MAP_PRIVATE\f1 must be specified, but not both.
The mapping type is retained across a
\f4fork\f1(2).
.P
Note that the private copy is not created until
the first write;
until then,
other users who have the object mapped \f4MAP_SHARED\f1 can
change the object.
.P
\f4MAP_FIXED\f1
informs the system that the value of
\f2pa\f1
must be
.IR addr ,
exactly.
The use of
\f4MAP_FIXED\f1
is discouraged, as it may
prevent an implementation from making the most effective use of system
resources.
.P
When
\f4MAP_FIXED\f1
is not set, the system uses
\f2addr\f1
in an
implementation-defined manner to arrive at
.IR pa .
The
\f2pa\f1
so chosen will be an area of the address space which the system deems
suitable for a mapping of
\f2len\f1
bytes
to the specified object.
All implementations interpret
an
\f2addr\f1
value of zero as
granting the system complete freedom in selecting
.IR pa ,
subject to constraints described below.
A non-zero value
of
\f2addr\f1
is taken to be a suggestion of a process address near which
the
mapping should be placed.
When the system selects a value for
.IR pa ,
it will never place a mapping at address \f40\f1, nor will it
replace any extant mapping, nor map into areas considered part of the potential
data or stack \(lqsegments\(rq.
.P
The parameter
\f2off\f1
is constrained to be
aligned and sized according to the value returned by
\f4sysconf\fP.
When
\f4MAP_FIXED\f1
is specified, the parameter
\f2addr\f1
must also meet these constraints.
The system performs mapping operations over whole pages.
Thus, while the parameter
\f2len\f1
need not meet a size or alignment constraint, the
system will include, in any mapping operation, any partial page specified
by the range
[\f2pa, pa + len\f1\^).
.P
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
\f4SIGBUS\f1
signal.
\f4SIGBUS\f1 signals may also be delivered on various file system
conditions, including quota exceeded errors.
.SH RETURN VALUE
On success, \f4mmap\f1 returns the 
address at which the mapping was placed (\f2pa\f1).
On failure it returns \f4(caddr_t)\-1\f1 and sets \f4errno\f1 to 
indicate an error.
.SH ERRORS
Under the following conditions, \f4mmap\f1
fails and sets \f4errno\f1 to:
.TP .75i
\f4EAGAIN\f1
The mapping could not be locked in memory.
.TP
\f4EBADF\f1
.I fd
is not open.
.TP
\f4EACCES\f1
.I fd
is not open for read, regardless of the protection specified, or
\f2fd\f1 is not open for write and \f4PROT_WRITE\f1 was specified for
a \f4MAP_SHARED\f1 type mapping.
.TP
\f4ENXIO\f1
Addresses in the range
[\f2off, off + len\f1\^)
are invalid for
.IR fd .
.TP
\f4EINVAL\f1
The arguments
\f2addr\f1
(if
\f4MAP_FIXED\f1
was specified) or
\f2off\f1
are not multiples of the page size as returned by
\f4sysconf\fP.
.TP
\f4EINVAL\f1
The field in
\f2flags\f1
is invalid (neither \f4MAP_PRIVATE\f1 or \f4MAP_SHARED\f1).
.TP
\f4EINVAL\f1
The argument
\f2len\f1
has a value less than or equal to \f40\f1.
.TP
\f4ENODEV\f1
.I fd
refers to an object for which
\f4mmap\f1
is meaningless, such as a terminal.
.TP
\f4ENOMEM\f1
\f4MAP_FIXED\f1
was specified and the range
[\f2addr, addr + len\f1\^)
exceeds that allowed for the address space of a process,
or
\f4MAP_FIXED\f1
was not specified and there is insufficient room in the address space
to effect the mapping.
.SH NOTES
\f4mmap\fP allows access to resources via address space
manipulations instead of the \f4read\fP/\f4write\fP 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:
.P
.RS
.nf
.na
.ft 4
fd = open(...)
lseek(fd, offset)
read(fd, buf, len)
/* use data in buf */
.ft 1
.fi
.RE
.P
Here is a rewrite using \f4mmap\fP:
.P
.RS
.nf
.na
.ft 4
fd = open(...)
address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
               MAP_PRIVATE, fd, offset)
/* use data at address */
.ft 1
.fi
.RE
.SH SEE ALSO
.na
\f4fcntl\fP(2),
\f4fork\fP(2),
\f4lockf\fP(3C),
\f4mlockall\fP(3C),
\f4mprotect\fP(2),
\f4munmap\fP(2),
\f4plock\fP(2),
\f4sysconf\fP(2).
.ad
