GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:mmap

MMAP(2) Linux Programmer's Manual MMAP(2)

NAME

     mmap, munmap - map or unmap files or devices into memory

SYNOPSIS

     #include <sys/mman.h>
     void *mmap(void *addr, size_t length, int prot, int flags,
                int fd, off_t offset);
     int munmap(void *addr, size_t length);
     See NOTES for information on feature test macro requirements.

DESCRIPTION

     mmap()  creates a new mapping in the virtual address space of the call-
     ing process.  The starting address for the new mapping is specified  in
     addr.   The  length argument specifies the length of the mapping (which
     must be greater than 0).
     If addr is NULL, then the kernel chooses the (page-aligned) address  at
     which to create the mapping; this is the most portable method of creat-
     ing a new mapping.  If addr is not NULL, then the kernel takes it as  a
     hint  about  where  to place the mapping; on Linux, the mapping will be
     created at a nearby page boundary.  The address of the new  mapping  is
     returned as the result of the call.
     The contents of a file mapping (as opposed to an anonymous mapping; see
     MAP_ANONYMOUS below), are initialized using length  bytes  starting  at
     offset  offset  in  the  file (or other object) referred to by the file
     descriptor fd.  offset must be a multiple of the page size as  returned
     by sysconf(_SC_PAGE_SIZE).
     The  prot  argument describes the desired memory protection of the map-
     ping (and must not conflict with the open mode of  the  file).   It  is
     either  PROT_NONE  or  the  bitwise  OR of one or more of the following
     flags:
     PROT_EXEC  Pages may be executed.
     PROT_READ  Pages may be read.
     PROT_WRITE Pages may be written.
     PROT_NONE  Pages may not be accessed.
     The flags argument determines whether updates to the mapping are  visi-
     ble to other processes mapping the same region, and whether updates are
     carried through to the underlying file.  This behavior is determined by
     including exactly one of the following values in flags:
     MAP_SHARED
            Share this mapping.  Updates to the mapping are visible to other
            processes mapping the same region, and (in  the  case  of  file-
            backed  mappings)  are  carried  through to the underlying file.
            (To precisely control when updates are carried  through  to  the
            underlying file requires the use of msync(2).)
     MAP_SHARED_VALIDATE (since Linux 4.15)
            This  flag  provides the same behavior as MAP_SHARED except that
            MAP_SHARED mappings ignore unknown flags in flags.  By contrast,
            when  creating  a  mapping using MAP_SHARED_VALIDATE, the kernel
            verifies all passed flags are known and fails the  mapping  with
            the  error  EOPNOTSUPP  for unknown flags.  This mapping type is
            also required to be  able  to  use  some  mapping  flags  (e.g.,
            MAP_SYNC).
     MAP_PRIVATE
            Create  a private copy-on-write mapping.  Updates to the mapping
            are not visible to other processes mapping the  same  file,  and
            are  not carried through to the underlying file.  It is unspeci-
            fied whether changes made to the file after the mmap() call  are
            visible in the mapped region.
     Both  MAP_SHARED  and  MAP_PRIVATE  are  described  in POSIX.1-2001 and
     POSIX.1-2008.  MAP_SHARED_VALIDATE is a Linux extension.
     In addition, zero or more of the following values can be ORed in flags:
     MAP_32BIT (since Linux 2.4.20, 2.6)
            Put  the  mapping  into  the  first  2  Gigabytes of the process
            address space.  This flag  is  supported  only  on  x86-64,  for
            64-bit  programs.   It  was  added  to allow thread stacks to be
            allocated somewhere in the  first  2 GB  of  memory,  so  as  to
            improve  context-switch performance on some early 64-bit proces-
            sors.  Modern x86-64 processors no longer have this  performance
            problem,  so  use of this flag is not required on those systems.
            The MAP_32BIT flag is ignored when MAP_FIXED is set.
     MAP_ANON
            Synonym for MAP_ANONYMOUS.  Deprecated.
     MAP_ANONYMOUS
            The mapping is not backed by any file; its contents are initial-
            ized  to zero.  The fd argument is ignored; however, some imple-
            mentations require fd to be -1 if MAP_ANONYMOUS (or MAP_ANON) is
            specified,  and  portable  applications should ensure this.  The
            offset argument should be zero.  The  use  of  MAP_ANONYMOUS  in
            conjunction  with  MAP_SHARED  is  supported on Linux only since
            kernel 2.4.
     MAP_DENYWRITE
            This flag is ignored.  (Long ago--Linux 2.0 and earlier--it sig-
            naled  that attempts to write to the underlying file should fail
            with ETXTBUSY.  But  this  was  a  source  of  denial-of-service
            attacks.)
     MAP_EXECUTABLE
            This flag is ignored.
     MAP_FILE
            Compatibility flag.  Ignored.
     MAP_FIXED
            Don't  interpret  addr  as  a hint: place the mapping at exactly
            that address.  addr must be suitably aligned: for most architec-
            tures  a  multiple of the page size is sufficient; however, some
            architectures may impose additional restrictions.  If the memory
            region  specified by addr and len overlaps pages of any existing
            mapping(s), then the overlapped part of the existing  mapping(s)
            will  be  discarded.   If  the specified address cannot be used,
            mmap() will fail.
            Software that aspires to be portable should  use  the  MAP_FIXED
            flag  with  care,  keeping  in  mind  that the exact layout of a
            process's memory mappings is  allowed  to  change  significantly
            between  kernel versions, C library versions, and operating sys-
            tem releases.  Carefully read the discussion  of  this  flag  in
            NOTES!
     MAP_FIXED_NOREPLACE (since Linux 4.17)
            This  flag  provides  behavior that is similar to MAP_FIXED with
            respect  to  the  addr  enforcement,   but   differs   in   that
            MAP_FIXED_NOREPLACE  never  clobbers a preexisting mapped range.
            If the requested range would collide with an  existing  mapping,
            then  this  call  fails  with  the  error EEXIST.  This flag can
            therefore be used as a way to atomically (with respect to  other
            threads)  attempt  to map an address range: one thread will suc-
            ceed; all others will report failure.
            Note  that  older   kernels   which   do   not   recognize   the
            MAP_FIXED_NOREPLACE flag will typically (upon detecting a colli-
            sion with a preexisting mapping) fall back to a  "non-MAP_FIXED"
            type  of behavior: they will return an address that is different
            from  the  requested  address.   Therefore,  backward-compatible
            software should check the returned address against the requested
            address.
     MAP_GROWSDOWN
            This flag is used for stacks.  It indicates to the  kernel  vir-
            tual  memory  system  that the mapping should extend downward in
            memory.  The return address is one page lower  than  the  memory
            area  that  is actually created in the process's virtual address
            space.  Touching an address in the "guard" page below  the  map-
            ping  will cause the mapping to grow by a page.  This growth can
            be repeated until the mapping grows to within a page of the high
            end  of  the  next  lower  mapping,  at which point touching the
            "guard" page will result in a SIGSEGV signal.
     MAP_HUGETLB (since Linux 2.6.32)
            Allocate the mapping using "huge pages."  See the  Linux  kernel
            source  file Documentation/vm/hugetlbpage.txt for further infor-
            mation, as well as NOTES, below.
     MAP_HUGE_2MB, MAP_HUGE_1GB (since Linux 3.8)
            Used in  conjunction  with  MAP_HUGETLB  to  select  alternative
            hugetlb page sizes (respectively, 2 MB and 1 GB) on systems that
            support multiple hugetlb page sizes.
            More generally, the desired huge page size can be configured  by
            encoding  the  base-2  logarithm of the desired page size in the
            six bits at the offset MAP_HUGE_SHIFT.  (A value of zero in this
            bit  field provides the default huge page size; the default huge
            page size can be discovered via the Hugepagesize  field  exposed
            by  /proc/meminfo.)   Thus,  the above two constants are defined
            as:
                #define  MAP_HUGE_2MB     (21  <<  MAP_HUGE_SHIFT)   #define
                MAP_HUGE_1GB    (30 << MAP_HUGE_SHIFT)
            The  range  of  huge page sizes that are supported by the system
            can be discovered by listing  the  subdirectories  in  /sys/ker-
            nel/mm/hugepages.
     MAP_LOCKED (since Linux 2.5.37)
            Mark the mapped region to be locked in the same way as mlock(2).
            This implementation will try to populate  (prefault)  the  whole
            range  but  the  mmap()  call  doesn't  fail with ENOMEM if this
            fails.  Therefore major faults might happen later  on.   So  the
            semantic  is  not  as strong as mlock(2).  One should use mmap()
            plus mlock(2) when major faults are  not  acceptable  after  the
            initialization  of  the mapping.  The MAP_LOCKED flag is ignored
            in older kernels.
     MAP_NONBLOCK (since Linux 2.5.46)
            This flag is meaningful only in conjunction  with  MAP_POPULATE.
            Don't  perform  read-ahead:  create page tables entries only for
            pages that are already present in RAM.  Since Linux 2.6.23, this
            flag  causes  MAP_POPULATE to do nothing.  One day, the combina-
            tion of MAP_POPULATE and MAP_NONBLOCK may be reimplemented.
     MAP_NORESERVE
            Do not reserve swap space for this mapping.  When swap space  is
            reserved,  one  has  the guarantee that it is possible to modify
            the mapping.  When swap space is  not  reserved  one  might  get
            SIGSEGV  upon  a  write if no physical memory is available.  See
            also the discussion of the  file  /proc/sys/vm/overcommit_memory
            in  proc(5).   In  kernels before 2.6, this flag had effect only
            for private writable mappings.
     MAP_POPULATE (since Linux 2.5.46)
            Populate (prefault) page tables for a mapping.  For a file  map-
            ping,  this  causes  read-ahead  on the file.  This will help to
            reduce blocking on page faults later.  MAP_POPULATE is supported
            for private mappings only since Linux 2.6.23.
     MAP_STACK (since Linux 2.6.27)
            Allocate  the  mapping  at  an address suitable for a process or
            thread stack.  This flag is currently a no-op, but  is  used  in
            the glibc threading implementation so that if some architectures
            require special treatment for  stack  allocations,  support  can
            later be transparently implemented for glibc.
     MAP_SYNC (since Linux 4.15)
            This flag is available only with the MAP_SHARED_VALIDATE mapping
            type; mappings of type  MAP_SHARED  will  silently  ignore  this
            flag.   This  flag  is  supported  only for files supporting DAX
            (direct mapping of persistent memory).  For other files,  creat-
            ing a mapping with this flag results in an EOPNOTSUPP error.
            Shared  file  mappings with this flag provide the guarantee that
            while some memory is writably mapped in the address space of the
            process,  it will be visible in the same file at the same offset
            even after the system crashes or is  rebooted.   In  conjunction
            with  the  use  of  appropriate  CPU instructions, this provides
            users of such mappings with a more efficient way of making  data
            modifications persistent.
     MAP_UNINITIALIZED (since Linux 2.6.33)
            Don't  clear  anonymous pages.  This flag is intended to improve
            performance on embedded devices.  This flag is honored  only  if
            the  kernel was configured with the CONFIG_MMAP_ALLOW_UNINITIAL-
            IZED option.  Because of the security implications, that  option
            is  normally  enabled  only  on  embedded devices (i.e., devices
            where one has complete control of the contents of user  memory).
     Of  the  above  flags,  only MAP_FIXED is specified in POSIX.1-2001 and
     POSIX.1-2008.  However, most systems also support MAP_ANONYMOUS (or its
     synonym MAP_ANON).
     Memory  mapped  by  mmap()  is  preserved across fork(2), with the same
     attributes.
     A file is mapped in multiples of the page size.  For a file that is not
     a  multiple  of  the  page  size,  the  remaining memory is zeroed when
     mapped, and writes to that region are not written out to the file.  The
     effect  of changing the size of the underlying file of a mapping on the
     pages that correspond to added  or  removed  regions  of  the  file  is
     unspecified.
 munmap()
     The munmap() system call deletes the mappings for the specified address
     range, and causes further references to addresses within the  range  to
     generate  invalid  memory references.  The region is also automatically
     unmapped when the process is terminated.  On the  other  hand,  closing
     the file descriptor does not unmap the region.
     The  address  addr must be a multiple of the page size (but length need
     not be).  All pages containing  a  part  of  the  indicated  range  are
     unmapped,  and  subsequent  references  to  these  pages  will generate
     SIGSEGV.  It is not an error if the indicated range  does  not  contain
     any mapped pages.

RETURN VALUE

     On success, mmap() returns a pointer to the mapped area.  On error, the
     value MAP_FAILED (that is, (void *) -1) is returned, and errno  is  set
     to indicate the cause of the error.
     On  success,  munmap() returns 0.  On failure, it returns -1, and errno
     is set to indicate the cause of the error (probably to EINVAL).

ERRORS

     EACCES A file descriptor refers to a non-regular file.  Or a file  map-
            ping  was  requested,  but  fd  is  not  open  for  reading.  Or
            MAP_SHARED was requested and PROT_WRITE is set, but  fd  is  not
            open in read/write (O_RDWR) mode.  Or PROT_WRITE is set, but the
            file is append-only.
     EAGAIN The file has been locked, or too much  memory  has  been  locked
            (see setrlimit(2)).
     EBADF  fd  is  not  a  valid file descriptor (and MAP_ANONYMOUS was not
            set).
     EEXIST MAP_FIXED_NOREPLACE was specified in flags, and the  range  cov-
            ered by addr and length is clashes with an existing mapping.
     EINVAL We don't like addr, length, or offset (e.g., they are too large,
            or not aligned on a page boundary).
     EINVAL (since Linux 2.6.12) length was 0.
     EINVAL flags contained neither MAP_PRIVATE or MAP_SHARED, or  contained
            both of these values.
     ENFILE The system-wide limit on the total number of open files has been
            reached.
     ENODEV The underlying filesystem of the specified file does not support
            memory mapping.
     ENOMEM No memory is available.
     ENOMEM The  process's  maximum  number  of  mappings  would  have  been
            exceeded.  This error can also occur for munmap(),  when  unmap-
            ping  a  region in the middle of an existing mapping, since this
            results in two smaller mappings on either  side  of  the  region
            being unmapped.
     ENOMEM (since  Linux 4.7) The process's RLIMIT_DATA limit, described in
            getrlimit(2), would have been exceeded.
     EOVERFLOW
            On 32-bit architecture together with the  large  file  extension
            (i.e.,  using 64-bit off_t): the number of pages used for length
            plus number of pages used for  offset  would  overflow  unsigned
            long (32 bits).
     EPERM  The prot argument asks for PROT_EXEC but the mapped area belongs
            to a file on a filesystem that was mounted no-exec.
     EPERM  The operation was prevented by a file seal; see fcntl(2).
     ETXTBSY
            MAP_DENYWRITE was set but the object specified by fd is open for
            writing.
     Use of a mapped region can result in these signals:
     SIGSEGV
            Attempted write into a region mapped as read-only.
     SIGBUS Attempted access to a portion of the buffer that does not corre-
            spond to the file (for example, beyond  the  end  of  the  file,
            including  the  case  where  another  process  has truncated the
            file).

