Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

Linux 2.6 - man page for mmap (linux section 3posix)

MMAP(P) 			    POSIX Programmer's Manual				  MMAP(P)

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 shall establish a mapping between a process' address space and a file,
       shared memory object, or  typed memory object.  The format of the call is as follows:

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

       The mmap() function shall establish 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 an implementation-defined function of the
       parameter  addr and the values of flags, further described below. A successful mmap() call
       shall return pa as its result. The address range starting at pa	and  continuing  for  len
       bytes  shall be legitimate for the possible (not necessarily current) address space of the
       process. The range of bytes starting at off and continuing for len bytes shall be  legiti-
       mate for the possible (not necessarily current) offsets in the file, shared memory object,
       or    typed memory object   represented by fildes.

       If fildes represents a typed memory object opened with either the POSIX_TYPED_MEM_ALLOCATE
       flag  or the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the memory object to be mapped shall be
       that portion of the typed memory object	allocated  by  the  implementation  as	specified
       below.  In  this  case, if off is non-zero, the behavior of mmap() is undefined. If fildes
       refers to a valid typed memory object that is not accessible  from  the	calling  process,
       mmap() shall fail.

       The  mapping  established  by  mmap()  shall replace any previous mappings for those whole
       pages containing any part of the address space of the process starting at pa and  continu-
       ing 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  shall  be  supported  for regular files, shared memory objects, and
	typed memory objects.  Support for any other type of file is unspecified.

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

			      Symbolic Constant   Description
			      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 cannot support the combination of access types specified by prot, the
       call to mmap() shall fail.

       An implementation may permit accesses other than those specified by prot;     however,  if
       the  Memory Protection option is supported, the implementation shall not permit a write to
       succeed where PROT_WRITE has not been set or shall not permit any access  where	PROT_NONE
       alone  has  been  set.	The implementation shall support at least the following values of
       prot: PROT_NONE, PROT_READ, PROT_WRITE, and the	bitwise-inclusive  OR  of  PROT_READ  and
       PROT_WRITE.   If  the  Memory Protection option is not supported, the result of any access
       that conflicts with the specified protection is	undefined.  The  file  descriptor  fildes
       shall  have  been opened with read permission, regardless of the protection options speci-
       fied. If PROT_WRITE is specified, the application shall ensure that it has opened the file
       descriptor  fildes  with  write	permission  unless  MAP_PRIVATE is specified in the flags
       parameter as described below.

       The parameter flags 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>:

			      Symbolic Constant   Description
			      MAP_SHARED	  Changes are shared.
			      MAP_PRIVATE	  Changes are private.
			      MAP_FIXED 	  Interpret addr exactly.

       Implementations	that  do  not  support the Memory Mapped Files option are not required to
       support MAP_PRIVATE.

       It is implementation-defined whether MAP_FIXED shall be supported.    MAP_FIXED	shall  be
       supported on XSI-conformant systems.

       MAP_SHARED  and	MAP_PRIVATE  describe  the  disposition of write references to the memory
       object. If MAP_SHARED is specified, write references shall change the  underlying  object.
       If MAP_PRIVATE is specified, modifications to the mapped data by the calling process shall
       be visible only to the calling process and shall not change the underlying object.  It  is
       unspecified whether modifications to the underlying object done after the MAP_PRIVATE map-
       ping is established are visible through the  MAP_PRIVATE  mapping.  Either  MAP_SHARED  or
       MAP_PRIVATE can be specified, but not both. The mapping type is retained across fork().

       When  fildes represents a typed memory object opened with either the POSIX_TYPED_MEM_ALLO-
       CATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, mmap() shall, if there  are  enough
       resources  available,  map  len bytes allocated from the corresponding typed memory object
       which were not previously allocated to any process in any processor that may  access  that
       typed memory object. If there are not enough resources available, the function shall fail.
       If fildes represents a typed memory object opened with the POSIX_TYPED_MEM_ALLOCATE_CONTIG
       flag,  these allocated bytes shall be contiguous within the typed memory object. If fildes
       represents a typed memory object opened	with  the  POSIX_TYPED_MEM_ALLOCATE  flag,  these
       allocated  bytes  may  be  composed  of	non-contiguous	fragments within the typed memory
       object.	If  fildes  represents	a  typed  memory   object   opened   with   neither   the
       POSIX_TYPED_MEM_ALLOCATE_CONTIG	flag  nor  the	POSIX_TYPED_MEM_ALLOCATE  flag, len bytes
       starting at offset off within the typed memory object are mapped, exactly as when  mapping
       a file or shared memory object. In this case, if two processes map an area of typed memory
       using the same off and len values and using file descriptors that refer to the same memory
       pool  (either  from  the same port or from a different port), both processes shall map the
       same region of storage.

       When MAP_FIXED is set in the flags argument, the implementation is informed that the value
       of  pa  shall  be addr, exactly. If MAP_FIXED is set, mmap() may return MAP_FAILED and set
       errno to [EINVAL]. If a MAP_FIXED request is successful, the mapping established by mmap()
       replaces any previous mappings for the process' pages in the range [pa,pa+len).

       When  MAP_FIXED is not set, the implementation uses addr in an implementation-defined man-
       ner to arrive at pa. The pa so chosen shall be an area  of  the	address  space	that  the
       implementation  deems suitable for a mapping of len bytes to the file. All implementations
       interpret an addr value of 0 as granting the implementation complete freedom in	selecting
       pa, subject to constraints described below. A non-zero value of addr is taken to be a sug-
       gestion of a process address near which the mapping should be placed. When the implementa-
       tion  selects  a value for pa, it never places a mapping at address 0, nor does it replace
       any extant mapping.

       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
       application shall ensure that the argument addr also meets these constraints.  The  imple-
       mentation  performs mapping operations over whole pages. Thus, while the argument len need
       not meet a size or alignment constraint, the implementation shall include, in any  mapping
       operation, any partial page specified by the range [pa,pa+len).

       The  system  shall always zero-fill any partial page at the end of an object. Further, the
       system shall never write out any modified portions of the last page of an object which are
       beyond  its  end.    References within the address range starting at pa and continuing for
       len bytes to whole pages following the end of an object shall result in delivery of a SIG-
       BUS signal.

       An implementation may generate SIGBUS signals when a reference would cause an error in the
       mapped object, such as out-of-space condition.

       The mmap() function shall add an extra reference to the	file  associated  with	the  file
       descriptor  fildes  which  is not removed by a subsequent close() on that file descriptor.
       This reference shall be removed when there are no more mappings to the file.

       The st_atime field of the mapped file may be marked for update at  any  time  between  the
       mmap()  call and the corresponding munmap() call. The initial read or write reference to a
       mapped region shall 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
       shall be marked for update at some point in the interval between a write reference to  the
       mapped  region  and  the next call to msync() with MS_ASYNC or MS_SYNC for that portion of
       the file by any process. If there is no such call and if the underlying file  is  modified
       as  a  result  of  a write reference, then these fields shall be marked for update at some
       time after the write reference.

       There may be implementation-defined limits on the number of memory  regions  that  can  be
       mapped (per process or per system).

       If  such  a limit is imposed, whether the number of memory regions that can be mapped by a
       process is decreased by the use of shmat() is implementation-defined.

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

