GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:munmap

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).
     allbox;  lbw18  lb lb l l l.  Interface Attribute Value T{ mmap(), mun-
     map() T}   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/munmap.txt · Last modified: 2019/05/17 09:32 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki