618 lines
31 KiB
HTML
618 lines
31 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>mmap</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="mmap"></a> <a name="tag_03_379"></a><!-- mmap -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_379_01"></a>NAME</h4>
|
|
|
|
<blockquote>mmap - map pages of memory</blockquote>
|
|
|
|
<h4><a name="tag_03_379_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('MF')">MF|SHM</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/sys/mman.h.html">sys/mman.h</a>><br>
|
|
<br>
|
|
void *mmap(void *</tt><i>addr</i><tt>, size_t</tt> <i>len</i><tt>, int</tt> <i>prot</i><tt>, int</tt> <i>flags</i><tt>,<br>
|
|
int</tt> <i>fildes</i><tt>, off_t</tt> <i>off</i><tt>); <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_379_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>mmap</i>() function shall establish a mapping between a process' address space and a file, shared memory object, or
|
|
<sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
typed memory object. <img src="../images/opt-end.gif" alt="[Option End]" border="0"> The format of the call is as
|
|
follows:</p>
|
|
|
|
<pre>
|
|
<i>pa</i><tt>=</tt><i>mmap</i><tt>(</tt><i>addr</i><tt>,</tt> <i>len</i><tt>,</tt> <i>prot</i><tt>,</tt> <i>flags</i><tt>,</tt> <i>fildes</i><tt>,</tt> <i>off</i><tt>);
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <i>mmap</i>() function shall establish a mapping between the address space of the process at an address <i>pa</i> for
|
|
<i>len</i> bytes to the memory object represented by the file descriptor <i>fildes</i> at offset <i>off</i> for <i>len</i> bytes.
|
|
The value of <i>pa</i> is an implementation-defined function of the parameter <i>addr</i> and the values of <i>flags</i>, further
|
|
described below. A successful <i>mmap</i>() call shall return <i>pa</i> as its result. The address range starting at <i>pa</i> and
|
|
continuing for <i>len</i> bytes shall be legitimate for the possible (not necessarily current) address space of the process. The
|
|
range of bytes starting at <i>off</i> and continuing for <i>len</i> bytes shall be legitimate for the possible (not necessarily
|
|
current) offsets in the file, shared memory object, or <sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src=
|
|
"../images/opt-start.gif" alt="[Option Start]" border="0"> typed memory object <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"> represented by <i>fildes</i>.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If <i>fildes</i> represents a typed memory object opened with either the POSIX_TYPED_MEM_ALLOCATE flag or the
|
|
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the memory object to be mapped shall be that portion of the typed memory object allocated by
|
|
the implementation as specified below. In this case, if <i>off</i> is non-zero, the behavior of <i>mmap</i>() is undefined. If
|
|
<i>fildes</i> refers to a valid typed memory object that is not accessible from the calling process, <i>mmap</i>() shall fail. <img
|
|
src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>The mapping established by <i>mmap</i>() shall replace any previous mappings for those whole pages containing any part of the
|
|
address space of the process starting at <i>pa</i> and continuing for <i>len</i> bytes.</p>
|
|
|
|
<p>If the size of the mapped file changes after the call to <i>mmap</i>() as a result of some other operation on the mapped file,
|
|
the effect of references to portions of the mapped region that correspond to added or removed portions of the file is
|
|
unspecified.</p>
|
|
|
|
<p>The <i>mmap</i>() function shall be supported for regular files, shared memory objects, and <sup>[<a href=
|
|
"javascript:open_code('TYM')">TYM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> typed memory
|
|
objects. <img src="../images/opt-end.gif" alt="[Option End]" border="0"> Support for any other type of file is unspecified.</p>
|
|
|
|
<p>The parameter <i>prot</i> determines whether read, write, execute, or some combination of accesses are permitted to the data
|
|
being mapped. The <i>prot</i> shall be either PROT_NONE or the bitwise-inclusive OR of one or more of the other flags in the
|
|
following table, defined in the <a href="../basedefs/sys/mman.h.html"><i><sys/mman.h></i></a> header.</p>
|
|
|
|
<center>
|
|
<table border="1" cellpadding="3" align="center">
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>Symbolic Constant</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Description</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">PROT_READ</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Data can be read.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">PROT_WRITE</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Data can be written.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">PROT_EXEC</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Data can be executed.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">PROT_NONE</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Data cannot be accessed.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>If an implementation cannot support the combination of access types specified by <i>prot</i>, the call to <i>mmap</i>() shall
|
|
fail.</p>
|
|
|
|
<p>An implementation may permit accesses other than those specified by <i>prot</i>; <sup>[<a href=
|
|
"javascript:open_code('MPR')">MPR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> however, if
|
|
the Memory Protection option is supported, the implementation shall not permit a write to succeed where PROT_WRITE has not been set
|
|
or shall not permit any access where PROT_NONE alone has been set. The implementation shall support at least the following values
|
|
of <i>prot</i>: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of PROT_READ and PROT_WRITE. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"> If the Memory Protection option is not supported, the result of any access
|
|
that conflicts with the specified protection is undefined. The file descriptor <i>fildes</i> shall have been opened with read
|
|
permission, regardless of the protection options specified. If PROT_WRITE is specified, the application shall ensure that it has
|
|
opened the file descriptor <i>fildes</i> with write permission unless MAP_PRIVATE is specified in the <i>flags</i> parameter as
|
|
described below.</p>
|
|
|
|
<p>The parameter <i>flags</i> provides other information about the handling of the mapped data. The value of <i>flags</i> is the
|
|
bitwise-inclusive OR of these options, defined in <a href="../basedefs/sys/mman.h.html"><i><sys/mman.h></i></a>:</p>
|
|
|
|
<center>
|
|
<table border="1" cellpadding="3" align="center">
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b>Symbolic Constant</b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>Description</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">MAP_SHARED</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Changes are shared.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">MAP_PRIVATE</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Changes are private.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent">MAP_FIXED</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Interpret <i>addr</i> exactly.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>Implementations that do not support the Memory Mapped Files option are not required to support MAP_PRIVATE.</p>
|
|
|
|
<p>It is implementation-defined whether MAP_FIXED shall be supported. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup>
|
|
<img src="../images/opt-start.gif" alt="[Option Start]" border="0"> MAP_FIXED shall be supported on XSI-conformant systems.
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>MAP_SHARED and MAP_PRIVATE describe the disposition of write references to the memory object. If MAP_SHARED is specified, write
|
|
references shall change the underlying object. If MAP_PRIVATE is specified, modifications to the mapped data by the calling process
|
|
shall be visible only to the calling process and shall not change the underlying object. It is unspecified whether modifications to
|
|
the underlying object done after the MAP_PRIVATE mapping is established are visible through the MAP_PRIVATE mapping. Either
|
|
MAP_SHARED or MAP_PRIVATE can be specified, but not both. The mapping type is retained across <a href=
|
|
"../functions/fork.html"><i>fork</i>()</a>.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
When <i>fildes</i> represents a typed memory object opened with either the POSIX_TYPED_MEM_ALLOCATE flag or the
|
|
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, <i>mmap</i>() shall, if there are enough resources available, map <i>len</i> bytes allocated
|
|
from the corresponding typed memory object which were not previously allocated to any process in any processor that may access that
|
|
typed memory object. If there are not enough resources available, the function shall fail. If <i>fildes</i> represents a typed
|
|
memory object opened with the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these allocated bytes shall be contiguous within the typed
|
|
memory object. If <i>fildes</i> represents a typed memory object opened with the POSIX_TYPED_MEM_ALLOCATE flag, these allocated
|
|
bytes may be composed of non-contiguous fragments within the typed memory object. If <i>fildes</i> represents a typed memory object
|
|
opened with neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the POSIX_TYPED_MEM_ALLOCATE flag, <i>len</i> bytes starting at
|
|
offset <i>off</i> within the typed memory object are mapped, exactly as when mapping a file or shared memory object. In this case,
|
|
if two processes map an area of typed memory using the same <i>off</i> and <i>len</i> values and using file descriptors that refer
|
|
to the same memory pool (either from the same port or from a different port), both processes shall map the same region of storage.
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>When MAP_FIXED is set in the <i>flags</i> argument, the implementation is informed that the value of <i>pa</i> shall be
|
|
<i>addr</i>, exactly. If MAP_FIXED is set, <i>mmap</i>() may return MAP_FAILED and set <i>errno</i> to [EINVAL]. If a MAP_FIXED
|
|
request is successful, the mapping established by <i>mmap</i>() replaces any previous mappings for the process' pages in the range
|
|
[<i>pa</i>,<i>pa</i>+<i>len</i>).</p>
|
|
|
|
<p>When MAP_FIXED is not set, the implementation uses <i>addr</i> in an implementation-defined manner to arrive at <i>pa</i>. The
|
|
<i>pa</i> so chosen shall be an area of the address space that the implementation deems suitable for a mapping of <i>len</i> bytes
|
|
to the file. All implementations interpret an <i>addr</i> value of 0 as granting the implementation complete freedom in selecting
|
|
<i>pa</i>, subject to constraints described below. A non-zero value of <i>addr</i> is taken to be a suggestion of a process address
|
|
near which the mapping should be placed. When the implementation selects a value for <i>pa</i>, it never places a mapping at
|
|
address 0, nor does it replace any extant mapping.</p>
|
|
|
|
<p>The <i>off</i> argument is constrained to be aligned and sized according to the value returned by <a href=
|
|
"../functions/sysconf.html"><i>sysconf</i>()</a> when passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, the
|
|
application shall ensure that the argument <i>addr</i> also meets these constraints. The implementation performs mapping operations
|
|
over whole pages. Thus, while the argument <i>len</i> need not meet a size or alignment constraint, the implementation shall
|
|
include, in any mapping operation, any partial page specified by the range [<i>pa</i>,<i>pa</i>+<i>len</i>).</p>
|
|
|
|
<p>The system shall always zero-fill any partial page at the end of an object. Further, the system shall never write out any
|
|
modified portions of the last page of an object which are beyond its end. <sup>[<a href=
|
|
"javascript:open_code('MPR')">MPR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> References
|
|
within the address range starting at <i>pa</i> and continuing for <i>len</i> bytes to whole pages following the end of an object
|
|
shall result in delivery of a SIGBUS signal. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>An implementation may generate SIGBUS signals when a reference would cause an error in the mapped object, such as out-of-space
|
|
condition.</p>
|
|
|
|
<p>The <i>mmap</i>() function shall add an extra reference to the file associated with the file descriptor <i>fildes</i> which is
|
|
not removed by a subsequent <a href="../functions/close.html"><i>close</i>()</a> on that file descriptor. This reference shall be
|
|
removed when there are no more mappings to the file.</p>
|
|
|
|
<p>The <i>st_atime</i> field of the mapped file may be marked for update at any time between the <i>mmap</i>() call and the
|
|
corresponding <a href="../functions/munmap.html"><i>munmap</i>()</a> call. The initial read or write reference to a mapped region
|
|
shall cause the file's <i>st_atime</i> field to be marked for update if it has not already been marked for update.</p>
|
|
|
|
<p>The <i>st_ctime</i> and <i>st_mtime</i> fields of a file that is mapped with MAP_SHARED and PROT_WRITE shall be marked for
|
|
update at some point in the interval between a write reference to the mapped region and the next call to <a href=
|
|
"../functions/msync.html"><i>msync</i>()</a> with MS_ASYNC or MS_SYNC for that portion of the file by any process. If there is no
|
|
such call and if the underlying file is modified as a result of a write reference, then these fields shall be marked for update at
|
|
some time after the write reference.</p>
|
|
|
|
<p>There may be implementation-defined limits on the number of memory regions that can be mapped (per process or per system).</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If such a limit is imposed, whether the number of memory regions that can be mapped by a process is decreased by the use of <a
|
|
href="../functions/shmat.html"><i>shmat</i>()</a> is implementation-defined. <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></p>
|
|
|
|
<p>If <i>mmap</i>() fails for reasons other than [EBADF], [EINVAL], or [ENOTSUP], some of the mappings in the address range
|
|
starting at <i>addr</i> and continuing for <i>len</i> bytes may have been unmapped.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>Upon successful completion, the <i>mmap</i>() function shall return the address at which the mapping was placed ( <i>pa</i>);
|
|
otherwise, it shall return a value of MAP_FAILED and set <i>errno</i> to indicate the error. The symbol MAP_FAILED is defined in
|
|
the <a href="../basedefs/sys/mman.h.html"><i><sys/mman.h></i></a> header. No successful return from <i>mmap</i>() shall
|
|
return the value MAP_FAILED.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>mmap</i>() function shall fail if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EACCES]</dt>
|
|
|
|
<dd>The <i>fildes</i> argument is not open for read, regardless of the protection specified, or <i>fildes</i> is not open for write
|
|
and PROT_WRITE was specified for a MAP_SHARED type mapping.</dd>
|
|
|
|
<dt>[EAGAIN]</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('ML')">ML</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The mapping could not be locked in memory, if required by <a href="../functions/mlockall.html"><i>mlockall</i>()</a>, due to a lack
|
|
of resources. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt>[EBADF]</dt>
|
|
|
|
<dd>The <i>fildes</i> argument is not a valid open file descriptor.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The <i>addr</i> argument (if MAP_FIXED was specified) or <i>off</i> is not a multiple of the page size as returned by <a href=
|
|
"../functions/sysconf.html"><i>sysconf</i>()</a>, or is considered invalid by the implementation.</dd>
|
|
|
|
<dt>[EINVAL]</dt>
|
|
|
|
<dd>The value of <i>flags</i> is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).</dd>
|
|
|
|
<dt>[EMFILE]</dt>
|
|
|
|
<dd>The number of mapped regions would exceed an implementation-defined limit (per process or per system).</dd>
|
|
|
|
<dt>[ENODEV]</dt>
|
|
|
|
<dd>The <i>fildes</i> argument refers to a file whose type is not supported by <i>mmap</i>().</dd>
|
|
|
|
<dt>[ENOMEM]</dt>
|
|
|
|
<dd>MAP_FIXED was specified, and the range [<i>addr</i>,<i>addr</i>+<i>len</i>) exceeds that allowed for the address space of a
|
|
process; or, if MAP_FIXED was not specified and there is insufficient room in the address space to effect the mapping.</dd>
|
|
|
|
<dt>[ENOMEM]</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('ML')">ML</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The mapping could not be locked in memory, if required by <a href="../functions/mlockall.html"><i>mlockall</i>()</a>, because it
|
|
would require more space than the system is able to supply. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt>[ENOMEM]</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Not enough unallocated memory resources remain in the typed memory object designated by <i>fildes</i> to allocate <i>len</i> bytes.
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt>[ENOTSUP]</dt>
|
|
|
|
<dd>MAP_FIXED or MAP_PRIVATE was specified in the <i>flags</i> argument and the implementation does not support this functionality.
|
|
|
|
|
|
<p>The implementation does not support the combination of accesses requested in the <i>prot</i> argument.</p>
|
|
</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>Addresses in the range [<i>off</i>,<i>off</i>+<i>len</i>) are invalid for the object specified by <i>fildes</i>.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd>MAP_FIXED was specified in <i>flags</i> and the combination of <i>addr</i>, <i>len</i>, and <i>off</i> is invalid for the
|
|
object specified by <i>fildes</i>.</dd>
|
|
|
|
<dt>[ENXIO]</dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
The <i>fildes</i> argument refers to a typed memory object that is not accessible from the calling process. <img src=
|
|
"../images/opt-end.gif" alt="[Option End]" border="0"></dd>
|
|
|
|
<dt>[EOVERFLOW]</dt>
|
|
|
|
<dd>The file is a regular file and the value of <i>off</i> plus <i>len</i> exceeds the offset maximum established in the open file
|
|
description associated with <i>fildes</i>.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_379_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>Use of <i>mmap</i>() may reduce the amount of memory available to other memory allocation functions.</p>
|
|
|
|
<p>Use of MAP_FIXED may result in unspecified behavior in further use of <a href="../functions/malloc.html"><i>malloc</i>()</a> and
|
|
<a href="../functions/shmat.html"><i>shmat</i>()</a>. The use of MAP_FIXED is discouraged, as it may prevent an implementation from
|
|
making the most effective use of resources.</p>
|
|
|
|
<p>The application must ensure correct synchronization when using <i>mmap</i>() in conjunction with any other file access method,
|
|
such as <a href="../functions/read.html"><i>read</i>()</a> and <a href="../functions/write.html"><i>write</i>()</a>, standard
|
|
input/output, and <a href="../functions/shmat.html"><i>shmat</i>()</a>.</p>
|
|
|
|
<p>The <i>mmap</i>() function allows access to resources via address space manipulations, instead of <a href=
|
|
"../functions/read.html"><i>read</i>()</a>/ <a href="../functions/write.html"><i>write</i>()</a>. Once a file is mapped, all a
|
|
process has to do to access it is use the data at the address to which the file was mapped. So, using pseudo-code to illustrate the
|
|
way in which an existing program might be changed to use <i>mmap</i>(), the following:</p>
|
|
|
|
<pre>
|
|
<tt>fildes = open(...)
|
|
lseek(fildes, some_offset)
|
|
read(fildes, buf, len)
|
|
/* Use data in buf. */
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>becomes:</p>
|
|
|
|
<pre>
|
|
<tt>fildes = open(...)
|
|
address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
|
|
/* Use data at address. */
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>After considering several other alternatives, it was decided to adopt the <i>mmap</i>() definition found in SVR4 for mapping
|
|
memory objects into process address spaces. The SVR4 definition is minimal, in that it describes only what has been built, and what
|
|
appears to be necessary for a general and portable mapping facility.</p>
|
|
|
|
<p>Note that while <i>mmap</i>() was first designed for mapping files, it is actually a general-purpose mapping facility. It can be
|
|
used to map any appropriate object, such as memory, files, devices, and so on, into the address space of a process.</p>
|
|
|
|
<p>When a mapping is established, it is possible that the implementation may need to map more than is requested into the address
|
|
space of the process because of hardware requirements. An application, however, cannot count on this behavior. Implementations that
|
|
do not use a paged architecture may simply allocate a common memory region and return the address of it; such implementations
|
|
probably do not allocate any more than is necessary. References past the end of the requested area are unspecified.</p>
|
|
|
|
<p>If an application requests a mapping that would overlay existing mappings in the process, it might be desirable that an
|
|
implementation detect this and inform the application. However, the default, portable (not MAP_FIXED) operation does not overlay
|
|
existing mappings. On the other hand, if the program specifies a fixed address mapping (which requires some implementation
|
|
knowledge to determine a suitable address, if the function is supported at all), then the program is presumed to be successfully
|
|
managing its own address space and should be trusted when it asks to map over existing data structures. Furthermore, it is also
|
|
desirable to make as few system calls as possible, and it might be considered onerous to require an <a href=
|
|
"../functions/munmap.html"><i>munmap</i>()</a> before an <i>mmap</i>() to the same address range. This volume of
|
|
IEEE Std 1003.1-2001 specifies that the new mappings replace any existing mappings, following existing practice in this
|
|
regard.</p>
|
|
|
|
<p>It is not expected, when the Memory Protection option is supported, that all hardware implementations are able to support all
|
|
combinations of permissions at all addresses. When this option is supported, implementations are required to disallow write access
|
|
to mappings without write permission and to disallow access to mappings without any access permission. Other than these
|
|
restrictions, implementations may allow access types other than those requested by the application. For example, if the application
|
|
requests only PROT_WRITE, the implementation may also allow read access. A call to <i>mmap</i>() fails if the implementation cannot
|
|
support allowing all the access requested by the application. For example, some implementations cannot support a request for both
|
|
write access and execute access simultaneously. All implementations supporting the Memory Protection option must support requests
|
|
for no access, read access, write access, and both read and write access. Strictly conforming code must only rely on the required
|
|
checks. These restrictions allow for portability across a wide range of hardware.</p>
|
|
|
|
<p>The MAP_FIXED address treatment is likely to fail for non-page-aligned values and for certain architecture-dependent address
|
|
ranges. Conforming implementations cannot count on being able to choose address values for MAP_FIXED without utilizing
|
|
non-portable, implementation-defined knowledge. Nonetheless, MAP_FIXED is provided as a standard interface conforming to existing
|
|
practice for utilizing such knowledge when it is available.</p>
|
|
|
|
<p>Similarly, in order to allow implementations that do not support virtual addresses, support for directly specifying any mapping
|
|
addresses via MAP_FIXED is not required and thus a conforming application may not count on it.</p>
|
|
|
|
<p>The MAP_PRIVATE function can be implemented efficiently when memory protection hardware is available. When such hardware is not
|
|
available, implementations can implement such "mappings" by simply making a real copy of the relevant data into process private
|
|
memory, though this tends to behave similarly to <a href="../functions/read.html"><i>read</i>()</a>.</p>
|
|
|
|
<p>The function has been defined to allow for many different models of using shared memory. However, all uses are not equally
|
|
portable across all machine architectures. In particular, the <i>mmap</i>() function allows the system as well as the application
|
|
to specify the address at which to map a specific region of a memory object. The most portable way to use the function is always to
|
|
let the system choose the address, specifying NULL as the value for the argument <i>addr</i> and not to specify MAP_FIXED.</p>
|
|
|
|
<p>If it is intended that a particular region of a memory object be mapped at the same address in a group of processes (on machines
|
|
where this is even possible), then MAP_FIXED can be used to pass in the desired mapping address. The system can still be used to
|
|
choose the desired address if the first such mapping is made without specifying MAP_FIXED, and then the resulting mapping address
|
|
can be passed to subsequent processes for them to pass in via MAP_FIXED. The availability of a specific address range cannot be
|
|
guaranteed, in general.</p>
|
|
|
|
<p>The <i>mmap</i>() function can be used to map a region of memory that is larger than the current size of the object. Memory
|
|
access within the mapping but beyond the current end of the underlying objects may result in SIGBUS signals being sent to the
|
|
process. The reason for this is that the size of the object can be manipulated by other processes and can change at any moment. The
|
|
implementation should tell the application that a memory reference is outside the object where this can be detected; otherwise,
|
|
written data may be lost and read data may not reflect actual data in the object.</p>
|
|
|
|
<p>Note that references beyond the end of the object do not extend the object as the new end cannot be determined precisely by most
|
|
virtual memory hardware. Instead, the size can be directly manipulated by <a href=
|
|
"../functions/ftruncate.html"><i>ftruncate</i>()</a>.</p>
|
|
|
|
<p>Process memory locking does apply to shared memory regions, and the MEMLOCK_FUTURE argument to <a href=
|
|
"../functions/mlockall.html"><i>mlockall</i>()</a> can be relied upon to cause new shared memory regions to be automatically
|
|
locked.</p>
|
|
|
|
<p>Existing implementations of <i>mmap</i>() return the value -1 when unsuccessful. Since the casting of this value to type <b>void
|
|
*</b> cannot be guaranteed by the ISO C standard to be distinct from a successful value, this volume of
|
|
IEEE Std 1003.1-2001 defines the symbol MAP_FAILED, which a conforming implementation does not return as the result of a
|
|
successful call.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="exec.html"><i><a href="../functions/exec.html">exec</a></i>()</a> , <a href="fcntl.html"><i>fcntl</i>()</a> , <a href=
|
|
"fork.html"><i>fork</i>()</a> , <a href="lockf.html"><i>lockf</i>()</a> , <a href="msync.html"><i>msync</i>()</a> , <a href=
|
|
"munmap.html"><i>munmap</i>()</a> , <a href="mprotect.html"><i>mprotect</i>()</a> , <a href=
|
|
"posix_typed_mem_open.html"><i>posix_typed_mem_open</i>()</a> , <a href="shmat.html"><i>shmat</i>()</a> , <a href=
|
|
"sysconf.html"><i>sysconf</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/sys/mman.h.html"><i><sys/mman.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4, Version 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Moved from X/OPEN UNIX extension to BASE.</p>
|
|
|
|
<p>Aligned with <i>mmap</i>() in the POSIX Realtime Extension as follows:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The DESCRIPTION is extensively reworded.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The [EAGAIN] and [ENOTSUP] mandatory error conditions are added.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>New cases of [ENOMEM] and [ENXIO] are added as mandatory error conditions.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The value returned on failure is the value of the constant MAP_FAILED; this was previously defined as -1.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Large File Summit extensions are added.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_379_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>mmap</i>() function is marked as part of the Memory Mapped Files option.</p>
|
|
|
|
<p>The Open Group Corrigendum U028/6 is applied, changing (<b>void</b> *)-1 to MAP_FAILED.</p>
|
|
|
|
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The DESCRIPTION is updated to described the use of MAP_FIXED.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The DESCRIPTION is updated to describe the addition of an extra reference to the file associated with the file descriptor passed
|
|
to <i>mmap</i>().</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The DESCRIPTION is updated to state that there may be implementation-defined limits on the number of memory regions that can be
|
|
mapped.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The DESCRIPTION is updated to describe constraints on the alignment and size of the <i>off</i> argument.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The [EINVAL] and [EMFILE] error conditions are added.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The [EOVERFLOW] error condition is added. This change is to support large files.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The following changes are made for alignment with the ISO POSIX-1:1996 standard:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The DESCRIPTION is updated to describe the cases when MAP_PRIVATE and MAP_FIXED need not be supported.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The following changes are made for alignment with IEEE Std 1003.1j-2000:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Semantics for typed memory objects are added to the DESCRIPTION.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>New [ENOMEM] and [ENXIO] errors are added to the ERRORS section.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The <a href="../functions/posix_typed_mem_open.html"><i>posix_typed_mem_open</i>()</a> function is added to the SEE ALSO
|
|
section.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|