📄 mmap.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><!-- Copyright 1997 The Open Group, All Rights Reserved --><title>mmap</title></head><body bgcolor=white><center><font size=2>The Single UNIX ® Specification, Version 2<br>Copyright © 1997 The Open Group</font></center><hr size=2 noshade><h4><a name = "tag_000_007_694"> </a>NAME</h4><blockquote>mmap - map pages of memory</blockquote><h4><a name = "tag_000_007_695"> </a>SYNOPSIS</h4><blockquote><pre><code>#include <<a href="sysmman.h.html">sys/mman.h</a>>void *mmap(void *<i>addr</i>, size_t <i>len</i>, int <i>prot</i>, int <i>flags</i>, int <i>fildes</i>, off_t <i>off</i>);</code></pre></blockquote><h4><a name = "tag_000_007_696"> </a>DESCRIPTION</h4><blockquote>The<i>mmap()</i>function establishes a mapping between a process' address space and a fileor shared memory object.The format of the call is as follows:<pre><code><i>pa</i>=<i>mmap</i>(<i>addr</i>, <i>len</i>, <i>prot</i>, <i>flags</i>, <i>fildes</i>, <i>off</i>);</code></pre><p>The<i>mmap()</i>function establishes a mapping between the address space of the processat 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-dependent function of the parameter<i>addr</i>and the values of<i>flags</i>,further described below.A successful<i>mmap()</i>call returns<i>pa</i>as its result.The address range starting at<i>pa</i>and continuing for<i>len</i>bytes will 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 will be legitimate for the possible (not necessarily current)offsets in the file or shared memory objectrepresented by<i>fildes</i>.<p>The mapping established by<i>mmap()</i>replaces any previous mappings forthose whole pages containing any part of theaddress space of the process starting at<i>pa</i>and continuing for<i>len</i>bytes.<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 toadded or removed portions of the file is unspecified.<p>The<i>mmap()</i>function is supported for regular filesand shared memory objects.Support for any other type of file is unspecified.<p>The parameter<i>prot</i>determines whether read, write, execute, or some combination ofaccesses are permitted to the data being mapped.The<i>prot</i>should be either PROT_NONEor the bitwise inclusive OR of one or more of the other flags inthe following table,defined in the header<i><a href="sysmman.h.html"><sys/mman.h></a></i>.<p><table bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Symbolic Constant</b><th align=center><b>Description</b><tr valign=top><td align=left>PROT_READ<td align=left>Data can be read.<tr valign=top><td align=left>PROT_WRITE<td align=left>Data can be written.<tr valign=top><td align=left>PROT_EXEC<td align=left>Data can be executed.<tr valign=top><td align=left>PROT_NONE<td align=left>Data cannot be accessed.</table><p>If an implementation cannot support the combination of access typesspecified by<i>prot</i>,the call to<i>mmap()</i>fails.An implementation may permit accesses other than those specified by<i>prot</i>;however,the implementation will not permit a write to succeed wherePROT_WRITE has not been set or permit any access wherePROT_NONE alone has been set.The implementation will support at least the following values of<i>prot</i>:PROT_NONE, PROT_READ, PROT_WRITE, and the inclusive OR ofPROT_READ and PROT_WRITE.The file descriptor<i>fildes</i>will have been opened with read permission,regardless of the protection options specified.If PROT_WRITE is specified, the application must have 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>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<i><a href="sysmman.h.html"><sys/mman.h></a></i>:<p><table bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Symbolic Constant</b><th align=center><b>Description</b><tr valign=top><td align=left>MAP_SHARED<td align=left>Changes are shared.<tr valign=top><td align=left>MAP_PRIVATE<td align=left>Changes are private.<tr valign=top><td align=left>MAP_FIXED<td align=left>Interpret <i>addr</i> exactly.</table><p>MAP_SHARED and MAP_PRIVATE describe the dispositionof write references to the memory object.If MAP_SHARED is specified, write references change the underlying object.If MAP_PRIVATE is specified, modifications to the mapped data by thecalling process will be visible only to the calling processand will not change the underlying object.It is unspecified whether modificationsto the underlying object done after the MAP_PRIVATEmapping 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<i><a href="fork.html">fork()</a></i>.<p>When MAP_FIXED is set in the <i>flags</i> argument, the implementation isinformed that the value of <i>pa</i> must be<i>addr</i>,exactly.If MAP_FIXED is set,<i>mmap()</i>may return MAP_FAILED and set errno to [EINVAL]. If a MAP_FIXEDrequest is successful, the mapping established by<i>mmap()</i>replaces any previous mappings for the process' pages in the range[<i>pa, pa + len</i>).<p>When MAP_FIXED is not set, the implementation uses <i>addr</i> in anunspecified manner to arrive at<i>pa</i>.The <i>pa</i> so chosen will be an area of the address space that theimplementation deems suitable for a mapping of <i>len</i> bytes to thefile. All implementations interpret an <i>addr</i> value of 0as granting the implementation complete freedom in selecting<i>pa</i>,subject to constraints described below. A non-zero value of <i>addr</i> istaken to be a suggestion of a process address near which the mapping should beplaced. When the implementation selects a value for<i>pa</i>,it never places a mapping at address 0, nor does it replace any extantmapping.<p>The <i>off</i> argument is constrained to be aligned and sized according to thevalue returned by<i><a href="sysconf.html">sysconf()</a></i>when passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, theargument <i>addr</i> must also meet these constraints. The implementationperforms mapping operations over whole pages. Thus, while the argument<i>len</i> need not meet a size or alignment constraint, the implementationwill include, in any mapping operation, any partial page specified by therange [<i>pa, pa + len</i>).<p>The system always zero-fills any partial page at the end of an object.Further, the system never writes out any modified portionsof the last page of an object that are beyond its end.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 objectresult in delivery of a SIGBUS signal.<p>An implementation may deliver SIGBUSsignals when a reference would cause an error in the mapped object,such as out-of-space condition.<p>The<i>mmap()</i>function adds an extra reference to the file associated with the filedescriptor <i>fildes</i> which is not removed by a subsequent<i><a href="close.html">close()</a></i>on that file descriptor. This reference is removed when there are no moremappings to the file.<p>The<b>st_atime</b>field of the mapped file may be marked for update at anytime between the<i>mmap()</i>call and the corresponding<i><a href="munmap.html">munmap()</a></i>call. The initial read or write reference to a mapped region will cause thefile's<b>st_atime</b>field to be marked for update if it has not already been marked for update.<p>The<b>st_ctime</b>and<b>st_mtime</b>fields of a file that is mapped with MAP_SHARED and PROT_WRITE, will be markedfor update at some point in the interval between a write reference to themapped region and the next call to<i><a href="msync.html">msync()</a></i>with MS_ASYNC or MS_SYNC for that portion of the file by any process. Ifthere is no such call, these fields may be marked for update at any time aftera write reference if the underlying file is modified as a result.<p>There may be implementation-dependent limits on the number of memory regionsthat can be mapped (per process or per system). If such a limit is imposed,whether the number of memory regions that can be mapped by a process isdecreased by the use of<i><a href="shmat.html">shmat()</a></i>is implementation-dependent.</blockquote><h4><a name = "tag_000_007_697"> </a>RETURN VALUE</h4><blockquote>Upon successful completion, the<i>mmap()</i>function returns the address at which the mapping was placed (pa);otherwise, it returns a value of MAP_FAILED and sets<i>errno</i>to indicate the error.The symbol MAP_FAILEDis defined in the header<i><a href="sysmman.h.html"><sys/mman.h></a></i>.No successful return from<i>mmap()</i>will return the value MAP_FAILED.<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.</blockquote><h4><a name = "tag_000_007_698"> </a>ERRORS</h4><blockquote>The<i>mmap()</i>function will fail if:<dl compact><dt>[EACCES]<dd>The <i>fildes</i> argument is not open for read, regardless of the protectionspecified, or <i>fildes</i> is not open for write and PROT_WRITE was specifiedfor a MAP_SHARED type mapping.<dt>[EAGAIN]<dd>The mapping could not be locked in memory, if required by<i><a href="mlockall.html">mlockall()</a></i>,due to a lack of resources.<dt>[EBADF]<dd>The <i>fildes</i> argument is not a valid open file descriptor.<dt>[EINVAL]<dd>The <i>addr</i> argument (if MAP_FIXED was specified) or <i>off</i> is nota multiple of the page size as returned by<i><a href="sysconf.html">sysconf()</a></i>,or are considered invalid by the implementation.<dt>[EINVAL]<dd>The value of <i>flags</i> is invalid (neither MAP_PRIVATE nor MAP_SHARED isset).<dt>[EMFILE]<dd>The number of mapped regions would exceed animplementation-dependent limit (per process or per system).<dt>[ENODEV]<dd>The <i>fildes</i> argument refers to a file whose type is not supported by<i>mmap()</i>.<dt>[ENOMEM]<dd>MAP_FIXED was specified, and the range [<i>addr, addr + len</i>) exceeds thatallowed for the address space of a process; or if MAP_FIXED was notspecified and there is insufficient room in the address space to effect themapping.<dt>[ENOMEM]<dd>The mapping could not be locked in memory, if required by<i><a href="mlockall.html">mlockall()</a></i>,because it would require more space than the system is able to supply.<dt>[ENOTSUP]<dd>The implementation does not support the combination of accessesrequested in the<i>prot</i>argument.<dt>[ENXIO]<dd>Addresses in the range [<i>off, off + len</i>) are invalid forthe object specified by <i>fildes</i>.<dt>[ENXIO]<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>.<dt>[EOVERFLOW]<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>.</dl></blockquote><h4><a name = "tag_000_007_699"> </a>EXAMPLES</h4><blockquote>None.</blockquote><h4><a name = "tag_000_007_700"> </a>APPLICATION USAGE</h4><blockquote>Use of<i>mmap()</i>may reduce the amount of memory available to other memory allocationfunctions.<p>Use of MAP_FIXED may result in unspecified behaviour infurther use of<i><a href="brk.html">brk()</a></i>,<i><a href="sbrk.html">sbrk()</a></i>,<i><a href="malloc.html">malloc()</a></i>and<i><a href="shmat.html">shmat()</a></i>.The use of MAP_FIXED is discouraged, as it may prevent an implementation frommaking the most effective use of resources.<p>The application must ensure correct synchronisation when using<i>mmap()</i>in conjunction with any other file access method, such as<i><a href="read.html">read()</a></i>and<i><a href="write.html">write()</a></i>,standard input/output, and<i><a href="shmat.html">shmat()</a></i>.<p>The<i>mmap()</i>function allows access to resources via address spacemanipulations, instead ofread()/write().Once a file is mapped, all a process has to do to access it is usethe data at the address to which the file was mapped. So, using pseudo-codeto illustrate the way in which an existing program might be changed to use<i>mmap()</i>,the following:<pre><code>fildes = open(...)lseek(fildes, some_offset)read(fildes, buf, len)/* use data in buf */</code></pre>becomes:<pre><code>fildes = open(...)address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)/* use data at address */</code></pre><p>The [EINVAL] error above is marked EX because it is defined as anoptional error in the POSIX Realtime Extension.</blockquote><h4><a name = "tag_000_007_701"> </a>FUTURE DIRECTIONS</h4><blockquote>None.</blockquote><h4><a name = "tag_000_007_702"> </a>SEE ALSO</h4><blockquote><i><a href="brk.html">brk()</a></i>,<i><a href="exec.html">exec</a></i>,<i><a href="fcntl.html">fcntl()</a></i>,<i><a href="fork.html">fork()</a></i>,<i><a href="lockf.html">lockf()</a></i>,<i><a href="msync.html">msync()</a></i>,<i><a href="munmap.html">munmap()</a></i>,<i><a href="mprotect.html">mprotect()</a></i>,<i><a href="sbrk.html">sbrk()</a></i>,<i><a href="shmat.html">shmat()</a></i>,<i><a href="sysconf.html">sysconf()</a></i>,<i><a href="sysmman.h.html"><sys/mman.h></a></i>.</blockquote><hr size=2 noshade><center><font size=2>UNIX ® is a registered Trademark of The Open Group.<br>Copyright © 1997 The Open Group<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]</font></center><hr size=2 noshade></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -