Provided by: manpages-dev_2.17-1_all bug

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  (or  other object) specified by the file 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 mode of the file). 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  a different address than the one specified.
                  If the memory region specified by  start  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.  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  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 after the mmap()  call  are
                  visible in the mapped region.

       You must specify exactly one of MAP_SHARED and MAP_PRIVATE.

       The  above three flags are described in 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 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_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  region.   When  it  is not reserved one might get SIGSEGV
              upon a write when no memory is available.

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

       MAP_GROWSDOWN
              Used  for  stacks.  Indicates  to  the kernel VM system that the
              mapping should extend downwards in memory.

       MAP_ANONYMOUS
              The mapping is not  backed  by  any  file;  the  fd  and  offset
              arguments are ignored.  This flag in 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
              supported 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 descriptor, unless MAP_ANONYMOUS is set, in
       which case the argument is ignored.

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

       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.

       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  start  must  be  a  multiple  of the page size. 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.

       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() with the MS_SYNC or MS_ASYNC flag, if one
       occurs.

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
       appropriately.  On success, munmap() returns  0,  on  failure  -1,  and
       errno is set (probably to EINVAL).

NOTES

       It  is  architecture  dependent whether PROT_READ includes PROT_EXEC or
       not. Portable programs should always set PROT_EXEC if  they  intend  to
       execute code in the new mapping.

ERRORS

       EACCES A  file descriptor refers to a non-regular file.  Or MAP_PRIVATE
              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).

       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  files  has  been
              reached.

       ENODEV The underlying filesystem of the specified file does not support
              memory mapping.

       ENOMEM No memory is available,  or  the  process’s  maximum  number  of
              mappings would have been exceeded.

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

       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
              correspond to the file (for example, beyond the end of the file,
              including  the  case  where  another  process  has truncated the
              file).

AVAILABILITY

       On POSIX systems on which mmap(), msync() and munmap()  are  available,
       _POSIX_MAPPED_FILES is defined in <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
       additional  error  codes  ENXIO and ENODEV.  SUSv2 documents additional
       error 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.

       In kernels before 2.6.7, the MAP_POPULATE flag only has effect if  prot
       is specified as PROT_NONE.

SEE ALSO

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