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

FreeBSD Manual Pages

  
 
  

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

NAME
     mmap -- map files or devices into memory

SYNOPSIS
     #include <sys/types.h>
     #include <sys/mman.h>

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

DESCRIPTION
     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
     range.

     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.

     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:

     MAP_ANON	 Map anonymous memory not associated with any specific file.
		 The file descriptor used for creating MAP_ANON	must be	-1.
		 The offset parameter is ignored.

     MAP_FIXED	 Do not	permit the system to select a different	address	than
		 the one specified.  If	the specified address cannot be	used,
		 mmap()	will fail.  If MAP_FIXED is specified, addr must be a
		 multiple of the pagesize.  Use	of this	option is discouraged.

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

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

     MAP_PRIVATE
		 Modifications are private.

     MAP_SHARED	 Modifications are shared.

     MAP_STACK	 This option is	only available if your system has been com-
		 piled with VM_STACK defined when compiling the	kernel.	This
		 is the	default	for i386 only. Consider	adding -DVM_STACK to
		 COPTFLAGS in your /etc/make.conf to enable this option	for
		 other architechures. MAP_STACK	implies	MAP_ANON, and offset
		 of 0.	fd must	be -1 and prot must include at least PROT_READ
		 and PROT_WRITE.  This option creates a	memory region that
		 grows to at most len bytes in size, starting from the stack
		 top and growing down.	The stack top is the starting address
		 returned by the call, plus len	bytes.	The bottom of the
		 stack at maximum growth is the	starting address returned by
		 the call.

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

     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.

RETURN VALUES
     Upon successful completion, mmap()	returns	a pointer to the mapped	re-
     gion.  Otherwise, a value of MAP_FAILED is	returned and errno is set to
     indicate the error.

ERRORS
     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
			writing.

     [EBADF]		is not a valid open file descriptor.

     [EINVAL]		MAP_FIXED was specified	and the	addr parameter was not
			page aligned, or part of the desired address space re-
			sides out of the valid address space for a user
			process.

     [EINVAL]		Len was	negative.

     [EINVAL]		MAP_ANON was specified and the fd parameter was	not
			-1.

     [EINVAL]		MAP_ANON has not been specified	and fd did not refer-
			ence a regular or character special file.

     [EINVAL]		Offset was not page-aligned.  (See BUGS	below.)

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

SEE ALSO
     madvise(2), mincore(2), mlock(2), mprotect(2), msync(2), munlock(2),
     munmap(2),	getpagesize(3)

BUGS
     len is limited to 2GB.  Mmapping slightly more than 2GB doesn't work, but
     it	is possible to map a window of size (filesize %	2GB) for file sizes of
     slightly less than	2G, 4GB, 6GB and 8GB.

     The limit is imposed for a	variety	of reasons. Most of them have to do
     with FreeBSD not wanting to use 64	bit offsets in the VM system due to
     the extreme performance penalty. So FreeBSD uses 32bit page indexes and
     this gives	FreeBSD	a maximum of 8TB filesizes. It's actually bugs in the
     filesystem	code that causes the limit to be further restricted to 1TB
     (loss of precision	when doing blockno calculations).

     Another reason for	the 2GB	limit is that filesystem metadata can reside
     at	negative offsets.

     We	currently can only deal	with page aligned file offsets.

4th Berkeley Distribution	 May 11, 1995	     4th Berkeley Distribution

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | BUGS

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

home | help