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

     Standard C	Library	(libc, -lc)

     #include <sys/types.h>
     #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.

     The flags parameter specifies the type of the mapped object, mapping
     options 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, MAP_PRIVATE or MAP_COPY must be specified.	 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	regions	is
		 used only for naming, and may be specified as -1 if no	name
		 is associated with the	region.

     MAP_FILE	 Mapped	from a regular file or character-special device	mem-

     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.

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

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

		 Modifications made by this process are	private, however modi-
		 fications made	by other processes using MAP_SHARED will be

     MAP_SHARED	 Modifications are shared.

     MAP_COPY	 Modifications are private, including other processes.

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

     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
     device to which swapping should be	done.

     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
			-1.  len was less than zero.

     [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),

     The MAP_COPY flag is not implemented.  The	current	MAP_COPY semantics are
     the same as those of the MAP_PRIVATE flag.

FreeBSD	11.1			 May 11, 1995			  FreeBSD 11.1


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

home | help