mmap(2) mmap(2) NAME mmap - map pages of memory SYNOPSIS #include <sys/mman.h> void *mmap(void *addr, size_t len, int prot, int flags, int fildes, off_t off); DESCRIPTION The mmap() function establishes a mapping between a process' address space and a file. The format of the call is as follows: pa=mmap(addr, len, prot, flags, fildes, off); The mmap() function establishes a mapping between the process' address space at an address pa for len bytes and the file associated with the file descriptor fildes at offset off for len bytes. The value of pa is an unspecified function of the argument addr and values of flags, further described below. A successful mmap() call returns pa as its result. The address ranges covered by [pa, pa+len] and [off, off+len] must be legitimate for the possible (not necessarily current) address space of a process and the file, respectively. If the size of the mapped file changes after the call to mmap(), the effect of references to portions of the mapped region that correspond to added or removed portions of the file is unspecified. The mmap() function is supported for regular files. Support for any other type of file is unspecified. The prot argument determines whether read, write, execute, or some combination of accesses are permitted to the pages being mapped. The protection options are defined in <sys/mman.h>: PROT_READ Page can be read. PROT_WRITE Page can be written. PROT_EXEC Page can be executed. PROT_NONE Page cannot be accessed. Implementations need not enforce all combinations of access permissions. However, writes shall only be permitted when PROT_WRITE has been set. The flags argument provides other information about the handling of the mapped pages. The options are defined in <sys/mman.h>: Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 mmap(2) mmap(2) MAP_SHARED Share changes. MAP_PRIVATE Changes are private. MAP_FIXED Interpret addr exactly. The MAP_PRIVATE and MAP_SHARED flags control the visibility of write references to the memory region. Exactly one of these flags must be specified. The mapping type is retained across a fork(). If MAP_SHARED is set in flags, write references to the memory region by the calling process may change the file and are visible in all MAP_SHARED mappings of the same portion of the file by any process. If MAP_PRIVATE is set in flags, write references to the memory region by the calling process do not change the file and are not visible to any process in other mappings of the same portion of the file. It is unspecified whether write references by processes that have mapped the memory region using MAP_SHARED are visible to processes that have mapped the same portion of the file using MAP_PRIVATE. It is also unspecified whether write references to a memory region mapped with MAP_SHARED are visible to processes reading the file and whether writes to a file are visible to processes that have mapped the modified portion of that file, except for the effect of msync(). When MAP_FIXED is set in the flags argument, the implementation is informed that the value of pa must be addr, exactly. If MAP_FIXED is set, mmap() may return (void *)-1 and set errno to EINVAL. If a MAP_FIXED request is successful, the mapping established by mmap() replaces any previous mappings for the process' pages in the range [pa, pa+len]. When MAP_FIXED is not set, the implementation uses addr in an unspecified manner to arrive at pa. The pa so chosen will be an area of the address space which the implementation deems suitable for a mapping of len bytes to the file. All implementations interpret an addr value of 0 as granting the implementation complete freedom in selecting pa, subject to constraints described below. A non-zero value of addr is taken to be a suggestion of a process address near which the mapping should be placed. When the implementation selects a value for pa, it never places a mapping at address 0, nor does it replace any extant mapping, nor map into dynamic memory allocation areas. The off argument is constrained to be aligned and sized according to the value returned by sysconf() when passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, the argument addr must also meet these constraints. The implementation performs mapping operations over whole pages. Thus, while the argument len need not meet a size or alignment constraint, the implementation will include, Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 mmap(2) mmap(2) in any umapping operation, any partial page specified by the range [pa, pa+len]. The implementation always zero-fills any partial page at the end of a memory region. Further, the implementation never writes out any modified portions of the last page of a file that are beyond the end of the mapped portion of the file. If the mapping established by mmap() extends into pages beyond the page containing the last byte of the file, an application reference to any of the pages in the mapping that are beyond the last page results in the delivery of a SIGBUS or SIGSEGV signal. The mmap() function adds an extra reference to the file associated with the file descriptor fildes which is not removed by a subsequent close() on that file descriptor. This reference is removed when there are no more mappings to the file. The st_atime field of the mapped file may be marked for update at any time between the mmap() call and the corresponding munmap() call. The initial read or write reference to a mapped region will cause the file's st_atime field to be marked for update if it has not already been marked for update. The st_ctime and st_mtime fields of a file that is mapped with MAP_SHARED and PROT_WRITE, will be marked for update at some point in the interval between a write reference to the mapped region and the next call to msync() with MS_ASYNC or MS_SYNC 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. There may be implementation-dependent limits on the number of memory regions that 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 is decreased by the use of shmat() is implementation-dependent. RETURN VALUE Upon successful completion, mmap() returns the address at which the mapping was placed (pa). Otherwise, it returns a value of -1 and sets errno to indicate the error. ERRORS The mmap() function will fail if: [EBADF] The fildes argument is not a valid open file descriptor. [EACCES] The fildes argument is not open for read, regardless of the protection specified, or fildes is not open for write and PROT_WRITE was specified for a MAP_SHARED type mapping. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 mmap(2) mmap(2) [ENXIO] Addresses in the range [off, off+len] are invalid for fildes. [EINVAL] The addr argument (if MAP_FIXED was specified) or off is not a multiple of the page size as returned by sysconf(), or are considered invalid by the implementation. [EINVAL] The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set). [EMFILE] The number of mapped regions would exceed an implementation-dependent limit (per process or per system). [ENODEV] The fildes argument refers to a file whose type is not supported by mmap(). [ENOMEM] MAP_FIXED was specified, and the range [addr, addr+len] 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. APPLICATION USAGE Use of mmap() may reduce the amount of memory available to other memory allocation functions. Use of MAP_FIXED may result in unspecified behaviour in further use of brk(), sbrk(), malloc(), and shmat(). The use of MAP_FIXED is discouraged, as it may prevent an implementation from making the most effective use of resources. The application must ensure correct synchronisation when using mmap() in conjunction with any other file access method, such as read() and write(), standard input/output, and shmat(). The mmap() function allows access to resources via address space manipulations, instead of read()/write(). 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 mmap(), the following: fildes = open(...) lseek(fildes, some_offset) read(fildes, buf, len) /* use data in buf */ becomes: Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 mmap(2) mmap(2) fildes = open(...) address = mmap(0, len, PROT_READ, MAP_PRIVATE, /* use data at address */ SEE ALSO exec, fcntl(), fork(), lockf(), msync(), munmap(), mprotect(), shmat(), sysconf(), <sys/mman.h>. CHANGE HISTORY First released in Issue 4, Version 2. - 5 - Formatted: April 25, 2001 mmap(2) mmap(2) HP-UX EXTENSIONS SYNOPSIS #include <sys/mman.h> caddr_t mmap( caddr_t addr, size_t len, int prot, int flags, int fildes, off_t off); DESCRIPTION MAP_FILE Create a mapped file region. MAP_ANONYMOUS Create an unnamed memory region. MAP_VARIABLE Place region at implementation-computed address. The MAP_FILE and MAP_ANONYMOUS flags control whether the region to be mapped is a mapped file region or an anonymous shared memory region. Exactly one of these flags must be selected. If MAP_FILE is set in flags: o A new mapped file region is created, mapping the file associated with fildes. o off specifies the file byte offset at which the mapping starts. This offset must be a multiple of the page size returned by sysconf(_SC_PAGE_SIZE). o If the end of the mapped file region is beyond the end of the file, any reference to an address in the mapped file region corresponding to an offset beyond the end of the file results in the delivery of a SIGBUS signal to the process, unless the address lies in the last partial page corresponding to the range beyond the end of the file. The last partial page mapping the range beyond the end of the file is always initialized to zeros, and any modified portions of the last page of a file which are beyond its end are not written back to the file. If MAP_ANONYMOUS is set in flags: o A new memory region is created and initialized to all zeros. This memory region can be shared only with descendants of Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 mmap(2) mmap(2) the current process. o If the fildes argument is not -1, an EINVAL error is generated. o The value of off is meaningless because there is no underlying file object for the memory region. The MAP_VARIABLE and MAP_FIXED flags control the placement of the region as described below. Exactly one of these flags must be selected. If MAP_VARIABLE is set in flags: o If the requested address is NULL, or if it is not possible for the system to place the region at the requested address, the region is placed at an address selected by the system. If the requested address is not a multiple of the page size returned by sysconf(_SC_PAGE_SIZE), the system treats the address as if it were rounded up to the next larger page size multiple. If MAP_FIXED is set in flags: o addr must be a multiple of the page size returned by sysconf(_SC_PAGE_SIZE). The prot argument can be PROT_NONE, or any combination of PROT_READ, PROT_WRITE , and PROT_EXEC ORed together. If PROT_NONE is not specified, the system may grant other access permissions to the region in addition to those explicitly requested, except that write access will not be granted unless PROT_WRITE is specified. mmap() cannot create a mapped file region unless the file descriptor used to map the file is open for reading. For a mapped file region that is mapped with MAP_SHARED, mmap() grants write access permission only if the file descriptor is open for writing. If a region was mapped with either MAP_PRIVATE or MAP_ANONYMOUS, mmap() grants all requested access permissions. After the successful completion of mmap(), fildes can be closed without effect on the mapped region or on the contents of the mapped file. Each mapped region creates a file reference, similar to an open file descriptor, that prevents the file data from being deallocated. Whether modifications made to the file using write() are visible to mapped regions, and whether modification to a mapped region are visible with read(), is undefined except for the effect of msync(). If an enforcement-mode file lock is in effect for any range of a file, a call to mmap() to map any range of the file with access rights that Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 mmap(2) mmap(2) would violate the lock fails. The msem_lock() and msem_unlock() semaphore interfaces can be used to coordinate shared access to a region created with the MAP_SHARED flag. The advisory locks of the lockf() or fcntl() interfaces have no effect on memory mapped access, but they can be used to coordinate shared access to a MAP_SHARED mapped file region. For a memory mapped file, the st_atime and st_mtime values returned by stat() are updated when a page in the memory mapped region is read from or written to the file system. After a call to fork(), the child process inherits all mapped regions with the same data and the same sharing and protection attributes as in the parent process. Each mapped file and anonymous memory region created with mmap() is unmapped upon process exit, and by a successful call to any of the exec functions. A SIGBUS signal is delivered to a process when a write reference to a mapped file region would cause a file system error condition such as exceeding quota or file system space limits. A SIGBUS signal is delivered to a process upon a write reference to a region without PROT_WRITE protection, or any reference to a region with PROT_NONE protection. A call to mmap() with PROT_EXECUTE specified, but without PROT_WRITE specified for a MAP_SHARED|MAP_FILE mapping is treated by the system as the execution of the underlying file. This implies that such a call fails if the file is currently open for writing or mapped with MAP_SHARED|PROT_WRITE options by any process, and that if the call succeeds, the file cannot be opened for writing or subsequently mapped with MAP_SHARED|PROT_WRITE options as long as such mappings are present. A file's status as an active executable file is determined only at the time of an exec(), exit(), or mmap() operation. mprotect() operations on a MAP_FILE|MAP_SHARED mapping have no effect on the underlying file's status as an active executable file. ERRORS [EACCES] The file referred to by fildes is not open for read access, or the file is not open for write access and PROT_WRITE was set for a MAP_SHARED mapping operation, or PROT_EXECUTE was set for a MAP_SHARED mapping operation and the underlying file does not have execute permission. [EAGAIN] The file represented by fildes has enforcement- mode file locking in effect for some range in the file. (see lockf(2), or fcntl(2)). [EOVERFLOW] The file is a regular file and the value of off+len exceeds the offset maximum established in Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 mmap(2) mmap(2) the open file description associated with fildes. [ETXTBSY] MAP_SHARED and MAP_FILE are set, and PROT_EXECUTE is set and PROT_WRITE is not set, and the file being mapped is currently open for writing. [EINVAL] The value of off+len exceeds the maximum supported offset for mapped files. DEPENDENCIES Series 700/800 Because the PA-RISC memory architecture utilizes a globally shared virtual address space between processes, and discourages multiple virtual address translations to the same physical address, all concurrently existing MAP_SHARED mappings of a file range must share the same virtual address offsets and hardware translations. PA-RISC- based HP-UX systems allocate virtual address ranges for shared memory and shared mapped files in the range 0x80000000 through 0xefffffff. This address range is used globally for all memory objects shared between processes. This implies the following: o Any single range of a file cannot be mapped multiply into different virtual address ranges. o After the initial MAP_SHARED mmap() of a file range, all subsequent MAP_SHARED calls to mmap() to map the same range of a file must either specify MAP_VARIABLE in flags and inherit the virtual address range the system has chosen for this range, or specify MAP_FIXED with an addr that corresponds exactly to the address chosen by the system for the initial mapping. Only after all mappings for a file range have been destroyed can that range be mapped to a different virtual address. o In most cases, two separate calls to mmap() cannot map overlapping ranges in a file. The virtual address range reserved for a file range is determined at the time of the initial mapping of the file range into a process address space. The system allocates only the virtual address range necessary to represent the initial mapping. As long as the initial mapping exists, subsequent attempts to map a different file range that includes any portion of the initial range may fail with an ENOMEM error if an extended contiguous address range that preserves the mappings of the initial range cannot be allocated. o Separate calls to mmap() to map contiguous ranges of a file do not necessarily return contiguous virtual address ranges. The system may allocate virtual addresses for each call to Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 mmap(2) mmap(2) mmap() on a first available basis. o The use of MAP_FIXED is strongly discouraged because it is not portable. Using MAP_FIXED is generally unsuccessful on this implementation, and when it is successful, it may prevent the system from optimally allocating virtual address space. MAP_FIXED is discouraged, but there are some applications which by design must fix pointer offsets into file data. The application must map the file at a specific address in order for the file offsets embedded in the file to make sense. Processes cannot control the usage of global virtual address space, but they can control what happens within their private data area. The Series 700/800 allows a single process to exclusively map a file MAP_SHARED into it's private data space. When a process specifies MAP_SHARED and MAP_FIXED with a private data address(i.e. second quadrant), the kernel interprets this as an exclusive mapping of the file. The request will only succeed if no other processes in the system currently have that file mapped through MAP_SHARED. If the file is already mapped the caller receives an EBUSY error. If the call is successful, the calling process is the only process allowed to map that file using MAP_SHARED until it unmaps the file using munmap(). Because it is exclusive, the mmap() is not inherited across fork(). When a file is exclusively mapped only MAP_PRIVATE mappings are allowed by other processes. The following combinations of protection modes are supported: PROT_NONE PROT_READ PROT_READ|PROT_EXECUTE PROT_READ|PROT_WRITE PROT_READ|PROT_WRITE|PROT_EXECUTE If a MAP_PRIVATE mapping is created of a file for which a MAP_SHARED mapping exists, a separate copy of a page for the MAP_PRIVATE mapping is created at the time of the first access to the page through the private mapping. AUTHOR mmap() was developed by HP, AT&T, and OSF. SEE ALSO fcntl(2), fork(2), ftruncate(2), lockf(2), madvise(2), mmap64(2), mprotect(2), msem_init(2), msem_lock(2), msem_unlock(2), msync(2), munmap(2), sysconf(2), mman(5), stat(5). STANDARDS CONFORMANCE mmap(): AES, SVID3 Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996