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
       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.  The prot argument describes
       the desired memory protection (and must not conflict  with
       the open mode of the file). 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.  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

       VATE.

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

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

       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.  The region is also automatically  unmapped  when
       the process is terminated.  On the other hand, closing the
       file descriptor does not unmap the region.



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 in read/write (O_RDWR) mode.

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

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

       Use of a mapped region can result in these signals:

       SIGSEGV
              Attempted write into a region specified to mmap  as
              read-only.

       SIGBUS Attempted  access  to  a portion of the buffer that
              where another process has truncated the file).


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.