MMAP(2) System Calls MMAP(2) NNAAMMEE mmap - map pages of memory SSYYNNOOPPSSIISS #include vvooiidd **mmmmaapp(vvooiidd **_a_d_d_r, ssiizzee__tt _l_e_n, iinntt _p_r_o_t, iinntt _f_l_a_g_s, iinntt _f_i_l_d_e_s, ooffff__tt _o_f_f); DDEESSCCRRIIPPTTIIOONN The mmmmaapp(()) function establishes a mapping between a process's address space and a file or shared memory object. The format of the call is as follows: _p_a = mmmmaapp((_a_d_d_r,, _l_e_n,, _p_r_o_t,, _f_l_a_g_s,, _f_i_l_d_e_s,, _o_f_f));; The mmmmaapp(()) function establishes a mapping between the address space of the process at an address _p_a for _l_e_n bytes to the memory object represented by the file descriptor _f_i_l_d_e_s at offset _o_f_f for _l_e_n bytes. The value of _p_a is a function of the _a_d_d_r argument and values of _f_l_a_g_s, further described below. A successful mmmmaapp(()) call returns _p_a as its result. The address range starting at _p_a and continuing for _l_e_n bytes will be legitimate for the possible (not necessarily current) address space of the process. The range of bytes starting at _o_f_f and continuing for _l_e_n bytes will be legitimate for the possible (not necessarily current) offsets in the file or shared memory object represented by _f_i_l_d_e_s. The mmmmaapp(()) function allows [_p_a_, _p_a _+ _l_e_n) to extend beyond the end of the object both at the time of the mmmmaapp(()) and while the mapping persists, such as when the file is created prior to the mmmmaapp(()) call and has no contents, or when the file is truncated. Any reference to addresses beyond the end of the object, however, will result in the delivery of a SSIIGGBBUUSS or SSIIGGSSEEGGVV signal. The mmmmaapp(()) function cannot be used to implicitly extend the length of files. The mapping established by mmmmaapp(()) replaces any previous mappings for those whole pages containing any part of the address space of the process starting at _p_a and continuing for _l_e_n bytes. If the size of the mapped file changes after the call to mmmmaapp(()) 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. The mmmmaapp(()) function is supported for regular files and shared memory objects. Support for any other type of file is unspecified. The _p_r_o_t argument determines whether read, write, execute, or some combination of accesses are permitted to the data being mapped. The _p_r_o_t argument should be either PPRROOTT__NNOONNEE or the bitwise inclusive OORR of one or more of the other flags in the following table, defined in the header . PPRROOTT__RREEAADD Data can be read. PPRROOTT__WWRRIITTEE Data can be written. PPRROOTT__EEXXEECC Data can be executed. PPRROOTT__NNOONNEE Data cannot be accessed. If an implementation of mmmmaapp(()) for a specific platform cannot support the combination of access types specified by _p_r_o_t, the call to mmmmaapp(()) fails. An implementation may permit accesses other than those specified by _p_r_o_t; however, the implementation will not permit a write to succeed where PPRROOTT__WWRRIITTEE has not been set or permit any access where PPRROOTT__NNOONNEE alone has been set. Each platform-specific implementation of mmmmaapp(()) supports the following values of _p_r_o_t: PPRROOTT__NNOONNEE, PPRROOTT__RREEAADD, PPRROOTT__WWRRIITTEE, and the inclusive OORR of PPRROOTT__RREEAADD and PPRROOTT__WWRRIITTEE. On some platforms, the PPRROOTT__WWRRIITTEE protection option is implemented as PPRROOTT__RREEAADD||PPRROOTT__WWRRIITTEE and PPRROOTT__EEXXEECC as PPRROOTT__RREEAADD||PPRROOTT__EEXXEECC. The file descriptor _f_i_l_d_e_s is opened with read permission, regardless of the protection options specified. If PPRROOTT__WWRRIITTEE is specified, the application must have opened the file descriptor _f_i_l_d_e_s with write permission unless MMAAPP__PPRRIIVVAATTEE is specified in the _f_l_a_g_s argument as described below. The _f_l_a_g_s argument provides other information about the handling of the mapped data. The value of _f_l_a_g_s is the bitwise inclusive OORR of these options, defined in : MMAAPP__SSHHAARREEDD Changes are shared. MMAAPP__PPRRIIVVAATTEE Changes are private. MMAAPP__FFIIXXEEDD Interpret _a_d_d_r exactly. MMAAPP__NNOORREESSEERRVVEE Do not reserve swap space. MMAAPP__AANNOONN Map anonymous memory. MMAAPP__AALLIIGGNN Interpret _a_d_d_r as required alignment. MMAAPP__TTEEXXTT Map text. MMAAPP__IINNIITTDDAATTAA Map initialized data segment. MMAAPP__3322BBIITT Map to the lower 32 bits of address space. MMAAPP__FFIILLEE Map a regular file. This is the default behavior; specifying this flag is not required. It is provided for compatibility with other systems and should not be included in new code. The MMAAPP__SSHHAARREEDD and MMAAPP__PPRRIIVVAATTEE options describe the disposition of write references to the underlying object. If MMAAPP__SSHHAARREEDD is specified, write references will change the memory object. If MMAAPP__PPRRIIVVAATTEE is specified, the initial write reference will create a private copy of the memory object page and redirect the mapping to the copy. The private copy is not created until the first write; until then, other users who have the object mapped MMAAPP__SSHHAARREEDD can change the object. Either MMAAPP__SSHHAARREEDD or MMAAPP__PPRRIIVVAATTEE must be specified, but not both. The mapping type is retained across ffoorrkk(2). When MMAAPP__FFIIXXEEDD is set in the _f_l_a_g_s argument, the system is informed that the value of _p_a must be _a_d_d_r, exactly. If MMAAPP__FFIIXXEEDD is set, mmmmaapp(()) may return (vvooiidd **)-1 and set eerrrrnnoo to EEIINNVVAALL. If a MMAAPP__FFIIXXEEDD request is successful, the mapping established by mmmmaapp(()) replaces any previous mappings for the process's pages in the range [_p_a_, _p_a _+ _l_e_n). The use of MMAAPP__FFIIXXEEDD is discouraged, since it may prevent a system from making the most effective use of its resources. When MMAAPP__FFIIXXEEDD is set and the requested address is the same as previous mapping, the previous address is unmapped and the new mapping is created on top of the old one. When MMAAPP__FFIIXXEEDD is not set, the system uses _a_d_d_r to arrive at _p_a. The _p_a so chosen will be an area of the address space that the system deems suitable for a mapping of _l_e_n bytes to the file. The mmmmaapp(()) function interprets an _a_d_d_r value of 0 as granting the system complete freedom in selecting _p_a, subject to constraints described below. A non-zero value of _a_d_d_r is taken to be a suggestion of a process address near which the mapping should be placed. When the system selects a value for _p_a, it will never place a mapping at address 0, nor will it replace any extant mapping, nor map into areas considered part of the potential data or stack "segments". When MMAAPP__AALLIIGGNN is set, the system is informed that the alignment of _p_a must be the same as _a_d_d_r. The alignment value in _a_d_d_r must be 0 or some power of two multiple of page size as returned by ssyyssccoonnff(3C). If addr is 0, the system will choose a suitable alignment. The MMAAPP__NNOORREESSEERRVVEE option specifies that no swap space be reserved for a mapping. Without this flag, the creation of a writable MMAAPP__PPRRIIVVAATTEE mapping reserves swap space equal to the size of the mapping; when the mapping is written into, the reserved space is employed to hold private copies of the data. A write into a MMAAPP__NNOORREESSEERRVVEE mapping produces results which depend on the current availability of swap space in the system. If space is available, the write succeeds and a private copy of the written page is created; if space is not available, the write fails and a SSIIGGBBUUSS or SSIIGGSSEEGGVV signal is delivered to the writing process. MMAAPP__NNOORREESSEERRVVEE mappings are inherited across ffoorrkk(()); at the time of the ffoorrkk(()), swap space is reserved in the child for all private pages that currently exist in the parent; thereafter the child's mapping behaves as described above. When MMAAPP__AANNOONN is set in _f_l_a_g_s, and _f_i_l_d_e_s is set to -1, mmmmaapp(()) provides a direct path to return anonymous pages to the caller. This operation is equivalent to passing mmmmaapp(()) an open file descriptor on //ddeevv//zzeerroo with MMAAPP__AANNOONN elided from the _f_l_a_g_s argument. The MMAAPP__TTEEXXTT option informs the system that the mapped region will be used primarily for executing instructions. This information can help the system better utilize MMU resources on some platforms. This flag is always passed by the dynamic linker when it maps text segments of shared objects. When the MMAAPP__TTEEXXTT option is used for regular file mappings on some platforms, the system can choose a mapping size larger than the page size returned by ssyyssccoonnff(3C). The specific page sizes that are used depend on the platform and the alignment of the addr and len arguments. Several different mapping sizes can be used to map the region with larger page sizes used in the parts of the region that meet alignment and size requirements for those page sizes. The MMAAPP__IINNIITTDDAATTAA option informs the system that the mapped region is an initialized data segment of an executable or shared object. When the MMAAPP__IINNIITTDDAATTAA option is used for regular file mappings on some platforms, the system can choose a mapping size larger than the page size returned by ssyyssccoonnff(()). The MMAAPP__IINNIITTDDAATTAA option should be used only by the dynamic linker for mapping initialized data of shared objects. The MMAAPP__3322BBIITT option informs the system that the search space for mapping assignment should be limited to the first 32 bits (4 Gbytes) of the caller's address space. This flag is accepted in both 32-bit and 64-bit process models, but does not alter the mapping strategy when used in a 32-bit process model. The _o_f_f argument is constrained to be aligned and sized according to the value returned by ssyyssccoonnff(()) when passed __SSCC__PPAAGGEESSIIZZEE or __SSCC__PPAAGGEE__SSIIZZEE. When MMAAPP__FFIIXXEEDD is specified, the _a_d_d_r argument must also meet these constraints. The system performs mapping operations over whole pages. Thus, while the _l_e_n argument need not meet a size or alignment constraint, the system will include, in any mapping operation, any partial page specified by the range [_p_a_, _p_a _+ _l_e_n). 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 SSIIGGBBUUSS or SSIIGGSSEEGGVV signal. SSIIGGBBUUSS signals may also be delivered on various file system conditions, including quota exceeded errors. The mmmmaapp(()) function adds an extra reference to the file associated with the file descriptor _f_i_l_d_e_s which is not removed by a subsequent cclloossee(2) on that file descriptor. This reference is removed when there are no more mappings to the file by a call to the mmuunnmmaapp(2) function. The sstt__aattiimmee field of the mapped file may be marked for update at any time between the mmmmaapp(()) call and the corresponding mmuunnmmaapp(2) call. The initial read or write reference to a mapped region will cause the file's sstt__aattiimmee field to be marked for update if it has not already been marked for update. The sstt__ccttiimmee and sstt__mmttiimmee fields of a file that is mapped with MMAAPP__SSHHAARREEDD and PPRROOTT__WWRRIITTEE, will be marked for update at some point in the interval between a write reference to the mapped region and the next call to mmssyynncc(3C) with MMSS__AASSYYNNCC or MMSS__SSYYNNCC for that portion of the file by any process. If there is no such call, these fields may be marked for update at any time after a write reference if the underlying file is modified as a result. If the process calls mmlloocckkaallll(3C) with the MMCCLL__FFUUTTUURREE flag, the pages mapped by all future calls to mmmmaapp(()) will be locked in memory. In this case, if not enough memory could be locked, mmmmaapp(()) fails and sets eerrrrnnoo to EEAAGGAAIINN. The mmmmaapp(()) function aligns based on the length of the mapping. When determining the amount of space to add to the address space, mmmmaapp(()) includes two 8-Kbyte pages, one at each end of the mapping that are not mapped and are therefore used as "red-zone" pages. Attempts to reference these pages result in access violations. The size requested is incremented by the 16 Kbytes for these pages and is then subject to rounding constraints. The constraints are: o For 32-bit processes: If length > 4 Mbytes round to 4-Mbyte multiple elseif length > 512 Kbytes round to 512-Kbyte multiple else round to 64-Kbyte multiple o For 64-bit processes: If length > 4 Mbytes round to 4-Mbyte multiple else round to 1-Mbyte multiple The net result is that for a 32-bit process: o If an mmmmaapp(()) request is made for 4 Mbytes, it results in 4 Mbytes + 16 Kbytes and is rounded up to 8 Mbytes. o If an mmmmaapp(()) request is made for 512 Kbytes, it results in 512 Kbytes + 16 Kbytes and is rounded up to 1 Mbyte. o If an mmmmaapp(()) request is made for 1 Mbyte, it results in 1 Mbyte + 16 Kbytes and is rounded up to 1.5 Mbytes. o Each 8-Kbyte mmap request "consumes" 64 Kbytes of virtual address space. To obtain maximal address space usage for a 32-bit process: o Combine 8-Kbyte requests up to a limit of 48 Kbytes. o Combine amounts over 48 Kbytes into 496-Kbyte chunks. o Combine amounts over 496 Kbytes into 4080-Kbyte chunks. To obtain maximal address space usage for a 64-bit process: o Combine amounts < 1008 Kbytes into chunks <= 1008 Kbytes. o Combine amounts over 1008 Kbytes into 4080-Kbyte chunks. The following is the output from a 32-bit program demonstrating this: mmaapp 88119922 bbyytteess:: 00xxffff339900000000 mmaapp 88119922 bbyytteess:: 00xxffff338800000000 64-Kbyte delta between starting addresses. mmaapp 551122 KKbbyytteess:: 00xxffff118800000000 mmaapp 551122 KKbbyytteess:: 00xxffff008800000000 1-Mbyte delta between starting addresses. mmaapp 449966 KKbbyytteess:: 00xxffff000000000000 mmaapp 449966 KKbbyytteess:: 00xxffeeff8800000000 512-Kbyte delta between starting addresses mmaapp 11 MMbbyyttee:: 00xxffeeee0000000000 mmaapp 11 MMbbyyttee:: 00xxffeecc8800000000 1536-Kbyte delta between starting addresses mmaapp 11000088 KKbbyytteess:: 00xxffeebb8800000000 mmaapp 11000088 KKbbyytteess:: 00xxffeeaa8800000000 1-Mbyte delta between starting addresses mmaapp 44 MMbbyytteess:: 00xxffee440000000000 mmaapp 44 MMbbyytteess:: 00xxffddcc0000000000 8-Mbyte delta between starting addresses mmaapp 44008800 KKbbyytteess:: 00xxffdd880000000000 mmaapp 44008800 KKbbyytteess:: 00xxffdd440000000000 4-Mbyte delta between starting addresses The following is the output of the same program compiled as a 64-bit application: mmaapp 88119922 bbyytteess:: 00xxffffffffffffffff77ff000000000000 mmaapp 88119922 bbyytteess:: 00xxffffffffffffffff77eeff0000000000 1-Mbyte delta between starting addresses mmaapp 551122 KKbbyytteess:: 00xxffffffffffffffff77eeee0000000000 mmaapp 551122 KKbbyytteess:: 00xxffffffffffffffff77eedd0000000000 1-Mbyte delta between starting addresses mmaapp 449966 KKbbyytteess:: 00xxffffffffffffffff77eecc0000000000 mmaapp 449966 KKbbyytteess:: 00xxffffffffffffffff77eebb0000000000 1-Mbyte delta between starting addresses mmaapp 11 MMbbyyttee:: 00xxffffffffffffffff77ee990000000000 mmaapp 11 MMbbyyttee:: 00xxffffffffffffffff77ee770000000000 2-Mbyte delta between starting addresses mmaapp 11000088 KKbbyytteess:: 00xxffffffffffffffff77ee660000000000 mmaapp 11000088 KKbbyytteess:: 00xxffffffffffffffff77ee550000000000 1-Mbyte delta between starting addresses mmaapp 44 MMbbyytteess:: 00xxffffffffffffffff77ee000000000000 mmaapp 44 MMbbyytteess:: 00xxffffffffffffffff77dd880000000000 8-Mbyte delta between starting addresses mmaapp 44008800 KKbbyytteess:: 00xxffffffffffffffff77dd440000000000 mmaapp 44008800 KKbbyytteess:: 00xxffffffffffffffff77dd000000000000 4-Mbyte delta between starting addresses RREETTUURRNN VVAALLUUEESS Upon successful completion, the mmmmaapp(()) function returns the address at which the mapping was placed (_p_a); otherwise, it returns a value of MMAAPP__FFAAIILLEEDD and sets eerrrrnnoo to indicate the error. The symbol MMAAPP__FFAAIILLEEDD is defined in the header . No successful return from mmmmaapp(()) will return the value MMAAPP__FFAAIILLEEDD. If mmmmaapp(()) fails for reasons other than EEBBAADDFF, EEIINNVVAALL or EENNOOTTSSUUPP, some of the mappings in the address range starting at _a_d_d_r and continuing for _l_e_n bytes may have been unmapped. EERRRROORRSS The mmmmaapp(()) function will fail if: EEAACCCCEESS The _f_i_l_d_e_s file descriptor is not open for read, regardless of the protection specified; or _f_i_l_d_e_s is not open for write and PPRROOTT__WWRRIITTEE was specified for a MMAAPP__SSHHAARREEDD type mapping. EEAAGGAAIINN The mapping could not be locked in memory. There was insufficient room to reserve swap space for the mapping. EEBBAADDFF The _f_i_l_d_e_s file descriptor is not open (and MMAAPP__AANNOONN was not specified). EEIINNVVAALL The arguments _a_d_d_r (if MMAAPP__FFIIXXEEDD was specified) or _o_f_f are not multiples of the page size as returned by ssyyssccoonnff(()). The argument _a_d_d_r (if MMAAPP__AALLIIGGNN was specified) is not 0 or some power of two multiple of page size as returned by ssyyssccoonnff(3C). MMAAPP__FFIIXXEEDD and MMAAPP__AALLIIGGNN are both specified. The field in _f_l_a_g_s is invalid (neither MMAAPP__PPRRIIVVAATTEE or MMAAPP__SSHHAARREEDD is set). The argument _l_e_n has a value equal to 0. MMAAPP__AANNOONN was specified, but the file descriptor was not -1. MMAAPP__TTEEXXTT was specified but PPRROOTT__EEXXEECC was not. MMAAPP__TTEEXXTT and MMAAPP__IINNIITTDDAATTAA were both specified. EEMMFFIILLEE The number of mapped regions would exceed an implementation-dependent limit (per process or per system). EENNOODDEEVV The _f_i_l_d_e_s argument refers to an object for which mmmmaapp(()) is meaningless, such as a terminal. EENNOOMMEEMM The MMAAPP__FFIIXXEEDD option was specified and the range [_a_d_d_r_, _a_d_d_r _+ _l_e_n) exceeds that allowed for the address space of a process. The MMAAPP__FFIIXXEEDD option was _n_o_t specified and there is insufficient room in the address space to effect the mapping. The mapping could not be locked in memory, if required by mmlloocckkaallll(3C), because it would require more space than the system is able to supply. The composite size of _l_e_n plus the lengths obtained from all previous calls to mmmmaapp(()) exceeds RRLLIIMMIITT__VVMMEEMM (see ggeettrrlliimmiitt(2)). EENNOOTTSSUUPP The system does not support the combination of accesses requested in the _p_r_o_t argument. EENNXXIIOO Addresses in the range [_o_f_f_, _o_f_f _+ _l_e_n) are invalid for the object specified by _f_i_l_d_e_s. The MMAAPP__FFIIXXEEDD option was specified in _f_l_a_g_s and the combination of _a_d_d_r, _l_e_n and _o_f_f is invalid for the object specified by _f_i_l_d_e_s. EEOOVVEERRFFLLOOWW The file is a regular file and the value of _o_f_f plus _l_e_n exceeds the offset maximum establish in the open file description associated with _f_i_l_d_e_s. The mmmmaapp(()) function may fail if: EEAAGGAAIINN The file to be mapped is already locked using advisory or mandatory record locking. See ffccnnttll(2). UUSSAAGGEE Use of mmmmaapp(()) may reduce the amount of memory available to other memory allocation functions. MMAAPP__AALLIIGGNN is useful to assure a properly aligned value of _p_a for subsequent use with mmeemmccnnttll(2) and the MMCC__HHAATT__AADDVVIISSEE command. This is best used for large, long-lived, and heavily referenced regions. MMAAPP__FFIIXXEEDD and MMAAPP__AALLIIGGNN are always mutually-exclusive. Use of MMAAPP__FFIIXXEEDD may result in unspecified behavior in further use of bbrrkk(2), ssbbrrkk(2), mmaalllloocc(3C), and sshhmmaatt(2). The use of MMAAPP__FFIIXXEEDD is discouraged, as it may prevent an implementation from making the most effective use of resources. The application must ensure correct synchronization when using mmmmaapp(()) in conjunction with any other file access method, such as rreeaadd(2) and wwrriittee(2), standard input/output, and sshhmmaatt(2). The mmmmaapp(()) function has a transitional interface for 64-bit file offsets. See llff6644(5). The mmmmaapp(()) function allows access to resources using address space manipulations instead of the rreeaadd(())/wwrriittee(()) 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: fildes = open(...) lseek(fildes, offset, whence) read(fildes, buf, len) /* use data in buf */ The following is a rewrite using mmmmaapp(()): fildes = open(...) address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE), MAP_PRIVATE, fildes, offset) /* use data at address */ AATTTTRRIIBBUUTTEESS See aattttrriibbuutteess(5) for descriptions of the following attributes: +--------------------+-------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-------------------+ |Interface Stability | Standard | +--------------------+-------------------+ |MT-Level | Async-Signal-Safe | +--------------------+-------------------+ SSEEEE AALLSSOO cclloossee(2), eexxeecc(2), ffccnnttll(2), ffoorrkk(2), ggeettrrlliimmiitt(2), mmeemmccnnttll(2), mmmmaappoobbjj(2), mmpprrootteecctt(2), mmuunnmmaapp(2), sshhmmaatt(2), lloocckkff(3C), mmlloocckkaallll(3C), mmssyynncc(3C), pplloocckk(3C), ssyyssccoonnff(3C), aattttrriibbuutteess(5), llff6644(5), ssttaannddaarrddss(5), nnuullll(7D), zzeerroo(7D) August 29, 2016 MMAP(2)