diff options
Diffstat (limited to 'man3p/mmap.3p')
| -rw-r--r-- | man3p/mmap.3p | 510 |
1 files changed, 510 insertions, 0 deletions
diff --git a/man3p/mmap.3p b/man3p/mmap.3p new file mode 100644 index 000000000..2a60ea937 --- /dev/null +++ b/man3p/mmap.3p @@ -0,0 +1,510 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MMAP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mmap +.SH NAME +mmap \- map pages of memory +.SH SYNOPSIS +.LP +\fB#include <sys/mman.h> +.br +.sp +void *mmap(void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB, int\fP +\fIprot\fP\fB, int\fP \fIflags\fP\fB, +.br +\ \ \ \ \ \ int\fP \fIfildes\fP\fB, off_t\fP \fIoff\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImmap\fP() function shall establish a mapping between a process' +address space and a file, shared memory object, or +\ typed memory object. The format of the call is as +follows: +.sp +.RS +.nf + +\fIpa\fP\fB=\fP\fImmap\fP\fB(\fP\fIaddr\fP\fB,\fP \fIlen\fP\fB,\fP \fIprot\fP\fB,\fP \fIflags\fP\fB,\fP \fIfildes\fP\fB,\fP \fIoff\fP\fB); +\fP +.fi +.RE +.LP +The \fImmap\fP() function shall establish a mapping between the address +space of the process at an address \fIpa\fP for +\fIlen\fP bytes to the memory object represented by the file descriptor +\fIfildes\fP at offset \fIoff\fP for \fIlen\fP bytes. +The value of \fIpa\fP is an implementation-defined function of the +parameter \fIaddr\fP and the values of \fIflags\fP, further +described below. A successful \fImmap\fP() call shall return \fIpa\fP +as its result. The address range starting at \fIpa\fP and +continuing for \fIlen\fP bytes shall be legitimate for the possible +(not necessarily current) address space of the process. The +range of bytes starting at \fIoff\fP and continuing for \fIlen\fP +bytes shall be legitimate for the possible (not necessarily +current) offsets in the file, shared memory object, or \ typed memory +object \ represented by \fIfildes\fP. +.LP +If \fIfildes\fP 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 \fIoff\fP +is non-zero, the behavior of \fImmap\fP() is undefined. If +\fIfildes\fP refers to a valid typed memory object that is not accessible +from the calling process, \fImmap\fP() shall fail. +.LP +The mapping established by \fImmap\fP() shall replace any previous +mappings for those whole pages containing any part of the +address space of the process starting at \fIpa\fP and continuing for +\fIlen\fP bytes. +.LP +If the size of the mapped file changes after the call to \fImmap\fP() +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. +.LP +The \fImmap\fP() function shall be supported for regular files, shared +memory objects, and \ typed memory +objects. Support for any other type of file is unspecified. +.LP +The parameter \fIprot\fP determines whether read, write, execute, +or some combination of accesses are permitted to the data +being mapped. The \fIprot\fP 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 \fI<sys/mman.h>\fP header. +.TS C +center; l l. +\fBSymbolic Constant\fP \fBDescription\fP +PROT_READ Data can be read. +PROT_WRITE Data can be written. +PROT_EXEC Data can be executed. +PROT_NONE Data cannot be accessed. +.TE +.LP +If an implementation cannot support the combination of access types +specified by \fIprot\fP, the call to \fImmap\fP() shall +fail. +.LP +An implementation may permit accesses other than those specified by +\fIprot\fP; \ 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 \fIprot\fP: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive +OR of PROT_READ and PROT_WRITE. If the Memory Protection option is +not supported, the result of any access +that conflicts with the specified protection is undefined. The file +descriptor \fIfildes\fP 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 \fIfildes\fP with write permission unless +MAP_PRIVATE is specified in the \fIflags\fP parameter as +described below. +.LP +The parameter \fIflags\fP provides other information about the handling +of the mapped data. The value of \fIflags\fP is the +bitwise-inclusive OR of these options, defined in \fI<sys/mman.h>\fP: +.TS C +center; l l. +\fBSymbolic Constant\fP \fBDescription\fP +MAP_SHARED Changes are shared. +MAP_PRIVATE Changes are private. +MAP_FIXED Interpret \fIaddr\fP exactly. +.TE +.LP +Implementations that do not support the Memory Mapped Files option +are not required to support MAP_PRIVATE. +.LP +It is implementation-defined whether MAP_FIXED shall be supported. +\ MAP_FIXED shall be supported on XSI-conformant systems. +.LP +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 \fIfork\fP(). +.LP +When \fIfildes\fP represents a typed memory object opened with either +the POSIX_TYPED_MEM_ALLOCATE flag or the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, \fImmap\fP() shall, if there +are enough resources available, map \fIlen\fP 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 \fIfildes\fP 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 \fIfildes\fP 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 \fIfildes\fP represents a typed memory object +opened with neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the +POSIX_TYPED_MEM_ALLOCATE flag, \fIlen\fP bytes starting at +offset \fIoff\fP 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 \fIoff\fP +and \fIlen\fP 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. +.LP +When MAP_FIXED is set in the \fIflags\fP argument, the implementation +is informed that the value of \fIpa\fP shall be +\fIaddr\fP, exactly. If MAP_FIXED is set, \fImmap\fP() may return +MAP_FAILED and set \fIerrno\fP to [EINVAL]. If a MAP_FIXED +request is successful, the mapping established by \fImmap\fP() replaces +any previous mappings for the process' pages in the range +[\fIpa\fP,\fIpa\fP+\fIlen\fP). +.LP +When MAP_FIXED is not set, the implementation uses \fIaddr\fP in an +implementation-defined manner to arrive at \fIpa\fP. The +\fIpa\fP so chosen shall be an area of the address space that the +implementation deems suitable for a mapping of \fIlen\fP bytes +to the file. All implementations interpret an \fIaddr\fP value of +0 as granting the implementation complete freedom in selecting +\fIpa\fP, subject to constraints described below. A non-zero value +of \fIaddr\fP is taken to be a suggestion of a process address +near which the mapping should be placed. When the implementation selects +a value for \fIpa\fP, it never places a mapping at +address 0, nor does it replace any extant mapping. +.LP +The \fIoff\fP argument is constrained to be aligned and sized according +to the value returned by \fIsysconf\fP() when passed _SC_PAGESIZE +or _SC_PAGE_SIZE. When MAP_FIXED is specified, the +application shall ensure that the argument \fIaddr\fP also meets these +constraints. The implementation performs mapping operations +over whole pages. Thus, while the argument \fIlen\fP need not meet +a size or alignment constraint, the implementation shall +include, in any mapping operation, any partial page specified by the +range [\fIpa\fP,\fIpa\fP+\fIlen\fP). +.LP +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. \ References +within the address range starting at \fIpa\fP and continuing for \fIlen\fP +bytes to whole pages following the end of an object +shall result in delivery of a SIGBUS signal. +.LP +An implementation may generate SIGBUS signals when a reference would +cause an error in the mapped object, such as out-of-space +condition. +.LP +The \fImmap\fP() function shall add an extra reference to the file +associated with the file descriptor \fIfildes\fP which is +not removed by a subsequent \fIclose\fP() on that file descriptor. +This reference shall be +removed when there are no more mappings to the file. +.LP +The \fIst_atime\fP field of the mapped file may be marked for update +at any time between the \fImmap\fP() call and the +corresponding \fImunmap\fP() call. The initial read or write reference +to a mapped region +shall cause the file's \fIst_atime\fP field to be marked for update +if it has not already been marked for update. +.LP +The \fIst_ctime\fP and \fIst_mtime\fP 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 \fImsync\fP() 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. +.LP +There may be implementation-defined limits on the number of memory +regions that can be mapped (per process or per system). +.LP +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 \fIshmat\fP() +is implementation-defined. +.LP +If \fImmap\fP() fails for reasons other than [EBADF], [EINVAL], or +[ENOTSUP], some of the mappings in the address range +starting at \fIaddr\fP and continuing for \fIlen\fP bytes may have +been unmapped. +.SH RETURN VALUE +.LP +Upon successful completion, the \fImmap\fP() function shall return +the address at which the mapping was placed ( \fIpa\fP); +otherwise, it shall return a value of MAP_FAILED and set \fIerrno\fP +to indicate the error. The symbol MAP_FAILED is defined in +the \fI<sys/mman.h>\fP header. No successful return from \fImmap\fP() +shall +return the value MAP_FAILED. +.SH ERRORS +.LP +The \fImmap\fP() function shall fail if: +.TP 7 +.B EACCES +The \fIfildes\fP argument is not open for read, regardless of the +protection specified, or \fIfildes\fP is not open for write +and PROT_WRITE was specified for a MAP_SHARED type mapping. +.TP 7 +.B EAGAIN +The mapping could not be locked in memory, if required by \fImlockall\fP(), +due to a lack +of resources. +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid open file descriptor. +.TP 7 +.B EINVAL +The \fIaddr\fP argument (if MAP_FIXED was specified) or \fIoff\fP +is not a multiple of the page size as returned by \fIsysconf\fP(), +or is considered invalid by the implementation. +.TP 7 +.B EINVAL +The value of \fIflags\fP is invalid (neither MAP_PRIVATE nor MAP_SHARED +is set). +.TP 7 +.B EMFILE +The number of mapped regions would exceed an implementation-defined +limit (per process or per system). +.TP 7 +.B ENODEV +The \fIfildes\fP argument refers to a file whose type is not supported +by \fImmap\fP(). +.TP 7 +.B ENOMEM +MAP_FIXED was specified, and the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fP) +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. +.TP 7 +.B ENOMEM +The mapping could not be locked in memory, if required by \fImlockall\fP(), +because it +would require more space than the system is able to supply. +.TP 7 +.B ENOMEM +Not enough unallocated memory resources remain in the typed memory +object designated by \fIfildes\fP to allocate \fIlen\fP bytes. +.TP 7 +.B ENOTSUP +MAP_FIXED or MAP_PRIVATE was specified in the \fIflags\fP argument +and the implementation does not support this functionality. +.LP +The implementation does not support the combination of accesses requested +in the \fIprot\fP argument. +.TP 7 +.B ENXIO +Addresses in the range [\fIoff\fP,\fIoff\fP+\fIlen\fP) are invalid +for the object specified by \fIfildes\fP. +.TP 7 +.B ENXIO +MAP_FIXED was specified in \fIflags\fP and the combination of \fIaddr\fP, +\fIlen\fP, and \fIoff\fP is invalid for the +object specified by \fIfildes\fP. +.TP 7 +.B ENXIO +The \fIfildes\fP argument refers to a typed memory object that is +not accessible from the calling process. +.TP 7 +.B EOVERFLOW +The file is a regular file and the value of \fIoff\fP plus \fIlen\fP +exceeds the offset maximum established in the open file +description associated with \fIfildes\fP. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +Use of \fImmap\fP() may reduce the amount of memory available to other +memory allocation functions. +.LP +Use of MAP_FIXED may result in unspecified behavior in further use +of \fImalloc\fP() and +\fIshmat\fP(). The use of MAP_FIXED is discouraged, as it may prevent +an implementation from +making the most effective use of resources. +.LP +The application must ensure correct synchronization when using \fImmap\fP() +in conjunction with any other file access method, +such as \fIread\fP() and \fIwrite\fP(), standard +input/output, and \fIshmat\fP(). +.LP +The \fImmap\fP() function allows access to resources via address space +manipulations, instead of \fIread\fP()/ \fIwrite\fP(). 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 \fImmap\fP(), +the following: +.sp +.RS +.nf + +\fBfildes = open(...) +lseek(fildes, some_offset) +read(fildes, buf, len) +/* Use data in buf. */ +\fP +.fi +.RE +.LP +becomes: +.sp +.RS +.nf + +\fBfildes = open(...) +address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) +/* Use data at address. */ +\fP +.fi +.RE +.SH RATIONALE +.LP +After considering several other alternatives, it was decided to adopt +the \fImmap\fP() 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. +.LP +Note that while \fImmap\fP() 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. +.LP +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. +.LP +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 \fImunmap\fP() before an \fImmap\fP() +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. +.LP +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 \fImmap\fP() 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. +.LP +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. +.LP +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. +.LP +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 \fIread\fP(). +.LP +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 \fImmap\fP() +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 \fIaddr\fP and not to specify MAP_FIXED. +.LP +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. +.LP +The \fImmap\fP() 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. +.LP +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 \fIftruncate\fP(). +.LP +Process memory locking does apply to shared memory regions, and the +MEMLOCK_FUTURE argument to \fImlockall\fP() can be relied upon to +cause new shared memory regions to be automatically +locked. +.LP +Existing implementations of \fImmap\fP() return the value -1 when +unsuccessful. Since the casting of this value to type \fBvoid +*\fP 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. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIexec\fP() , \fIfcntl\fP() , \fIfork\fP() , \fIlockf\fP() , \fImsync\fP() +, \fImunmap\fP() , \fImprotect\fP() , \fIposix_typed_mem_open\fP() +, \fIshmat\fP() , \fIsysconf\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI<sys/mman.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |