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 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

       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.