ATTRIBUTES

     For  an  explanation  of  the  terms  used   in   this   section,   see
     attributes(7).
     +-----------------+---------------+---------+
     |Interface        | Attribute     | Value   |
     +-----------------+---------------+---------+
     |mmap(), munmap() | Thread safety | MT-Safe |
     +-----------------+---------------+---------+

CONFORMING TO

     POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD.

AVAILABILITY

     On POSIX systems on which mmap(), msync(2), and munmap() are available,
     _POSIX_MAPPED_FILES is defined in <unistd.h> to a value greater than 0.
     (See also sysconf(3).)

NOTES

     On   some  hardware  architectures  (e.g.,  i386),  PROT_WRITE  implies
     PROT_READ.  It is  architecture  dependent  whether  PROT_READ  implies
     PROT_EXEC  or  not.   Portable  programs should always set PROT_EXEC if
     they intend to execute code in the new mapping.
     The portable way to create a mapping is to specify addr  as  0  (NULL),
     and  omit  MAP_FIXED  from flags.  In this case, the system chooses the
     address for the mapping; the address is chosen so as  not  to  conflict
     with any existing mapping, and will not be 0.  If the MAP_FIXED flag is
     specified, and addr is 0 (NULL), then the  mapped  address  will  be  0
     (NULL).
     Certain  flags  constants  are  defined  only  if suitable feature test
     macros are defined (possibly by default):  _DEFAULT_SOURCE  with  glibc
     2.19  or  later;  or _BSD_SOURCE or _SVID_SOURCE in glibc 2.19 and ear-
     lier.  (Employing _GNU_SOURCE also suffices, and requiring  that  macro
     specifically  would  have  been more logical, since these flags are all
     Linux-specific.)  The relevant flags are: MAP_32BIT, MAP_ANONYMOUS (and
     the   synonym   MAP_ANON),   MAP_DENYWRITE,  MAP_EXECUTABLE,  MAP_FILE,
     MAP_GROWSDOWN, MAP_HUGETLB,  MAP_LOCKED,  MAP_NONBLOCK,  MAP_NORESERVE,
     MAP_POPULATE, and MAP_STACK.
     An  application  can  determine  which pages of a mapping are currently
     resident in the buffer/page cache using mincore(2).
 Using MAP_FIXED safely
     The only safe use for MAP_FIXED is where the address range specified by
     addr  and  length was previously reserved using another mapping; other-
     wise, the use of MAP_FIXED is hazardous  because  it  forcibly  removes
     preexisting  mappings,  making  it  easy for a multithreaded process to
     corrupt its own address space.
     For example, suppose that thread A looks through  /proc/<pid>/maps  and
     in  order  to  locate  an  unused  address  range that it can map using
     MAP_FIXED, while thread B simultaneously acquires part or all  of  that
     same    address    range.    When   thread   A   subsequently   employs
     mmap(MAP_FIXED), it will effectively clobber the mapping that thread  B
     created.   In  this  scenario,  thread  B  need  not  create  a mapping
     directly; simply making a library call that, internally, uses dlopen(3)
     to  load  some  other shared library, will suffice.  The dlopen(3) call
     will map the library into the process's  address  space.   Furthermore,
     almost  any  library  call may be implemented in a way that adds memory
     mappings to the address space, either with this technique, or by simply
     allocating  memory.   Examples  include brk(2), malloc(3), pthread_cre-
     ate(3), and the PAM libraries
     Since Linux 4.17, a multithreaded program can use  the  MAP_FIXED_NORE-
     PLACE  flag to avoid the hazard described above when attempting to cre-
     ate a mapping at a fixed address that has not been reserved by a preex-
     isting mapping.
 Timestamps changes for file-backed mappings
     For file-backed mappings, the st_atime field for the mapped file may be
     updated at any time between the mmap() and the corresponding unmapping;
     the  first  reference  to a mapped page will update the field if it has
     not been already.
     The st_ctime and st_mtime field for a file mapped with  PROT_WRITE  and
     MAP_SHARED  will  be  updated  after  a write to the mapped region, and
     before a subsequent msync(2) with the MS_SYNC or MS_ASYNC flag, if  one
     occurs.
 Huge page (Huge TLB) mappings
     For mappings that employ huge pages, the requirements for the arguments
     of mmap() and munmap() differ somewhat from the requirements  for  map-
     pings that use the native system page size.
     For mmap(), offset must be a multiple of the underlying huge page size.
     The system automatically aligns length to be a multiple of the underly-
     ing huge page size.
     For munmap(), addr and length must both be a multiple of the underlying
     huge page size.
 C library/kernel differences
     This page describes the interface provided by the glibc mmap()  wrapper
     function.   Originally, this function invoked a system call of the same
     name.  Since kernel 2.4,  that  system  call  has  been  superseded  by
     mmap2(2),  and  nowadays  the  glibc  mmap()  wrapper  function invokes
     mmap2(2) with a suitably adjusted value for offset.

