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

FreeBSD Manual Pages


home | help
MMAP(2)			    BSD	System Calls Manual		       MMAP(2)

     mmap -- map files or devices into memory

     Standard C	Library	(libc, -lc)

     #include <sys/mman.h>

     void *
     mmap(void *addr, size_t len, int prot, int	flags, int fd, off_t offset);

     The mmap function causes the pages	starting at addr and continuing	for at
     most len bytes to be mapped from the object described by fd, starting at
     byte offset offset.  If len is not	a multiple of the pagesize, the	mapped
     region may	extend past the	specified range.  Any such extension beyond
     the end of	the mapped object will be zero-filled.

     If	addr is	non-zero, it is	used as	a hint to the system.  (As a conve-
     nience to the system, the actual address of the region may	differ from
     the address supplied.)  If	addr is	zero, an address will be selected by
     the system.  The actual starting address of the region is returned.  A
     successful	mmap deletes any previous mapping in the allocated address

     The protections (region accessibility) are	specified in the prot argument
     by	OR'ing the following values:

	   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.

     Note that,	due to hardware	limitations, on	some platforms PROT_WRITE may
     imply PROT_READ, and PROT_READ may	imply PROT_EXEC.  Portable programs
     should not	rely on	these flags being separately enforceable.

     The flags parameter specifies the type of the mapped object, mapping op-
     tions and whether modifications made to the mapped	copy of	the page are
     private to	the process or are to be shared	with other references.	Note
     that either MAP_SHARED or MAP_PRIVATE must	be specified.  Sharing,	map-
     ping type and options are specified in the	flags argument by OR'ing the
     following values:

	   MAP_ALIGNED(n)      Request that the	allocation be aligned to the
			       given boundary.	The parameter n	should be the
			       base 2 logarithm	of the desired alignment
			       (e.g., to request alignment to 16K, use 14 as
			       the value for n).  The alignment	must be	equal
			       to or greater than the platform's page size as
			       returned	by sysconf(3) with the _SC_PAGESIZE

	   MAP_ANON	       Map anonymous memory not	associated with	any
			       specific	file.  The file	descriptor is not used
			       for creating MAP_ANON regions, and must be
			       specified as -1.	 The mapped memory will	be
			       zero filled.

	   MAP_FILE	       Mapped from a regular file or character-special
			       device memory.

	   MAP_FIXED	       Do not permit the system	to select a different
			       address than the	one specified.	If the speci-
			       fied address cannot be used, mmap will fail.
			       If MAP_FIXED is specified, addr must be a mul-
			       tiple of	the pagesize.  Use of this option is

	   MAP_HASSEMAPHORE    Notify the kernel that the region may contain
			       semaphores and that special handling may	be

	   MAP_INHERIT	       Permit regions to be inherited across execve(2)
			       system calls.

	   MAP_TRYFIXED	       Attempt to use the address addr even if it
			       falls within the	normally protected process
			       data or text segment memory regions.  If	the
			       requested region	of memory is actually present
			       in the memory map, a different address will be
			       selected	as if MAP_TRYFIXED had not been	speci-
			       fied.  If addr is NULL, this flag is ignored
			       and the system will select a mapping address.

	   MAP_WIRED	       Lock the	mapped region into memory as with

	   MAP_PRIVATE	       Modifications made by this process are private,
			       however modifications made by other processes
			       using MAP_SHARED	will be	seen.

	   MAP_SHARED	       Modifications are shared.

     The close(2) function does	not unmap pages, see munmap(2) for further in-

     The current design	does not allow a process to specify the	location of
     swap space.  In the future	we may define an additional mapping type,
     MAP_SWAP, in which	the file descriptor argument specifies a file or de-
     vice to which swapping should be done.

     If	MAP_FIXED is not specified, the	system will attempt to place the map-
     ping in an	unused portion of the address space chosen to minimize possi-
     ble collision between mapped regions and the heap.

     Upon successful completion, mmap returns a	pointer	to the mapped region.
     Otherwise,	a value	of MAP_FAILED is returned and errno is set 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.

     mmap() will fail if:

     [EACCES]		The flag PROT_READ was specified as part of the	prot
			parameter and fd was not open for reading.  The	flags
			MAP_SHARED and PROT_WRITE were specified as part of
			the flags and prot parameters and fd was not open for

     [EBADF]		fd is not a valid open file descriptor.

     [EINVAL]		MAP_FIXED was specified	and the	addr parameter was not
			page aligned or	was outside of the valid address range
			for a process.	MAP_ANON was specified and fd was not

     [ENODEV]		fd did not reference a regular or character special

     [ENOMEM]		MAP_FIXED was specified	and the	addr parameter wasn't
			available.  MAP_ANON was specified and insufficient
			memory was available.

     [EOVERFLOW]	fd references a	regular	file and the value of offset
			plus len would exceed the offset maximum established
			in its open file description.

     madvise(2), mincore(2), mlock(2), mprotect(2), msync(2), munmap(2),
     getpagesize(3), sysconf(3)

     The mmap()	function conforms to IEEE Std 1003.1b-1993 ("POSIX.1").

     The mmap()	interface was first designed in	4.2BSD.

BSD			       December	20, 2011			   BSD


Want to link to this manual page? Use this URL:

home | help