manpagez: man (manual) pages & more
man mmap(2)
Home | html | info | man
mmap(2)                     BSD System Calls Manual                    mmap(2)


NAME

     mmap -- allocate memory, or map files or devices into memory


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <sys/mman.h>

     void *
     mmap(void *addr, size_t len, int prot, int flags, int fd, off_t offset);


DESCRIPTION

     The mmap() system call causes the pages starting at addr and continuing
     for at most len bytes to be mapped from the object described by fd,
     starting at byte offset offset.  If offset or len is not a multiple of
     the pagesize, the mapped region may extend past the specified range.  Any
     extension beyond the end of the mapped object will be zero-filled.

     The addr argument is used by the system to determine the starting address
     of the mapping, and its interpretation is dependent on the setting of the
     MAP_FIXED flag.  If MAP_FIXED is specified in flags, the system will try
     to place the mapping at the specified address, possibly removing a map-
     ping that already exists at that location.  If MAP_FIXED is not speci-
     fied, then the system will attempt to use the range of addresses starting
     at addr if they do not overlap any existing mappings, including memory
     allocated by malloc(3) and other such allocators.  Otherwise, the system
     will choose an alternate address for the mapping (using an implementation
     dependent algorithm) that does not overlap any existing mappings.  In
     other words, without MAP_FIXED the system will attempt to find an empty
     location in the address space if the specified address range has already
     been mapped by something else.  If addr is zero and MAP_FIXED is not
     specified, then an address will be selected by the system so as not to
     overlap any existing mappings in the address space.  In all cases, the
     actual starting address of the region is returned.  If MAP_FIXED is spec-
     ified, a successful mmap deletes any previous mapping in the allocated
     address range.  Previous mappings are never deleted if MAP_FIXED is not
     specified.

     The protections (region accessibility) are specified in the prot argument
     by or'ing the following values:

     PROT_NONE   Pages may not be accessed.
     PROT_READ   Pages may be read.
     PROT_WRITE  Pages may be written.
     PROT_EXEC   Pages may be executed.

     Note that, due to hardware limitations, on some platforms PROT_WRITE may
     imply PROT_READ, and PROT_READ may imply PROT_EXEC.  Portable programs
     should not rely on these flags being separately enforcable.

     The flags argument 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 flags
     argument by or'ing the following values:

     MAP_ANON          Map anonymous memory not associated with any specific
                       file.  The offset argument is ignored.  Mac OS X spe-
                       cific: 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 <mach/vm_sta-
                       tistics.h> and the ones that currently apply to mmap
                       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
                       <mach/vm_statistics.h> 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.

                       VM_FLAGS_SUPERPAGE_SIZE_*     to use superpages for the
                       allocation.  See <mach/vm_statistics.h> for supported
                       architectures and sizes (or use VM_FLAGS_SUPER-
                       PAGE_SIZE_ANY to have the kernel choose a size).  The
                       specified size must be divisible by the superpage size
                       (except for VM_FLAGS_SUPERPAGE_SIZE_ANY), and if you
                       use MAP_FIXED, the specified address must be properly
                       aligned. If the system cannot satisfy the request with
                       superpages, the call will fail. Note that currently,
                       superpages are always wired and not inherited by chil-
                       dren of the process.

     MAP_FILE          Mapped from a regular file.  (This is the default map-
                       ping 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, mmap() will fail.  If MAP_FIXED is speci-
                       fied, addr must be a multiple of the pagesize.  If a
                       MAP_FIXED request is successful, the mapping estab-
                       lished by mmap() replaces any previous mappings for the
                       process' pages in the range from addr to addr + len.
                       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) system call 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.


RETURN VALUES

     Upon successful completion, mmap() returns a pointer to the mapped
     region.  Otherwise, a value of MAP_FAILED is returned and errno is set to
     indicate the error.


ERRORS

     The mmap() system call will fail if:

     [EACCES]           The flag PROT_READ was specified as part of the prot
                        argument and fd was not open for reading.  The flags
                        MAP_SHARED and PROT_WRITE were specified as part of
                        the flags and prot argument and fd was not open for
                        writing.

     [EBADF]            The fd argument is not a valid open file descriptor.

     [EINVAL]           MAP_FIXED was specified and the addr argument was not
                        page aligned, or part of the desired address space
                        resides out of the valid address space for a user
                        process.

     [EINVAL]           flags does not include either MAP_PRIVATE or
                        MAP_SHARED.

     [EINVAL]           The len argument was negative.

     [EINVAL]           The offset argument was not page-aligned based on the
                        page size as returned by getpagesize(3).

     [ENODEV]           MAP_ANON has not been specified and the file fd refers
                        to does not support mapping.

     [ENOMEM]           MAP_FIXED was specified and the addr argument was not
                        available.  MAP_FIXED was specified and the address
                        range specified exceeds the address space limit for
                        the process.  MAP_ANON was specified and insufficient
                        memory was available.

     [ENXIO]            Addresses in the specified range are invalid for fd.

     [EOVERFLOW]        Addresses in the specified range exceed the maximum
                        offset set for fd.


LEGACY SYNOPSIS

     #include <sys/types.h>
     #include <sys/mman.h>

     The include file <sys/types.h> is necessary.


COMPATIBILITY

     mmap() now returns with errno set to EINVAL in places that historically
     succeeded.  The rules have changed as follows:

     o   The flags parameter must specify either MAP_PRIVATE or MAP_SHARED.

     o   The size parameter must not be 0.

     o   The off parameter must be a multiple of pagesize, as returned by
         sysconf().


SEE ALSO

     madvise(2), mincore(2), minherit(2), mlock(2), mprotect(2), msync(2),
     munlock(2), munmap(2), shmat(2), getpagesize(3)

BSD                             April 21, 2006                             BSD

Mac OS X 10.9.1 - Generated Mon Jan 6 09:26:01 CST 2014