Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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 mul-tiple multiple
     tiple 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 mapping that
     already exists at that location.  If MAP_FIXED is not specified, 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 exist-ing existing
     ing 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 over-lap overlap
     lap any existing mappings in the address space.  In all cases, the actual starting address of the
     region is returned.  If MAP_FIXED is specified, 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 val-ues: values:
     ues:

     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 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 <mach/vm_statistics.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 VM_FLAGS_SUPERPAGE_SIZE_ANY
                       PAGE_SIZE_ANY to have the kernel choose a size).  The specified size must be divisi-ble divisible
                       ble 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 sat-isfy satisfy
                       isfy the request with superpages, the call will fail. Note that currently, superpages
                       are always wired and not inherited by children of the process.

     MAP_FILE          Mapped from a regular file.  (This is the default mapping type, and need not be spec-ified.) specified.)
                       ified.)

     MAP_FIXED         Do not permit the system to select a different address than the one specified.  If
                       the specified address cannot be used, mmap() will fail.  If MAP_FIXED is specified,
                       addr must be a multiple of the pagesize.  If a MAP_FIXED request is successful, the
                       mapping established 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 semaphores 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 get-pagesize(3). getpagesize(3).
                        pagesize(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:

     •   The flags parameter must specify either MAP_PRIVATE or MAP_SHARED.

     •   The size parameter must not be 0.

     •   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