unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

MMAP(2)                       System Calls Manual                      MMAP(2)



NAME
       mmap - map pages of memory

SYNOPSIS
       #include <&lt;sys/types.h>&gt;
       #include <&lt;sys/mman.h>&gt;

       caddr_t mmap(addr, len, prot, flags, fd, off)
       caddr_t addr;
       size_t len;
       int prot, flags, fd;
       off_t off;

DESCRIPTION
       mmap()  establishes a mapping between the process's address space at an
       address pa for len bytes to the memory object represented by fd at  off
       for len bytes.  The value of pa is an implementation-dependent function
       of the parameter addr and values of flags, further described below.   A
       successful  mmap()  call  returns pa as its result.  The address ranges
       covered by [pa, pa + len) and [off, off + len) must be  legitimate  for
       the  possible  (not necessarily current) address space of a process and
       the object in question, respectively.

       The mapping established by mmap() replaces any  previous  mappings  for
       the process's pages in the range [pa, pa + len).

       close(2V)  does not unmap pages of the object referred to by a descrip-
       tor.  Use munmap(2) to remove a mapping.

       The parameter prot determines whether read,  write,  execute,  or  some
       combination  of  accesses  are permitted to the pages being mapped. The
       protection options are defined in <&lt;sys/mman.h>&gt; as:

              #define PROT_READ        0x1       /* page can be read */
              #define PROT_WRITE       0x2       /* page can be written */
              #define PROT_EXEC        0x4       /* page can be executed */
              #define PROT_NONE        0x0       /* page can not be accessed */

       Not all implementations literally provide  all  possible  combinations.
       PROT_WRITE  is  often implemented as PROT_READ|PROT_WRITE and PROT_EXEC
       as PROT_READ|PROT_EXEC.  However, no implementation will permit a write
       to  succeed  where  PROT_WRITE  has  not  been  set.   The  behavior of
       PROT_WRITE can be influenced by setting MAP_PRIVATE in the flags param-
       eter, described below.

       The  parameter  flags  provides other information about the handling of
       the mapped pages.  The options are defined in <&lt;sys/mman.h>&gt; as:

              #define MAP_SHARED       1         /* Share changes */
              #define MAP_PRIVATE      2         /* Changes are private */
              #define MAP_TYPE         0xf       /* Mask for type of mapping */
              #define MAP_FIXED        0x10      /* Interpret addr exactly */

       MAP_SHARED and MAP_PRIVATE describe the disposition of write references
       to  the  memory  object.   If MAP_SHARED is specified, write references
       will change the memory object.  If MAP_PRIVATE is specified,  the  ini-
       tial  write  reference  will create a private copy of the memory object
       page and redirect the  mapping  to  the  copy.   The  mapping  type  is
       retained across a fork(2V).

       MAP_FIXED  informs  the  system  that  the  value  of  pa must be addr,
       exactly.  The use of MAP_FIXED is discouraged, as  it  may  prevent  an
       implementation from making the most effective use of system resources.

       When  MAP_FIXED is not set, the system uses addr as a hint in an imple-
       mentation-defined manner to arrive at pa.  The pa so chosen will be  an
       area of the address space which the system deems suitable for a mapping
       of len bytes to the specified object.  All implementations interpret an
       addr value of zero as granting the system complete freedom in selecting
       pa, subject to constraints described below.  A non-zero value  of  addr
       is taken to be a suggestion of a process address near which the mapping
       should be placed.  When the system selects a  value  for  pa,  it  will
       never place a mapping at address 0, nor will it replace any extant map-
       ping, nor map into areas considered part of the potential data or stack
       ``segments''.

       The  parameter  off is constrained to be aligned and sized according to
       the value returned by getpagesize (2).  When  MAP_FIXED  is  specified,
       the  parameter  addr must also meet these constraints.  The system per-
       forms mapping operations over whole pages.  Thus, while  the  parameter
       len  need  not  meet  a  size  or alignment constraint, the system will
       include in any mapping operation any  partial  page  specified  by  the
       range [pa, pa + len).

       mmap()  allows  [pa,  pa + len) to extend beyond the end of the object,
       both at the time of the mmap() and  while  the  mapping  persists,  for
       example  if  the  file  was created just prior to the mmap() and has no
       contents, or if the file is  truncated.   Any  reference  to  addresses
       beyond the end of the object, however, will result in the delivery of a
       SIGBUS signal.

       The system will always zero-fill any partial page  at  the  end  of  an
       object.  Further, the system will never write out any modified portions
       of the last page of an object which are beyond its end.  References  to
       whole pages following the end of an object will result in a SIGBUS sig-
       nal.  SIGBUS may also be delivered on  various  filesystem  conditions,
       including quota exceeded errors.

       If  the  process  calls mlockall(3) with the MCL_FUTURE flag, the pages
       mapped by all future calls to mmap() will be locked in memory.  In this
       case, if not enough memory could be locked, mmap() fails and sets errno
       to EAGAIN.

RETURN VALUES
       mmap() returns the address at which the mapping was placed (pa) on suc-
       cess.  On failure, it returns -1 and sets errno to indicate the error.

ERRORS
       EACCES         fd was not open for read and PROT_READ or PROT_EXEC were
                      specified.

                      fd was not open for write and PROT_WRITE  was  specified
                      for a MAP_SHARED type mapping.

       EAGAIN         Some  or  all of the mapping could not be locked in mem-
                      ory.

       EBADF          fd was not open.

       EINVAL         The arguments addr (if MAP_FIXED was specified) and  off
                      were  not multiples of the page size as returned by get-
                      pagesize (2).

                      The  MAP_TYPE  field  in  flags  was  invalid   (neither
                      MAP_PRIVATE nor MAP_SHARED).

       ENODEV         fd refered to an object for which mmap() is meaningless,
                      such as a terminal.

       ENOMEM         MAP_FIXED was specified, and the  range  [addr,  addr  +
                      len)  exceeded  that  allowed for the address space of a
                      process.

                      MAP_FIXED was not specified and there  was  insufficient
                      room in the address space to effect the mapping.

       ENXIO          Addresses  in the range [off, off + len) are invalid for
                      fd.

SEE ALSO
       fork(2V), getpagesize(2), mprotect(2), munmap(2), mlockall(3)



                                21 January 1990                        MMAP(2)