RETURN VALUE
       Upon successful completion, the mmap() function shall return the address at which the map-
       ping  was  placed ( pa); otherwise, it shall return a value of MAP_FAILED and set errno to
       indicate the error. The symbol MAP_FAILED is defined in the <sys/mman.h> header.  No  suc-
       cessful return from mmap() shall return the value MAP_FAILED.

ERRORS
       The mmap() function shall fail if:

       EACCES The  fildes  argument 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, if required by mlockall(), due to a lack
	      of resources.

       EBADF  The fildes argument is not a valid open file descriptor.

       EINVAL The addr argument (if MAP_FIXED was specified) or off is not a multiple of the page
	      size as returned by sysconf(), or is considered invalid by the implementation.

       EINVAL The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).

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

       ENODEV The fildes argument refers to a file whose type is not supported by mmap().

       ENOMEM MAP_FIXED was specified, and the range [addr,addr+len) exceeds that allowed for the
	      address  space of a process; or, if MAP_FIXED was not specified and there is insuf-
	      ficient room in the address space to effect the mapping.

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

       ENOMEM Not  enough  unallocated	memory resources remain in the typed memory object desig-
	      nated by fildes to allocate len bytes.

       ENOTSUP
	      MAP_FIXED or MAP_PRIVATE was specified in the flags argument and the implementation
	      does not support this functionality.

       The  implementation  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.

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

       ENXIO  The fildes argument refers to a typed memory object that is not accessible from the
	      calling process.

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

       The following sections are informative.

