Seth Woolley's Man Viewer

mmap(2) - mmap, munmap, mmap, munmap - map or unmap files or devices into memory - man 2 mmap

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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 *start, size_t length, int prot , int flags, int fd,
       off_t offset);

       int munmap(void *start, size_t length);

DESCRIPTION
       The mmap function asks to map length bytes starting  at  offset  offset
       from  the  file(1,n)  (or  other object) specified by the file(1,n) descriptor fd
       into memory, preferably at address start.  This  latter  address  is  a
       hint  only,  and is usually specified as 0.  The actual place where the
       object is mapped is returned by mmap, and is never 0.

       The prot argument describes the desired memory protection (and must not
       conflict  with the open(2,3,n) mode of the file(1,n)). It is either PROT_NONE or is
       the bitwise OR of one or more of the other PROT_* 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 parameter 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 or are to be shared with  other  references.
       It has bits

       MAP_FIXED  Do  not  select(2,7,2 select_tut)  a different address than the one specified.
                  If the specified address cannot be used, mmap will fail.  If
                  MAP_FIXED  is  specified,  start  must  be a multiple of the
                  pagesize.  Use of this option is discouraged.

       MAP_SHARED Share this mapping with all other processes  that  map  this
                  object.   Storing  to the region is equivalent to writing to
                  the file.  The  file(1,n)  may  not  actually  be  updated  until
                  msync(2) or munmap(2) are called.

       MAP_PRIVATE
                  Create  a  private  copy-on-write  mapping.   Stores  to the
                  region do not affect the original file.  It  is  unspecified
                  whether  changes  made  to  the file(1,n) after the mmap call are
                  visible in(1,8) the mapped region.

       You must specify exactly one of MAP_SHARED and MAP_PRIVATE.

       The above three flags are described in(1,8) POSIX.1b (formerly POSIX.4)  and
       SUSv2.  Linux also knows about the following non-standard flags:

       MAP_DENYWRITE
              This  flag is ignored.  (Long ago, it signalled that attempts to
              write(1,2) to the underlying file(1,n) should fail with ETXTBUSY. But this
              was a source of denial-of-service attacks.)

       MAP_EXECUTABLE
              This flag is ignored.

       MAP_NORESERVE
              (Used  together  with  MAP_PRIVATE.)  Do  not reserve swap space
              pages for this mapping. When swap space is reserved, one has the
              guarantee  that  it  is possible to modify this private copy-on-
              write(1,2) region.  When it is not reserved  one  might  get  SIGSEGV
              upon a write(1,2) when no memory is available.

       MAP_LOCKED (since Linux 2.5.37)
              Lock the pages of the mapped region into memory in(1,8) the manner of
              mlock().  This flag is ignored in(1,8) older kernels.

       MAP_GROWSDOWN
              Used for stacks. Indicates to the kernel VM system that the map-
              ping should extend downwards in(1,8) memory.

       MAP_ANONYMOUS
              The  mapping  is not backed by any file(1,n); the fd and offset argu-
              ments are ignored.  This flag in(1,8) conjunction with MAP_SHARED  is
              implemented since Linux 2.4.

       MAP_ANON
              Alias for MAP_ANONYMOUS. Deprecated.

       MAP_FILE
              Compatibility flag. Ignored.

       MAP_32BIT
              Put the mapping into the first 2GB of the process address space.
              Ignored when MAP_FIXED is set. This flag is currently only  sup-
              ported on x86-64 for 64bit programs.

       MAP_POPULATE (since Linux 2.5.46)
              Populate (prefault) pagetables.

       MAP_NONBLOCK (since Linux 2.5.46)
              Do not block on IO.

       Some systems document the additional flags MAP_AUTOGROW, MAP_AUTORESRV,
       MAP_COPY, and MAP_LOCAL.

       fd should be a valid file(1,n) descriptor, unless MAP_ANONYMOUS is  set(7,n,1 builtins),  in(1,8)
       which case the argument is ignored.

       offset  should  be  a multiple of the page size as returned by getpage-
       size(2).

       Memory mapped by mmap  is  preserved  across  fork(2),  with  the  same
       attributes.

       A  file(1,n) is mapped in(1,8) multiples of the page size. For a file(1,n) 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(1,n) of a mapping on  the
       pages  that  correspond  to  added  or  removed  regions of the file(1,n) is
       unspecified.

       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(1,n) descriptor does not unmap the region.

       The address start must be a multiple of the page size. All  pages  con-
       taining a part of the indicated range are unmapped, and subsequent ref-
       erences to these pages will generate SIGSEGV. It is not an error(8,n) if(3,n) the
       indicated range does not contain any mapped pages.

       For file-backed mappings, the st_atime field for the mapped file(1,n) may be
       updated at any time(1,2,n) between the mmap() and the corresponding unmapping;
       the  first  reference  to a mapped page will update(7,n) the field if(3,n) it has
       not been already.

       The st_ctime and st_mtime field for a file(1,n) mapped with  PROT_WRITE  and
       MAP_SHARED  will  be  updated  after  a write(1,2) to the mapped region, and
       before a subsequent msync() with the MS_SYNC or MS_ASYNC flag,  if(3,n)  one
       occurs.

