Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
mmap(2)								       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);

       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	repre-
       sented 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 re-
       sult.  The  address  range  starting at pa and continuing for len bytes
       will 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 will be legitimate	for the	possible (not necessarily cur-
       rent)  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 per-
       sists, 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 ad-
       dresses beyond the end of the object, however, will result in  the  de-
       livery  of  a  SIGBUS  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	refer-
       ences to	portions of the	mapped region that correspond to added or  re-
       moved 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 de-
       scriptor	fildes is opened with read permission, regardless of the  pro-
       tection	options	specified. If PROT_WRITE is specified, the application
       must have opened	the file descriptor fildes with	write  permission  un-
       less 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 spec-
       ified, 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 previous address is	unmapped and the new mapping  is  cre-
       ated 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  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  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 map-
       ping  reserves  swap  space  equal to the size of the mapping; when the
       mapping is written into,	the reserved space  is employed	to  hold  pri-
       vate  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 available,	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 parent; thereafter the	 child's  map-
       ping 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 segments of
       shared objects. When the	MAP_TEXT option	is used	for regular file  map-
       pings  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 alignment 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 regular file  mappings  on  some	 plat-
       forms,  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	opera-
       tion, any partial page specified	by the range [pa, pa + len).

       The  system will	always zero-fill any partial page at the end of	an ob-
       ject. 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
       various file system conditions, including quota exceeded	errors.

       The mmap() function adds	an extra reference to the file associated with
       the  file  descriptor  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 munmap(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 de-
       termining  the  amount of space to add to the address space, mmap() in-
       cludes 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	refer-
       ence 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

       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.

       The mmap() function will	fail if:

       EACCES	       The fildes file descriptor is not open  for  read,  re-
		       gardless	 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 implemen-
		       tation-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 in-
		       sufficient room in the address space to effect the map-
		       ping.

		       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 ob-
		       ject 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 locking. See	fcntl(2).

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

       MAP_ALIGN is useful to assure a properly	aligned	value of pa for	subse-
       quent use with memcntl(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 dis-
       couraged, as it may prevent an implementation from making the most  ef-
       fective 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 off-
       sets.  See lf64(5).

       The mmap() function allows access to resources using address space  ma-
       nipulations  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 ad-
       dress 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 */

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

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

       close(2),  exec(2),  fcntl(2), fork(2), getrlimit(2), memcntl(2), mpro-
       tect(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)

				  7 Apr	2005			       mmap(2)

NAME | SYNOPSIS | USAGE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mmap&sektion=2&manpath=SunOS+5.10>

home | help