mmap.html

posix标准英文,html格式

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"> &nbsp;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>&lt;sys/mman.h&gt;</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 value of <i>len</i> is zero.</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>