RETURN VALUE
       On  success,  mmap returns a pointer to the mapped area.  On error(8,n), the
       value MAP_FAILED (that is, (void *) -1) is returned, and errno  is  set(7,n,1 builtins)
       appropriately.   On success, munmap returns 0, on failure -1, and errno
       is set(7,n,1 builtins) (probably to EINVAL).

NOTES
       It is architecture dependent whether PROT_READ  includes  PROT_EXEC  or
       not.  Portable  programs  should always set(7,n,1 builtins) PROT_EXEC if(3,n) they intend to
       execute code in(1,8) the new mapping.

ERRORS
       EACCES A file(1,n) descriptor refers to a non-regular file.  Or  MAP_PRIVATE
              was  requested,  but  fd is not open(2,3,n) for reading.  Or MAP_SHARED
              was requested and PROT_WRITE is set(7,n,1 builtins),  but  fd  is  not  open(2,3,n)  in(1,8)
              read(2,n,1 builtins)/write(1,2) (O_RDWR) mode.  Or PROT_WRITE is set(7,n,1 builtins), but the file(1,n) is
              append-only.

       EAGAIN The file(1,n) has been locked, or too much memory has been locked.

       EBADF  fd is not a valid file(1,n) descriptor  (and  MAP_ANONYMOUS  was  not
              set(7,n,1 builtins)).

       EINVAL We  don't  like  start or length or offset.  (E.g., they are too
              large, or not aligned on a PAGESIZE boundary.)

       ENFILE The system limit on the total number  of  open(2,3,n)  files  has  been
              reached.

       ENODEV The underlying filesystem of the specified file(1,n) does not support
              memory mapping.

       ENOMEM No memory is available, or the process's maximum number of  map-
              pings would have been exceeded.

       EPERM  The prot argument asks for PROT_EXEC but the mapped area belongs
              to a file(1,n) on a filesystem that was mounted no-exec.

       ETXTBSY
              MAP_DENYWRITE was set(7,n,1 builtins) but the object specified by fd is open(2,3,n) for
              writing.

       Use of a mapped region can result in(1,8) these signals:

       SIGSEGV
              Attempted write(1,2) into a region specified to mmap as read-only.

       SIGBUS Attempted access(2,5) to a portion of the buffer that does not corre-
              spond to the file(1,n) (for example, beyond  the  end  of  the  file(1,n),
              including  the  case  where  another  process  has truncated the
              file(1,n)).

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

CONFORMING TO
       SVr4, POSIX.1b (formerly POSIX.4), 4.4BSD, SUSv2.  SVr4 documents addi-
       tional  error(8,n) codes ENXIO and ENODEV.  SUSv2 documents additional error(8,n)
       codes EMFILE and EOVERFLOW.

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.

SEE ALSO
       getpagesize(2), mlock(2), mmap2(2), mremap(2), msync(2), shm_open(2)
       B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391.



Linux 2.6.7                       2004-09-11                           MMAP(2)

References for this manual (incoming links)