Unix/Linux Go Back    


OpenSolaris 2009.06 - man page for mmap (opensolaris section 2)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


mmap(2)  				   System Calls 				    mmap(2) 

NAME
       mmap - map pages of memory

SYNOPSIS
       #include <sys/mman.h>

       void *mmap(void *addr, size_t len, int prot, int flags,
	    int fildes, off_t off);

DESCRIPTION
       The  mmap() function establishes a mapping between a process's address space and a file or
       shared memory object. The format of the call is as follows:

       pa = mmap(addr, len, prot, flags, fildes, off);

       The mmap() function establishes a mapping between the address space of the process  at  an
       address pa for len bytes to the memory object represented by the file descriptor fildes at
       offset off for len bytes. The value of pa is a function of the  addr argument  and  values
       of  flags, further described below. A successful mmap() call returns pa as its result. The
       address range starting at pa and continuing for len bytes will be legitimate for the  pos-
       sible  (not necessarily current) address space of the process. The range of bytes starting
       at off and continuing for len bytes will be legitimate for the possible	(not  necessarily
       current) offsets in the file or shared memory object represented by fildes.

       The  mmap()  function allows [pa, pa + len) to extend beyond the end of the object both at
       the time of the mmap() and while the mapping persists, such as when the	file  is  created
       prior to the mmap() call and has no contents, or when the file is truncated. Any reference
       to addresses beyond the end of the object, however, will result in the delivery of a  SIG-
       BUS  or SIGSEGV signal. The mmap() function cannot be used to implicitly extend the length
       of files.

       The mapping established by mmap() replaces any previous mappings  for  those  whole  pages
       containing  any part of the address space of the process starting at pa and continuing for
       len bytes.

       If the size of the mapped file changes after the call to mmap() as a result of some  other
       operation  on  the  mapped file, the effect of references to portions of the mapped region
       that correspond to added or removed portions of the file is unspecified.

       The mmap() function is supported for regular files and shared memory objects. Support  for
       any other type of file is unspecified.

       The   prot  argument  determines  whether  read,  write,  execute,  or some combination of
       accesses are permitted to the data being  mapped.  The  prot  argument  should  be  either
       PROT_NONE  or  the bitwise inclusive OR of one or more of the other flags in the following
       table, defined in the header <sys/mman.h>.

       PROT_READ     Data can be read.

       PROT_WRITE    Data can be written.

       PROT_EXEC     Data can be executed.

       PROT_NONE     Data cannot be accessed.

       If an implementation of mmap() for a specific platform cannot support the  combination  of
       access  types  specified  by  prot, the call to mmap() fails. An implementation may permit
       accesses other than those specified by prot; however, the implementation will not permit a
       write  to  succeed  where PROT_WRITE has not been set or permit any access where PROT_NONE
       alone has been set. Each platform-specific implementation of mmap() supports the following
       values  of  prot:  PROT_NONE, PROT_READ, PROT_WRITE, and the inclusive OR of PROT_READ and
       PROT_WRITE. On  some  platforms,  the  PROT_WRITE  protection  option  is  implemented  as
       PROT_READ|PROT_WRITE  and  PROT_EXEC as PROT_READ|PROT_EXEC. The file descriptor fildes is
       opened with read permission, regardless of the protection options specified. If PROT_WRITE
       is  specified, the application must have opened the file descriptor fildes with write per-
       mission unless MAP_PRIVATE is specified in the flags argument as described below.

       The  flags argument provides other information about the handling of the mapped data.  The
       value of flags is the bitwise inclusive OR of these options, defined in <sys/mman.h>:

       MAP_SHARED	Changes are shared.

       MAP_PRIVATE	Changes are private.

       MAP_FIXED	Interpret addr exactly.

       MAP_NORESERVE	Do not reserve swap space.

       MAP_ANON 	Map anonymous memory.

       MAP_ALIGN	Interpret addr as required aligment.

       MAP_TEXT 	Map text.

       MAP_INITDATA	Map initialized data segment.

       The MAP_SHARED and MAP_PRIVATE options describe the disposition of write references to the
       underlying object. If MAP_SHARED is specified, write references	will  change  the  memory
       object.	If  MAP_PRIVATE  is  specified, the initial write reference will create a private
       copy of the memory object page and redirect the mapping to the copy. The private  copy  is
       not  created  until  the  first	write; until then, other users who have the object mapped
       MAP_SHARED can change the object. Either MAP_SHARED or MAP_PRIVATE must be specified,  but
       not both. The mapping type is retained across   fork(2) .

       When  MAP_FIXED	is set in the flags argument, the system is informed that the value of pa
       must be addr, exactly. If MAP_FIXED is set, mmap() may return (void *)-1 and set errno  to
       EINVAL.	 If a MAP_FIXED request is successful, the mapping established by mmap() replaces
       any previous mappings for the process's pages in the range [pa, pa  +  len).  The  use  of
       MAP_FIXED is discouraged, since it may prevent a system from making the most effective use
       of its resources.

       When MAP_FIXED is set and the requested address is the same as previous mapping, the  pre-
       vious address is unmapped and the new mapping is created on top of the old one.

       When  MAP_FIXED is not set, the system uses addr to arrive at pa. The pa so chosen will be
       an area of the address space that the system deems suitable for a mapping of len bytes  to
       the  file.  The	mmap() function interprets an addr value of 0 as granting the system com-
       plete 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 mapping, nor map into areas considered part of the
       potential data or stack "segments".

       When MAP_ALIGN is set, the system is informed that the alignment of pa must be the same as
       addr.  The alignment value in addr must be 0 or some power of two multiple of page size as
       returned by   sysconf(3C) . If addr is 0, the system will choose a suitable  alignment.

       The MAP_NORESERVE option specifies that no swap space be reserved for a	mapping.  Without
       this flag, the creation of a writable MAP_PRIVATE mapping reserves swap space equal to the
       size of the mapping; when the mapping is written into, the reserved space is  employed  to
       hold  private  copies  of  the data. A write into a MAP_NORESERVE mapping produces results
       which depend on the current availability of swap  space in the system.  If space is avail-
       able,  the  write succeeds and a  private copy of the written page is created; if space is
       not available, the write fails and a SIGBUS or SIGSEGV signal is delivered to the  writing
       process.   MAP_NORESERVE mappings are inherited across  fork(); at the time of the fork(),
       swap space is reserved in the child for all private pages that currently exist in the par-
       ent; thereafter the child's mapping behaves as described above.

       When  MAP_ANON  is set in flags, and fildes is set to -1, mmap() provides a direct path to
       return anonymous pages to the caller.  This operation is equivalent to passing  mmap()  an
       open file descriptor on /dev/zero with MAP_ANON elided from the flags argument.

       The  MAP_TEXT  option informs the system that the mapped region will be used primarily for
       executing instructions. This information can help the system better utilize MMU	resources
       on some platforms. This flag is always passed by the dynamic linker when it maps text seg-
       ments of shared objects. When the MAP_TEXT option is used for  regular  file  mappings  on
       some platforms, the system can choose a mapping size larger than the page size returned by
         sysconf(3C) . The specific page sizes that are used depend on the platform and  the  align-
       ment  of the addr and len arguments. Several diffrent mapping sizes can be used to map the
       region with larger page sizes used in the parts of the region that meet alignment and size
       requirements for those page sizes.

       The  MAP_INITDATA  option informs the system that the mapped region is an initialized data
       segment of an executable or shared object. When the MAP_INITDATA option is used for  regu-
       lar  file mappings on some platforms, the system can choose a mapping size larger than the
       page size returned by sysconf(). The MAP_INITDATA  option  should  be  used  only  by  the
       dynamic linker for mapping initialized data of shared objects.

       The off argument is constrained to be aligned and sized according to the value returned by
       sysconf() when passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, the addr
       argument  must  also  meet  these constraints. The system performs mapping operations over
       whole pages. Thus, while the  len argument 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).

       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
       the  delivery of a SIGBUS or SIGSEGV signal. SIGBUS signals may also be delivered on vari-
       ous file system conditions, including quota exceeded errors.

       The mmap() function adds an extra reference to the file associated with the file  descrip-
       tor  fildes  which  is not removed by a subsequent   close(2)  on that file descriptor.  This
       reference is removed when there are no more mappings to the file by a  call  to	the  mun-
         map(2)  function.

       The  st_atime  field  of  the mapped file may be marked for update at any time between the
       mmap() call and the corresponding   munmap(2)  call.  The initial read or write reference  to
       a mapped region will cause the file's st_atime field to be marked for update if it has not
       already been marked for update.

       The st_ctime and st_mtime fields of a file that is mapped with MAP_SHARED and  PROT_WRITE,
       will  be  marked for update at some point in the interval between a write reference to the
       mapped region and the next call to   msync(3C)  with MS_ASYNC or MS_SYNC for that portion  of
       the  file by any process.  If there is no such call, these fields may be marked for update
       at any time after a write reference if the underlying file is modified as a result.

       If the process calls   mlockall(3C)  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.

       The mmap() function aligns based on the length of the mapping. When determining the amount
       of  space  to add to the address space, mmap() includes two 8-Kbyte pages, one at each end
       of the mapping that are not mapped and are therefore used as "red-zone" pages. Attempts to
       reference these pages result in access violations.

       The  size requested is incremented by the 16 Kbytes for these pages and is then subject to
       rounding constraints. The constraints are:

	   o	  For 32-bit processes:

		    If length > 4 Mbytes
			    round to 4-Mbyte multiple
		    elseif length > 512 Kbytes
			    round to 512-Kbyte multiple
		    else
			    round to 64-Kbyte multiple

	   o	  For 64-bit processes:

		    If length > 4 Mbytes
			    round to 4-Mbyte multiple
		    else
			    round to 1-Mbyte multiple

       The net result is that for a 32-bit process:

	   o	  If an mmap() request is made for 4 Mbytes, it results in 4 Mbytes +  16  Kbytes
		  and is rounded up to 8 Mbytes.

	   o	  If  an  mmap()  request  is  made for 512 Kbytes, it results in 512 Kbytes + 16
		  Kbytes and is rounded up to 1 Mbyte.

	   o	  If an mmap() request is made for 1 Mbyte, it results in 1 Mbyte + 16 Kbytes and
		  is rounded up to 1.5 Mbytes.

	   o	  Each 8-Kbyte mmap request "consumes" 64 Kbytes of virtual address space.

       To obtain maximal address space usage for a 32-bit process:

	   o	  Combine 8-Kbyte requests up to a limit of 48 Kbytes.

	   o	  Combine amounts over 48 Kbytes into 496-Kbyte chunks.

	   o	  Combine amounts over 496 Kbytes into 4080-Kbyte chunks.

       To obtain maximal address space usage for a 64-bit process:

	   o	  Combine amounts < 1008 Kbytes into chunks <= 1008 Kbytes.

	   o	  Combine amounts over 1008 Kbytes into 4080-Kbyte chunks.

       The following is the output from a 32-bit program demonstrating this:

       map 8192 bytes: 0xff390000
       map 8192 bytes: 0xff380000

	   64-Kbyte delta between starting addresses.

       map 512 Kbytes: 0xff180000
       map 512 Kbytes: 0xff080000

	   1-Mbyte delta between starting addresses.

       map 496 Kbytes: 0xff000000
       map 496 Kbytes: 0xfef80000

	   512-Kbyte delta between starting addresses

       map 1 Mbyte: 0xfee00000
       map 1 Mbyte: 0xfec80000

	   1536-Kbyte delta between starting addresses

       map 1008 Kbytes: 0xfeb80000
       map 1008 Kbytes: 0xfea80000

	   1-Mbyte delta between starting addresses

       map 4 Mbytes: 0xfe400000
       map 4 Mbytes: 0xfdc00000

	   8-Mbyte delta between starting addresses

       map 4080 Kbytes: 0xfd800000
       map 4080 Kbytes: 0xfd400000

	   4-Mbyte delta between starting addresses

       The following is the output of the same program compiled as a 64-bit application:

       map 8192 bytes: 0xffffffff7f000000
       map 8192 bytes: 0xffffffff7ef00000

	   1-Mbyte delta between starting addresses

       map 512 Kbytes: 0xffffffff7ee00000
       map 512 Kbytes: 0xffffffff7ed00000

	   1-Mbyte delta between starting addresses

       map 496 Kbytes: 0xffffffff7ec00000
       map 496 Kbytes: 0xffffffff7eb00000

	   1-Mbyte delta between starting addresses

       map 1 Mbyte: 0xffffffff7e900000
       map 1 Mbyte: 0xffffffff7e700000

	   2-Mbyte delta between starting addresses

       map 1008 Kbytes: 0xffffffff7e600000
       map 1008 Kbytes: 0xffffffff7e500000

	   1-Mbyte delta between starting addresses

       map 4 Mbytes: 0xffffffff7e000000
       map 4 Mbytes: 0xffffffff7d800000

	   8-Mbyte delta between starting addresses

       map 4080 Kbytes: 0xffffffff7d400000
       map 4080 Kbytes: 0xffffffff7d000000

	   4-Mbyte delta between starting addresses

RETURN VALUES
       Upon  successful  completion, the mmap() function returns the address at which the mapping
       was placed (pa); otherwise, it returns a value of MAP_FAILED and sets  errno  to  indicate
       the  error.  The  symbol  MAP_FAILED  is defined in the header <sys/mman.h>. No successful
       return from mmap() will return the value MAP_FAILED.

       If mmap() fails for reasons other than EBADF, EINVAL or ENOTSUP, some of the  mappings  in
       the address range starting at addr and continuing for len bytes may have been unmapped.

ERRORS
       The mmap() function will fail if:

       EACCES	    The fildes file descriptor is not open for read, regardless of the protection
		    specified; or fildes is not open for write and PROT_WRITE was specified for a
		    MAP_SHARED type mapping.

       EAGAIN	    The mapping could not be locked in memory.

		    There was insufficient room to reserve swap space for the mapping.

       EBADF	    The fildes file descriptor is not open (and MAP_ANON was not specified).

       EINVAL	    The  arguments  addr (if MAP_FIXED was specified) or off are not multiples of
		    the page size as returned by sysconf().

		    The argument addr (if MAP_ALIGN was specified) is not 0 or some power of  two
		    multiple of page size as returned by   sysconf(3C) .

		    MAP_FIXED and MAP_ALIGN are both specified.

		    The field in flags is invalid (neither MAP_PRIVATE or MAP_SHARED is set).

		    The argument len has a value equal to 0.

		    MAP_ANON was specified, but the file descriptor was not -1.

		    MAP_TEXT was specified but PROT_EXEC was not.

		    MAP_TEXT and MAP_INITDATA were both specified.

       EMFILE	    The  number  of mapped regions would exceed an implementation-dependent limit
		    (per process or per system).

       ENODEV	    The fildes argument refers to an object for which mmap() is meaningless, such
		    as a terminal.

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

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

		    The  mapping  could  not  be  locked  in memory, if required by   mlockall(3C) ,
		    because it would require more space than the system is able to supply.

		    The composite size of len plus the lengths obtained from all  previous  calls
		    to mmap() exceeds RLIMIT_VMEM (see	  getrlimit(2) ).

       ENOTSUP	    The system does not support the combination of accesses requested in the prot
		    argument.

       ENXIO	    Addresses in the range [off, off + len) are invalid for the object	specified
		    by fildes.

		    The  MAP_FIXED option was specified in flags and the combination of addr, len
		    and off is invalid for the object specified by fildes.

       EOVERFLOW    The file is a regular file and the value of off plus len exceeds  the  offset
		    maximum establish in the open file description associated with fildes.

       The mmap() function may fail if:

       EAGAIN	 The file to be mapped is already locked using advisory or mandatory record lock-
		 ing. See   fcntl(2) .

USAGE
       Use of mmap() may reduce the amount of memory available to other memory	allocation  func-
       tions.

       MAP_ALIGN is useful to assure a properly aligned value of pa for subsequent use with memc-
         ntl(2)  and the MC_HAT_ADVISE command. This is best used for large, long-lived, and heavily
       referenced regions. MAP_FIXED and MAP_ALIGN are always mutually-exclusive.

       Use  of	MAP_FIXED  may	result in unspecified behavior in further use of   brk(2) ,   sbrk(2) ,
         malloc(3C) , and   shmat(2) . The use of MAP_FIXED is discouraged, as it may prevent an imple-
       mentation from making the most effective use of resources.

       The  application must ensure correct synchronization when using mmap() in conjunction with
       any other file access method, such as   read(2)  and    write(2) ,  standard  input/output,  and
         shmat(2) .

       The mmap() function has a transitional interface for 64-bit file offsets.  See   lf64(5) .

       The  mmap()  function allows access to resources using address space manipulations instead
       of the read()/write() interface. Once a file is mapped, all a process has to do to  access
       it is use the data at the address to which the object was mapped.

       Consider the following pseudo-code:

	 fildes = open(...)
	 lseek(fildes, offset, whence)
	 read(fildes, buf, len)
	 /* use data in buf */

       The following is a rewrite using  mmap():

	 fildes = open(...)
	 address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
		   MAP_PRIVATE, fildes, offset)
	 /* use data at address */

ATTRIBUTES
       See   attributes(5)  for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-Signal-Safe 	   |
       +-----------------------------+-----------------------------+

SEE ALSO
         close(2) ,    exec(2) ,    fcntl(2) ,   fork(2) ,   getrlimit(2) ,   memcntl(2) ,   mmapobj(2) ,   mprotect(2) ,
         munmap(2) ,    shmat(2) ,    lockf(3C) ,     mlockall(3C) ,     msync(3C) ,	  plock(3C) ,     sysconf(3C) ,
         attributes(5) ,   lf64(5) ,   standards(5) ,   null(7D) ,   zero(7D) 

SunOS 5.11				    4 Feb 2009					    mmap(2)
Unix & Linux Commands & Man Pages : ©2000 - 2017 Unix and Linux Forums


All times are GMT -4. The time now is 05:02 AM.