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

FreeBSD Manual Pages


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

     mmap -- map files or devices into memory

     #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 contents of	fd, starting at	offset,	to be
     mapped in memory at the given addr.  The mapping will extend at least len
     bytes, subject to page alignment restrictions.

     The addr argument describes the address where the system should place the
     mapping.  If the MAP_FIXED	flag is	specified, the allocation will happen
     at	the specified address, replacing any previously	established mappings
     in	its range.  Otherwise, the mapping will	be placed at the available
     spot at addr; failing that	it will	be placed "close by".  If addr is NULL
     the system	can pick any address.  Except for MAP_FIXED mappings, the sys-
     tem will never replace existing mappings.

     The len argument describes	the minimum amount of bytes the	mapping	will
     span.  Since mmap() maps pages into memory, len may be rounded up to hit
     a page boundary.  If len is 0, the	mapping	will fail with EINVAL.

     If	an fd and offset are specified,	the resulting address may end up not
     on	a page boundary, in order to align the page offset in the addr to the
     page offset in offset.

     The protections (region accessibility) are	specified in the prot argu-
     ment.  It should either be	PROT_NONE (no permissions) or the bitwise OR
     of	one or more of the following values:

	   PROT_EXEC	 Pages may be executed.
	   PROT_READ	 Pages may be read.
	   PROT_WRITE	 Pages may be written.

     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.	Shar-
     ing, mapping type,	and options are	specified in the flags argument	by
     OR'ing the	following values.  Exactly one of the first two	values must be

	   MAP_PRIVATE	  Modifications	are private.

	   MAP_SHARED	  Modifications	are shared.

     Any combination of	the following flags may	additionally be	used:

	   MAP_ANON	  Map anonymous	memory not associated with any spe-
			  cific	file.  The file	descriptor used	for creating
			  MAP_ANON must	currently be -1	indicating no name is
			  associated with the region.

	   MAP_ANONYMOUS  Synonym for MAP_ANON.

	   MAP_FIXED	  Demand that the mapping is placed at addr, rather
			  than having the system select	a location.  addr, len
			  and offset (in the case of fd	mappings) must be mul-
			  tiples of the	page size.  Existing mappings in the
			  address range	will be	replaced.  Use of this option
			  is discouraged.

	   MAP_STACK	  Indicate that	the mapping is used as a stack.	 This
			  flag must be used in combination with	MAP_ANON and

	   MAP_CONCEAL	  Exclude the mapping from core	dumps.

     Finally, the following flags are also provided for	source compatibility
     with code written for other operating systems, but	are not	recommended
     for use in	new OpenBSD code:

	   MAP_COPY	  Modifications	are private and, unlike	MAP_PRIVATE,
			  modifications	made by	others are not visible.	 On
			  OpenBSD this behaves just like MAP_PRIVATE.

	   MAP_FILE	  Mapped from a	regular	file, character	special	file,
			  or block special file	specified by file descriptor
			  fd.  On OpenBSD and all systems conforming to	IEEE
			  Std 1003.1-2008 ("POSIX.1") this is the default map-
			  ping type and	need not be specified.

			  Notify the kernel that the region may	contain	sema-
			  phores and that special handling may be necessary.
			  On OpenBSD this flag is ignored.

	   MAP_INHERIT	  Permit regions to be inherited across	execve(2) sys-
			  tem calls.  On OpenBSD this flag is ignored.

	   MAP_TRYFIXED	  Attempt to use the hint provided by addr.  On
			  OpenBSD this is the default behavior.

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

     The mmap()	function returns a pointer to the mapped region	if successful;
     otherwise the value MAP_FAILED is returned	and the	global variable	errno
     is	set to indicate	the error.  A successful return	from mmap() will never
     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_PRIVATE and	MAP_SHARED were	both specified.

     [EINVAL]		MAP_FIXED was specified	and the	addr parameter was not
			page aligned.

     [EINVAL]		addr and len specified a region	that would extend be-
			yond the end of	the address space.

     [EINVAL]		fd did not specify a regular, character	special, or
			block special file.

     [EINVAL]		fd specified a character special or block special file
			and the	underlying device does not support memory map-

     [EINVAL]		The allocation len was 0.

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

     [ENOTSUP]		The accesses requested in the prot argument are	not
			allowed.  In particular, PROT_WRITE | PROT_EXEC	map-
			pings are not permitted	unless the filesystem is
			mounted	wxallowed and the process is link-time tagged
			with wxneeded.	(See also kern.wxabort in sysctl(2)
			for a method to	diagnose failure).

     madvise(2), mlock(2), mprotect(2),	mquery(2), msync(2), munmap(2),
     getpagesize(3), core(5)

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

     A fully functional	mmap() system call first appeared in SunOS 4.0 and has
     been available since 4.3BSD Net/2.

     IEEE Std 1003.1-2008 ("POSIX.1") specifies	that references	to pages be-
     yond the end of a mapped object shall generate a SIGBUS signal; however,
     on	some architectures OpenBSD generates a SIGSEGV signal in this case in-

     Additionally, IEEE	Std 1003.1-2008	("POSIX.1") specifies that mmap()
     shall fail	with EINVAL if neither MAP_PRIVATE nor MAP_SHARED is specified
     by	flags; however,	for compatibility with old programs, OpenBSD instead
     defaults to MAP_SHARED for	mappings of character special files, and to
     MAP_PRIVATE for all other mappings.  New programs should not rely on this

     Due to a limitation of the	current	vm system (see uvm_init(9)), mapping
     descriptors PROT_WRITE without also specifying PROT_READ is useless (re-
     sults in a	segmentation fault when	first accessing	the mapping).  This
     means that	such descriptors must be opened	with O_RDWR, which requires
     both read and write permissions on	the underlying object.

FreeBSD	13.0			 March 2, 2021			  FreeBSD 13.0


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

home | help