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

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

SYNOPSIS
       #include <unistd.h>
       #include <sys/mman.h>

       #ifdef _POSIX_MAPPED_FILES

       void  *  mmap(void  *start,  size_t length, int prot , int
       flags, int fd, off_t offset);

       int munmap(void *start, size_t length);

       #endif

DESCRIPTION
       The mmap function asks to map  length  bytes  starting  at
       offset offset from the file (or other object) specified by
       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.  The prot argument describes the desired memory pro-
       tection. It has bits

       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 specified address cannot  be
                  used,  mmap  will fail.  If MAP_FIXED is speci-
                  fied, 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

       MAP_PRIVATE
                  Create a private copy-on-write mapping.

       You must specify exactly one of  MAP_SHARED  and  MAP_PRI-
       VATE.

       The  above three flags are described in POSIX.1b (formerly
       POSIX.4).  Linux also knows about MAP_DENYWRITE,  MAP_EXE-
       CUTABLE and MAP_ANON(YMOUS).

       The munmap system call deletes the mappings for the speci-
       fied address  range,  and  causes  further  references  to
       addresses within the range to generate invalid memory ref-
       erences.

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

ERRORS
       EBADF  fd  is  not a valid file descriptor (and MAP_ANONY-
              MOUS was not set).

       EACCES MAP_PRIVATE was asked, but fd is not open for read-
              ing.   Or  MAP_SHARED  was  asked and PROT_WRITE is
              set, fd is not open for writing.

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

       ETXTBUSY
              MAP_DENYWRITE was set but the object  specified  by
              fd is open for writing.

       EAGAIN The  file  has  been locked, or too much memory has
              been locked.

       ENOMEM No memory is available.

CONFORMING TO
       SVr4, POSIX.1b (formerly POSIX.4), 4.4BSD.  Svr4 documents
       additional error codes ENXIO and ENODEV.

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

Linux 1.3.86              12 April 1996                         1