MMAP(2) BSD System Calls Manual MMAP(2) NNAAMMEE mmmmaapp -- map files or devices into memory SSYYNNOOPPSSIISS ##iinncclluuddee <> _v_o_i_d _* mmmmaapp(_v_o_i_d _*_a_d_d_r, _s_i_z_e___t _l_e_n, _i_n_t _p_r_o_t, _i_n_t _f_l_a_g_s, _i_n_t _f_i_l_d_e_s, _o_f_f___t _o_f_f_s_e_t); DDEESSCCRRIIPPTTIIOONN The mmmmaapp function causes the pages starting at _a_d_d_r and continuing for at most _l_e_n bytes to be mapped from the object described by _f_i_l_d_e_s, starting at byte offset _o_f_f_s_e_t. If _o_f_f_s_e_t or _l_e_n is not a multiple of the page- size, the mapped region may extend past the specified range. If _a_d_d_r is non-zero, it is used as a hint to the system. (As a conve- nience to the system, the actual address of the region may differ from the address supplied.) If _a_d_d_r is zero, an address will be selected by the system. The actual starting address of the region is returned. A successful _m_m_a_p deletes any previous mapping in the allocated address range. The protections (region accessibility) are specified in the _p_r_o_t argument by _o_r'ing the following values: PROT_EXEC Pages may be executed. PROT_READ Pages may be read. PROT_WRITE Pages may be written. The _f_l_a_g_s parameter specifies the type of the mapped object, mapping options, and whether modifications made to the mapped copy of the page are private to the process (copy-on-write) or are to be shared with other references. Sharing, mapping type, and options are specified in the _f_l_a_g_s argument by _o_r'ing the following values: MAP_ANON Map anonymous memory not associated with any specific file. Mac OS X specific: the file descriptor used for creating MAP_ANON regions can be used to pass some Mach VM flags, and can be specified as -1 if no such flags are associated with the region. Mach VM flags are defined in and the ones that currently apply to mmmmaapp are: VM_FLAGS_PURGABLE to create Mach purgable (i.e. volatile) memory VM_MAKE_TAG(tag) to associate an 8-bit tag with the region defines some preset tags (with a VM_MEMORY_ prefix). Users are encouraged to use tags between 240 and 255. Tags are used by tools such as vmmap(1) to help identify specific memory regions. MAP_FILE Mapped from a regular file or character-special device memory. (This is the default mapping type, and need not be specified.) MAP_FIXED Do not permit the system to select a different address than the one specified. If the specified address can- not be used, mmmmaapp will fail. If MAP_FIXED is speci- fied, _a_d_d_r must be a multiple of the pagesize. Use of this option is discouraged. MAP_HASSEMAPHORE Notify the kernel that the region may contain sema- phores and that special handling may be necessary. MAP_PRIVATE Modifications are private (copy-on-write). MAP_SHARED Modifications are shared. MAP_NOCACHE Pages in this mapping are not retained in the kernel's memory cache. If the system runs low on memory, pages in MAP_NOCACHE mappings will be among the first to be reclaimed. This flag is intended for mappings that have little locality and provides a hint to the kernel that pages in this mapping are unlikely to be needed again in the near future. Conforming applications must specify either MAP_PRIVATE or MAP_SHARED. The close(2) function does not unmap pages, see munmap(2) for further information. The current design does not allow a process to specify the location of swap space. In the future we may define an additional mapping type, MAP_SWAP, in which the file descriptor argument specifies a file or device to which swapping should be done. RREETTUURRNN VVAALLUUEESS Upon successful completion, mmmmaapp returns a pointer to the mapped region. Otherwise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. EERRRROORRSS MMmmaapp() will fail if: [EACCES] _F_i_l_d_e_s is not open for reading. [EACCES] The flags PROT_WRITE and MAP_SHARED are specified as part of the _f_l_a_g_s and _p_r_o_t parameters and _f_i_l_d_e_s is not open for writing. [EBADF] _f_i_l_d_e_s is not a valid file descriptor for an open file. [EINVAL] MAP_FIXED is specified and the parameter is not page aligned. [EINVAL] _f_i_l_d_e_s does not reference a regular or character spe- cial file. [EINVAL] _f_l_a_g_s does not include either MAP_PRIVATE or MAP_SHARED. [EINVAL] _l_e_n is not greater than zero. [EINVAL] _o_f_f_s_e_t is not a multiple of the page size, as returned by sysconf(3). [EMFILE] The limit on mapped regions (per process or system) is exceeded. [ENODEV] The file type for _f_i_l_d_e_s is not supported for mapping. [ENOMEM] MAP_FIXED is specified and the address range specified exceeds the address space limit for the process. [ENOMEM] MAP_FIXED is specified and the address specified by the _a_d_d_r parameter isn't available. [ENOMEM] MAP_ANON is specified and insufficient memory is available. [ENXIO] Addresses in the specified range are invalid for fildes. [EOVERFLOW] Addresses in the specified range exceed the maximum offset set for fildes. LLEEGGAACCYY SSYYNNOOPPSSIISS ##iinncclluuddee <> ##iinncclluuddee <> The include file <_s_y_s_/_t_y_p_e_s_._h> is necessary. CCOOMMPPAATTIIBBIILLIITTYY mmmmaapp() now returns with _e_r_r_n_o set to EINVAL in places that historically succeeded. The rules have changed as follows: ++oo The _f_l_a_g_s parameter must specify either MAP_PRIVATE or MAP_SHARED. ++oo The _s_i_z_e parameter must not be 0. ++oo The _o_f_f parameter must be a multiple of pagesize, as returned by ssyyssccoonnff(). SSEEEE AALLSSOO getpagesize(2), madvise(2), mincore(2), mlock(2), mprotect(2), msync(2), munmap(2), sysconf(3), compat(5) 4th Berkeley Distribution June 4, 1993 4th Berkeley Distribution