BUGS

     On Linux, there are no guarantees  like  those  suggested  above  under
     MAP_NORESERVE.   By  default,  any  process can be killed at any moment
     when the system runs out of memory.
     In kernels before 2.6.7, the MAP_POPULATE flag has effect only if  prot
     is specified as PROT_NONE.
     SUSv3  specifies  that  mmap() should fail if length is 0.  However, in
     kernels before 2.6.12, mmap() succeeded in this case:  no  mapping  was
     created  and the call returned addr.  Since kernel 2.6.12, mmap() fails
     with the error EINVAL for this case.
     POSIX specifies that the system shall always zero fill any partial page
     at the end of the object and that system will never write any modifica-
     tion of the object beyond its end.  On Linux, when you  write  data  to
     such  partial  page  after the end of the object, the data stays in the
     page cache even after the file is closed and unmapped and  even  though
     the  data  is never written to the file itself, subsequent mappings may
     see the modified content.  In some cases, this could be fixed by  call-
     ing  msync(2)  before the unmap takes place; however, this doesn't work
     on tmpfs(5) (for example, when using the POSIX shared memory  interface
     documented in shm_overview(7)).

EXAMPLE

     The  following  program  prints part of the file specified in its first
     command-line argument to standard output.  The range  of  bytes  to  be
     printed  is  specified  via  offset and length values in the second and
     third command-line arguments.  The program creates a memory mapping  of
     the  required  pages  of  the file and then uses write(2) to output the
     desired bytes.
 Program source
     #include <sys/mman.h> #include <sys/stat.h> #include <fcntl.h> #include
     <stdio.h> #include <stdlib.h> #include <unistd.h>
     #define handle_error(msg) \
         do { perror(msg); exit(EXIT_FAILURE); } while (0)
     int main(int argc, char *argv[]) {
         char *addr;
         int fd;
         struct stat sb;
         off_t offset, pa_offset;
         size_t length;
         ssize_t s;
         if (argc < 3 || argc > 4) {
             fprintf(stderr, "%s file offset [length]\n", argv[0]);
             exit(EXIT_FAILURE);
         }
         fd = open(argv[1], O_RDONLY);
         if (fd == -1)
             handle_error("open");
         if (fstat(fd, &sb) == -1)           /* To obtain file size */
             handle_error("fstat");
         offset = atoi(argv[2]);
         pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) - 1);
             /* offset for mmap() must be page aligned */
         if (offset >= sb.st_size) {
             fprintf(stderr, "offset is past end of file\n");
             exit(EXIT_FAILURE);
         }
         if (argc == 4) {
             length = atoi(argv[3]);
             if (offset + length > sb.st_size)
                 length = sb.st_size - offset;
                     /* Can't display bytes past end of file */
         } else {    /* No length arg ==> display to end of file */
             length = sb.st_size - offset;
         }
         addr = mmap(NULL, length + offset - pa_offset, PROT_READ,
                     MAP_PRIVATE, fd, pa_offset);
         if (addr == MAP_FAILED)
             handle_error("mmap");
         s = write(STDOUT_FILENO, addr + offset - pa_offset, length);
         if (s != length) {
             if (s == -1)
                 handle_error("write");
             fprintf(stderr, "partial write");
             exit(EXIT_FAILURE);
         }
         munmap(addr, length + offset - pa_offset);
         close(fd);
         exit(EXIT_SUCCESS); }

SEE ALSO

     ftruncate(2),  getpagesize(2),  memfd_create(2),  mincore(2), mlock(2),
     mmap2(2), mprotect(2), mremap(2), msync(2), remap_file_pages(2),  setr-
     limit(2), shmat(2), userfaultfd(2), shm_open(3), shm_overview(7)
     The  descriptions  of the following files in proc(5): /proc/[pid]/maps,
     /proc/[pid]/map_files, and /proc/[pid]/smaps.
     B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391.

COLOPHON

     This page is part of release 4.16 of the Linux  man-pages  project.   A
     description  of  the project, information about reporting bugs, and the
     latest    version    of    this    page,    can     be     found     at
     https://www.kernel.org/doc/man-pages/.

Linux 2018-04-30 MMAP(2)

/data/webs/external/dokuwiki/data/pages/man/mmap.txt · Last modified: 2019/05/17 09:47 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki