unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



mmap(2)								      mmap(2)



NAME
  mmap - Maps file system object into virtual memory

SYNOPSIS

  #include <&lt;sys/mman.h>&gt;

  void *mmap (
	  void *addr,
	  size_t len,
	  int prot,
	  int flags,
	  int filedes,
	  off_t	off );

  [Tru64 UNIX]	 The following definition of the mmap()	function does not
  conform to current standards and is supported	only for backward compatibil-
  ity (see standards(5)):

  caddr_t mmap (
	  caddr_t addr,
	  size_t len,
	  int prot,
	  int flags,
	  int filedes,
	  off_t	off );

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  mmap():  XSH5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

  Standards: standards(5)

PARAMETERS

  addr	    Specifies the starting address of the new region (truncated	to a
	    page boundary).

  len	    Specifies the length in bytes of the new region (rounded up	to a
	    page boundary).

  prot	    Specifies access permissions as either PROT_NONE or	the result of
	    a logical OR operation on any combination of PROT_READ,
	    PROT_WRITE,	and PROT_EXEC.

  flags	    Specifies attributes of the	mapped region as the results of	a
	    bitwise-inclusive OR operation on any combination of MAP_FILE,
	    MAP_ANONYMOUS, MAP_VARIABLE, MAP_FIXED, MAP_SHARED,	MAP_PRIVATE,
	    MAP_INHERIT, or MAP_UNALIGNED .

  filedes   Specifies the file to be mapped to the new mapped file region
	    returned by	open().

  off	    Specifies the offset into the file that gets mapped	at address
	    addr.

DESCRIPTION

  The mmap() function creates a	new mapped file	region,	a new private region,
  or a new shared memory region.

  The addr and len parameters specify the requested starting address and
  length in bytes for the new region.  The address is a	multiple of the	page
  size returned	by sysconf(_SC_PAGE_SIZE).

  If the len parameter is not a	multiple of the	page size returned by
  sysconf(_SC_PAGE_SIZE), then the result of any reference to an address
  between the end of the region	and the	end of the page	containing the end of
  the region is	undefined.

  The flags parameter specifies	attributes of the mapped region.  Values of
  the flags parameter are constructed by a bitwise-inclusive OR	operation on
  the flags from the following list of symbolic	names defined in the
  sys/mman.h file:

  MAP_FILE     Create a	mapped file region.

  MAP_ANONYMOUS
	       Create an unnamed memory	region.

  MAP_VARIABLE Place region at the computed address.

  MAP_FIXED    Place region at fixed address.

  MAP_SHARED   Share changes.

  MAP_PRIVATE  Changes are private.

  MAP_INHERIT  Region not unmapped by exec(2).

  MAP_UNALIGNED
	       Do not verify that the file offset is page aligned.

  The MAP_FILE and MAP_ANONYMOUS flags control whether the region to be
  mapped is a mapped file region or an anonymous shared	memory region. One of
  these	flags must be selected.

  If MAP_FILE is set in	the flags parameter:

    +  A new mapped file region	is created, mapping the	file associated	with
       the filedes parameter.

    +  The off parameter specifies the file byte offset	at which the mapping
       starts.	This offset must be a multiple of the page size	returned by
       sysconf(_SC_PAGE_SIZE).

    +  If the end of the mapped	file region is beyond the end of the file,
       the result of any reference to an address in the	mapped file region
       corresponding to	an offset beyond the end of the	file is	unspecified.

  If MAP_ANONYMOUS is set in the flags parameter:

    +  A new memory region is created and initialized to all zeros.  This
       memory region can be shared only	with descendents of the	current	pro-
       cess.

    +  If the filedes parameter	is not -1, the mmap() function fails.


  The new region is placed at the requested address if the requested address
  is not null and it is	possible to place the region at	this address.  When
  the requested	address	is null	or the region cannot be	placed at the
  requested address, the MAP_VARIABLE and MAP_FIXED flags control the place-
  ment of the region.  One of these flags must be selected.

  If MAP_VARIABLE is set in the	flags parameter:

    +  If the requested	address	is null	or if it is not	possible for the sys-
       tem to place the	region at the requested	address, the region is placed
       at an address selected by the system.

  If MAP_FIXED is set in the flags parameter:

    +  If the requested	address	is not null, the mmap()	function succeeds
       even if the requested address is	already	part of	another	region.	 (If
       the address is within an	existing region, the effect on the pages
       within that region and within the area of the overlap produced by the
       two regions is the same as if they were unmapped.  In other words,
       whatever	is mapped between addr and addr	+ len will be unmapped.)

    +  If the requested	address	is null	and MAP_FIXED is specified, the
       region is placed	at the default exact mapping address for the region.
       It places the region at this value exactly, replacing previous map-
       pings if	necessary.  The	exact mapping address is determined from a
       combination of the flag and protection parameters passed	to the mmap()
       function.

  The MAP_PRIVATE and MAP_SHARED flags control the visibility of modifica-
  tions	to the mapped file or shared memory region.  One of these flags	must
  be selected.

  If MAP_SHARED	is set in the flags parameter:

    +  If the region is	a mapped region, modifications to the region are
       visible to other	processes that have mapped the same region using
       MAP_SHARED.

    +  If the region is	a mapped file region, modifications to the region are
       written to the file.  (Note that	the modifications are not immediately
       written to the file because of buffer cache delay; that is, the write
       to the file does	not occur until	there is a need	to reuse the buffer
       cache.  If the modifications must be written to the file	immediately,
       the msync() function can	be used	to ensure that this is done.)

  If MAP_PRIVATE is set	in the flags parameter:

    +  Modifications to	the mapped region by the calling process are not
       visible to other	processes that have mapped the same region using
       either MAP_PRIVATE or MAP_SHARED.

    +  Modifications to	the mapped region by the calling process are not
       written to the file.

  It is	unspecified whether modifications by processes that have mapped	the
  region using MAP_SHARED are visible to other processes that have mapped the
  same region using MAP_PRIVATE.

  If MAP_INHERIT is set	in the flags parameter:

    +  The mapped region cannot	be removed from	the address space of the cal-
       ling process by the exec(2) system call.

  If MAP_UNALIGNED is set in the flags parameter:

    +  The mmap	system call is prevented from verifying	that the file offset
       is page aligned.

  The prot parameter specifies the mapped region's access permissions.	The
  sys/mman.h header file defines the following access options:

  PROT_READ The	mapped region can be read.

  PROT_WRITE
	    The	mapped region can be written.

  PROT_EXEC The	mapped region can be executed.

  PROT_NONE The	mapped region cannot be	accessed.

  The prot parameter can be either PROT_NONE or	the results of a logical OR
  operation on any combination of PROT_READ, PROT_WRITE, and PROT_EXEC.	 If
  PROT_NONE is not specified, access permissions may be	granted	to the region
  in addition to those explicitly requested, except that write access is not
  granted unless PROT_WRITE is specified.

  If the region	is a mapped file that was mapped with MAP_SHARED, the mmap()
  function grants read or execute access permission only if the	file descrip-
  tor used to map the file is open for reading,	and grants write access	per-
  mission only if the file descriptor used to map the file is open for writ-
  ing.	If the region is a mapped file that was	mapped with MAP_PRIVATE, the
  mmap() function grants read, write, or execute access	permission only	if
  the file descriptor used to map the file is open for reading.	 If the
  region is a shared memory region that	was mapped with	MAP_ANONYMOUS, the
  mmap() function grants all requested access permissions.

  After	the successful completion of the mmap()	function, the filedes parame-
  ter can be closed without effect on the mapped region	or on the contents of
  the mapped file.  Each mapped	region creates a file reference, similar to
  an open file descriptor, which prevents the file data	from being deallo-
  cated.

  Modifications	made to	the file using the write() function are	visible	to
  mapped regions, and modifications to a mapped	region are visible with	the
  read() function.

  After	a call to the fork() function, the child process inherits all mapped
  regions with the same	sharing	and protection attributes as in	the parent
  process.  Each mapped	file and shared	memory region created with the mmap()
  function is unmapped by a successful call to any of the exec functions,
  unless that region is	made inheritable across	exec.

NOTES

  Note that memory acquired with the mmap() function is	not locked, regard-
  less of the previous use of the plock() function.

  Note that mmaping will fail on a file	that has direct	I/O enabled.

  For AdvFS files, use the msync() function to write out modified file data
  in a memory region established by mmap().  This is necessary to ensure the
  integrity of the changes in the data being written.




RETURN VALUES

  Upon successful completion, the mmap() function returns the address at
  which	the mapping was	placed.	 Otherwise, mmap() returns the value of
  MAP_FAILED.  The symbol, MAP_FAILED, is defined in the <&lt;sys/mman.h>&gt; header
  file.

ERRORS

  If the mmap()	function fails,	errno may be set to one	of the following
  values:

  [EACCES]  The	file referred to by filedes is not open	for read access, or
	    the	file is	not open for write access and PROT_WRITE was set for
	    a MAP_SHARED mapping operation.

  [EBADF]   The	filedes	parameter is not a valid file descriptor.

  [EFAULT]  The	addr parameter is an invalid address.

  [EINVAL]  The	flags or prot parameter	is invalid, or the addr	parameter or
	    off	parameter is not a multiple of the page	size returned by
	    sysconf(_SC_PAGE_SIZE).   This error is also returned if the file
	    is already open for	atomic write data logging or direct I/O.

  [ENODEV]  The	file descriptor	filedes	refers to an object that cannot	be
	    mapped, such as a terminal.

  [ENOMEM]  There is not enough	address	space to map len bytes.

  [ENXIO]   The	addresses specified by the range [off, off + len) are invalid
	    for	filedes.

RELATED	INFORMATION

  Functions: exec(2), fcntl(2),	fork(2), madvise(2), mprotect(2), msync(2),
  munmap(2), plock(2), sysconf(3)

  Standards: standards(5)