EXAMPLES
       None.

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

       Use  of	MAP_FIXED  may	result	in  unspecified  behavior  in further use of malloc() and
       shmat(). The use of MAP_FIXED is discouraged, as it may	prevent  an  implementation  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()  and  write(),  standard  input/output,  and
       shmat().

       The mmap() function allows access to resources via address space manipulations, instead of
       read()/ write(). Once a file is mapped, all a process has to do to access it  is  use  the
       data  at the address to which the file was mapped. So, using pseudo-code to illustrate the
       way in which an existing program might be changed to use mmap(), the following:

	      fildes = open(...)
	      lseek(fildes, some_offset)
	      read(fildes, buf, len)
	      /* Use data in buf. */

       becomes:

	      fildes = open(...)
	      address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
	      /* Use data at address. */

RATIONALE
       After considering several other alternatives, it was decided to adopt the  mmap()  defini-
       tion  found in SVR4 for mapping memory objects into process address spaces. The SVR4 defi-
       nition is minimal, in that it describes only what has been built, and what appears  to  be
       necessary for a general and portable mapping facility.

       Note that while mmap() was first designed for mapping files, it is actually a general-pur-
       pose mapping facility. It can be used to map  any  appropriate  object,	such  as  memory,
       files, devices, and so on, into the address space of a process.

       When a mapping is established, it is possible that the implementation may need to map more
       than is requested into the address space of the process because of hardware  requirements.
       An  application, however, cannot count on this behavior. Implementations that do not use a
       paged architecture may simply allocate a common memory region and return  the  address  of
       it;  such  implementations probably do not allocate any more than is necessary. References
       past the end of the requested area are unspecified.

       If an application requests a mapping that would overlay existing mappings in the  process,
       it  might be desirable that an implementation detect this and inform the application. How-
       ever, the default, portable (not MAP_FIXED) operation does not overlay existing	mappings.
       On  the	other hand, if the program specifies a fixed address mapping (which requires some
       implementation knowledge to determine a suitable address, if the function is supported  at
       all),  then  the program is presumed to be successfully managing its own address space and
       should be trusted when it asks to map over existing data structures.  Furthermore,  it  is
       also desirable to make as few system calls as possible, and it might be considered onerous
       to require an munmap() before an  mmap()  to  the  same	address  range.  This  volume  of
       IEEE Std 1003.1-2001  specifies	that the new mappings replace any existing mappings, fol-
       lowing existing practice in this regard.

       It is not expected, when the Memory Protection option  is  supported,  that  all  hardware
       implementations are able to support all combinations of permissions at all addresses. When
       this option is supported, implementations are required to disallow write  access  to  map-
       pings  without write permission and to disallow access to mappings without any access per-
       mission. Other than these restrictions, implementations may allow access types other  than
       those  requested  by  the  application.	For  example,  if  the	application requests only
       PROT_WRITE, the implementation may also allow read access.  A call to mmap() fails if  the
       implementation  cannot  support	allowing all the access requested by the application. For
       example, some implementations cannot support a request for both write access  and  execute
       access  simultaneously.	All  implementations supporting the Memory Protection option must
       support requests for no access, read access, write access, and both read and write access.
       Strictly  conforming  code must only rely on the required checks. These restrictions allow
       for portability across a wide range of hardware.

       The MAP_FIXED address treatment is likely to fail for non-page-aligned values and for cer-
       tain  architecture-dependent  address  ranges.  Conforming implementations cannot count on
       being able to choose address values for MAP_FIXED without utilizing  non-portable,  imple-
       mentation-defined  knowledge.  Nonetheless,  MAP_FIXED is provided as a standard interface
       conforming to existing practice for utilizing such knowledge when it is available.

       Similarly, in order to allow implementations that do not support virtual  addresses,  sup-
       port  for directly specifying any mapping addresses via MAP_FIXED is not required and thus
       a conforming application may not count on it.

       The MAP_PRIVATE function can be implemented efficiently when memory protection hardware is
       available.  When  such hardware is not available, implementations can implement such "map-
       pings" by simply making a real copy of the relevant  data  into	process  private  memory,
       though this tends to behave similarly to read().

       The  function  has been defined to allow for many different models of using shared memory.
       However, all uses are not equally portable across all machine architectures.  In  particu-
       lar,  the  mmap()  function  allows  the  system as well as the application to specify the
       address at which to map a specific region of a memory object. The most portable way to use
       the  function is always to let the system choose the address, specifying NULL as the value
       for the argument addr and not to specify MAP_FIXED.

       If it is intended that a particular region of a	memory	object	be  mapped  at	the  same
       address	in a group of processes (on machines where this is even possible), then MAP_FIXED
       can be used to pass in the desired mapping address. The system can still be used to choose
       the  desired  address  if the first such mapping is made without specifying MAP_FIXED, and
       then the resulting mapping address can be passed to subsequent processes for them to  pass
       in  via	MAP_FIXED.  The availability of a specific address range cannot be guaranteed, in
       general.

       The mmap() function can be used to map a region of memory that is larger than the  current
       size  of  the  object.  Memory access within the mapping but beyond the current end of the
       underlying objects may result in SIGBUS signals being sent to the process. The reason  for
       this  is  that the size of the object can be manipulated by other processes and can change
       at any moment. The implementation should tell the application that a memory  reference  is
       outside	the  object  where  this can be detected; otherwise, written data may be lost and
       read data may not reflect actual data in the object.

       Note that references beyond the end of the object do not extend the object as the new  end
       cannot  be  determined precisely by most virtual memory hardware. Instead, the size can be
       directly manipulated by ftruncate().

       Process memory locking does apply to shared memory regions, and the  MEMLOCK_FUTURE  argu-
       ment  to  mlockall() can be relied upon to cause new shared memory regions to be automati-
       cally locked.

       Existing implementations of mmap() return the value -1 when unsuccessful. Since the  cast-
       ing of this value to type void * cannot be guaranteed by the ISO C standard to be distinct
       from  a	successful  value,  this  volume  of  IEEE Std 1003.1-2001  defines  the   symbol
       MAP_FAILED,  which a conforming implementation does not return as the result of a success-
       ful call.

FUTURE DIRECTIONS
       None.

SEE ALSO
       exec()  ,  fcntl()  ,  fork()  ,  lockf()  ,   msync()	,   munmap()   ,   mprotect()	,
       posix_typed_mem_open()	,   shmat()   ,  sysconf()  ,  the  Base  Definitions  volume  of
       IEEE Std 1003.1-2001, <sys/mman.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					  MMAP(P)


All times are GMT -4. The time now is 07:14 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password