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

FreeBSD Manual Pages

  
 
  

home | help
mmap(2)			      System Calls Manual		       mmap(2)

NAME
       mmap - map pages	of memory

SYNOPSIS
DESCRIPTION
       This manpage contains HP-UX extensions.

       The function establishes	a mapping between a process' address space and
       a file. The format of the call is as follows:

       The function establishes	a mapping between the process'	address	 space
       at  an  address	pa for len bytes and the file associated with the file
       descriptor fildes at offset off for len bytes. The value	of  pa	is  an
       unspecified  function of	the argument addr and values of	flags, further
       described below.	A successful call returns pa as	its  result.  The  ad-
       dress ranges covered by [pa, pa+len] and	[off, off+len] must be legiti-
       mate for	the possible (not necessarily  current)	 address  space	 of  a
       process and the file, respectively.

       If  the size of the mapped file changes after the call to the effect of
       references to portions of the mapped region that	correspond to added or
       removed portions	of the file is unspecified.

       The  function  is  supported  for regular files.	 Support for any other
       type of file is unspecified except for which  is	 supported  in	HP-UX.
       See also	zero(7).

       The prot	argument determines whether read, write, execute, or some com-
       bination	of accesses are	permitted to the pages being mapped.  The pro-
       tection options are defined in

	      Page can be read.

	      Page can be written.

	      Page can be executed.

	      Page cannot be accessed.

       Implementations	need  not  enforce  all	combinations of	access permis-
       sions. However, writes shall only be permitted when has been set.

       The flags argument provides other information about the handling	of the
       mapped pages. The options are defined in

	      Share changes.

	      Share changes between 32-bit and 64-bit processes.

	      Changes are private.

	      Interpret		       addr exactly.

       The  and	flags control the visibility of	write references to the	memory
       region.	Exactly	one of these flags must	 be  specified.	  The  mapping
       type is retained	across a

       If  is set in flags, write references to	the memory region by the call-
       ing process may change the file and are visible in all mappings of  the
       same  portion  of  the file by any process of the same executable type.
       That is,	an application compiled	as a 32-bit process will  be  able  to
       share the same mappings with other 32-bit processes, and	an application
       compiled	as a 64-bit process will be able to share  the	same  mappings
       with other 64-bit processes.

       If  a  64-bit  and a 32-bit application want to share the same mapping,
       both and	must be	set in flags by	the 64-bit  application.   The	32-bit
       application does	not need to set	in flags.  When	is set in flags, write
       references to the memory	region by the calling process may  change  the
       file.  Changes are visible in all 32-bit	processes which	specify	and by
       all 64-bit processes which specify both and for the same	portion	of the
       file.

       If  is set in flags, write references to	the memory region by the call-
       ing process do not change the file and are not visible to  any  process
       in other	mappings of the	same portion of	the file.

       It  is  unspecified  whether  write  references	by processes that have
       mapped the memory region	using  are  visible  to	 processes  that  have
       mapped the same portion of the file using

       It  is  also  unspecified  whether  write references to a memory	region
       mapped with are visible to  processes  reading  the  file  and  whether
       writes to a file	are visible to processes that have mapped the modified
       portion of that file, except for	the effect of

       When is set in the flags	argument, the implementation is	informed  that
       the value of pa must be addr, exactly. If is set, may return and	set to
       If a request is successful, the mapping	established  by	 replaces  any
       previous	mappings for the process' pages	in the range [pa, pa+len].

       When  is	not set, the implementation uses addr in an unspecified	manner
       to arrive at pa.	 The pa	so chosen will be an area of the address space
       which  the  implementation deems	suitable for a mapping of bytes	to the
       file. All implementations interpret an addr value of 0 as granting  the
       implementation complete freedom in selecting pa,	subject	to constraints
       described below.	A non-zero value of addr is taken to be	 a  suggestion
       of a process address near which the mapping should be placed.  When the
       implementation selects a	value for pa, it never places a	mapping	at ad-
       dress  0,  nor does it replace any extant mapping, nor map into dynamic
       memory allocation areas.

       The off argument	is constrained to be aligned and  sized	 according  to
       the  value  returned  by	when passed or When is specified, the argument
       addr must also meet these constraints. The implementation performs map-
       ping  operations	 over  whole pages.  Thus, while the argument len need
       not meet	a size or alignment constraint,	the  implementation  will  in-
       clude,  in  any	unmapping operation, any partial page specified	by the
       range [pa, pa+len].

       The implementation always zero-fills any	partial	page at	the end	 of  a
       memory  region.	Further, the implementation never writes out any modi-
       fied portions of	the last page of a file	that are beyond	the end	of the
       mapped portion of the file.  If the mapping established by extends into
       pages beyond the	page containing	the last byte of the file, an applica-
       tion  reference	to any of the pages in the mapping that	are beyond the
       last page results in the	delivery of a or signal.  The function adds an
       extra  reference	to the file associated with the	file descriptor	fildes
       which is	not removed by a subsequent on that file descriptor. This ref-
       erence  is  removed  when  there	are no more mappings to	the file.  The
       st_atime	field of the mapped file may be	marked for update at any  time
       between	the call and the corresponding call. The initial read or write
       reference to a mapped region will cause the file's st_atime field to be
       marked for update if it has not already been marked for update.

       The st_ctime and	st_mtime fields	of a file that is mapped with and will
       be marked for update at some point in the interval between a write ref-
       erence  to the mapped region and	the next call to with or for that por-
       tion of the file	by any process.	If there is no such call, these	fields
       may be marked for update	at any time after a write reference if the un-
       derlying	file is	modified as a result.

       There may be implementation-dependent limits on the  number  of	memory
       regions	that  can  be  mapped  (per process or per system).  If	such a
       limit is	imposed, whether the number of	memory	regions	 that  can  be
       mapped by a process is decreased	by the use of is implementation-depen-
       dent.

RETURN VALUE
       Upon successful completion, returns the address,	 (pa),	at  which  the
       mapping	was placed.  Otherwise,	it returns (defined in and sets	to in-
       dicate the error.

ERRORS
       The function will fail if:

	      [EBADF]	     The fildes	argument is not	a valid	open file  de-
			     scriptor.

	      [EACCES]	     The fildes	argument is not	open for read, regard-
			     less of the protection specified,	or  fildes  is
			     not  open	for write and was specified for	a type
			     mapping.

	      [ENXIO]	     Addresses in the range [off, off+len] are invalid
			     for fildes.

	      [EINVAL]	     The  addr	argument  (if was specified) or	off is
			     not a multiple of the page	size as	returned by or
			     are considered invalid by the implementation.

	      [EINVAL]	     The  value	 of  flags  is invalid (neither	nor is
			     set).

	      [EINVAL]	     The mapping  already  exists  in  64-bit  address
			     space, but	the application	performing the current
			     request has been compiled as a 32-bit executable.

	      [EINVAL]	     The mapping  already  exists  in  32-bit  address
			     space, but	the application	performing the current
			     request has been compiled as a 64-bit  executable
			     and did not specify in the	flags argument.

	      [EMFILE]	     The  number of mapped regions would exceed	an im-
			     plementation-dependent limit (per process or  per
			     system).

	      [ENODEV]	     The  fildes  argument refers to a file whose type
			     is	not supported by

	      [ENOMEM]	     was specified, and	the range [addr, addr+len] ex-
			     ceeds  that  allowed  for	the address space of a
			     process; or if was	not specified and there	is in-
			     sufficient	 room  in  the address space to	effect
			     the mapping.

APPLICATION USAGE
       Use of may reduce the amount of memory available	to other memory	 allo-
       cation functions.

       Use of may result in unspecified	behavior in further use	of and The use
       of is discouraged, as it	may prevent an implementation from making  the
       most effective use of resources.

       The  application	must ensure correct synchronization when using in con-
       junction	with any other file access method, such	as  and	 standard  in-
       put/output, and

       The  function  allows  access  to resources via address space manipula-
       tions, instead of Once a	file is	mapped,	all a process has to do	to ac-
       cess  it	 is  use the data at the address to which the file was mapped.
       So, using pseudo-code to	illustrate the way in which an	existing  pro-
       gram might be changed to	use the	following:

       becomes:

SEE ALSO
       exec(2),	fcntl(2), fork(2), lockf(2), msync(2), munmap(2), mprotect(2),
       shmop(2), sysconf(2).

mmap(2)			      System Calls Manual		       mmap(2)

				  HP-UX	EXTENSIONS

NAME
       mmap - map pages	of memory

SYNOPSIS
DESCRIPTION
	      Create a mapped file region.

	      Create an	unnamed	memory region.

	      Place region at implementation-computed address.

	      Lazily evaluate swap space reservation.

	      Allocate physical	memory from the	current	locality domain.

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

       If is set in flags:

	      o	   A new mapped	file region is created,	mapping	the file asso-
		   ciated with fildes.

	      o	   off	specifies  the	file  byte offset at which the mapping
		   starts.  This offset	must be	a multiple of  the  page  size
		   returned by

	      o	   If  the  end	of the mapped file region is beyond the	end of
		   the file, any reference to an address in  the  mapped  file
		   region  corresponding  to  an  offset beyond	the end	of the
		   file	results	in the delivery	of a signal  to	 the  process,
		   unless  the	address	 lies  in the last partial page	corre-
		   sponding to the range beyond	the end	of the file.  The last
		   partial  page  mapping the range beyond the end of the file
		   is always initialized to zeros, and any  modified  portions
		   of the last page of a file which are	beyond its end are not
		   written back	to the file.

       If is set in flags:

	      o	   A new memory	region is created and initialized to  all  ze-
		   ros.	  This	memory	region can be shared only with descen-
		   dants of the	current	process.

	      o	   If the fildes argument is not -1, an	EINVAL error is	gener-
		   ated.   This	 is  not  enforced in the current release, but
		   will	be enforced in the next	release.

	      o	   The value of	off is meaningless because there is no	under-
		   lying file object for the memory region.

       The  and	 flags control the placement of	the region as described	below.
       Exactly one of these flags must be selected.

       If is set in flags:

	      o	   If the requested address is NULL, or	if it is not  possible
		   for	the  system  to	 place the region at the requested ad-
		   dress, the region is	placed at an address selected  by  the
		   system.   If	the requested address is not a multiple	of the
		   page	size returned by the system treats the address	as  if
		   it were rounded up to the next larger page size multiple.

       If is set in flags:

	      o	   addr	must be	a multiple of the page size returned by

       If is set in flags:

	      o	   no swap space is initially be reserved for the private map-
		   ping.  Without this flag, the creation of a MAP_PRIVATE re-
		   gion	 reserves swap space equal to the size of the mapping.
		   When	a page in  the	mapping	 is  first  modified  (written
		   into),  a  private page is created and the swap space which
		   had been reserved is	used to	hold the private copy  of  the
		   data	 in  the event of a page-out.  An initial write	into a
		   page	of a MAP_NORESERVE mapping produces results which  de-
		   pend	on the current availability of system swap space since
		   the swap space reservation occurs at	the time of the	 first
		   write  and  only  for the affected page.  If	the swap space
		   reservation can be made for the page,  the  write  succeeds
		   and	is  processed  as  described  above; if	not, the write
		   fails and a signal is posted	to the writing process for the
		   effective  virtual address.	on a MAP_NORESERVE object will
		   release swap	space reservations for relevant	pages.

       If is set in flags:

	      o	   Memory for this region will be allocated from  the  current
		   locality  domain.   This flag overrides the default alloca-
		   tion	policy of first	touch.	Under a	first touch allocation
		   policy, when	memory needs to	be allocated, the locality do-
		   main	chosen is that of the currently	executing process.

       The prot	argument can be	or any combination of and OR'ed	together.   If
       is  not specified, the system may grant other access permissions	to the
       region in addition to those explicitly requested, except	that write ac-
       cess will not be	granted	unless is specified.

       cannot  create  a mapped	file region unless the file descriptor used to
       map the file is open for	reading.  For a	mapped	file  region  that  is
       mapped  with grants write access	permission only	if the file descriptor
       is open for writing.  If	a region was mapped with either	or grants  all
       requested access	permissions.

       After  the successful completion	of fildes 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 de-
       scriptor, that prevents the file	data from being	deallocated.

       Whether modifications made to the file using are	visible	to mapped  re-
       gions, and whether modifications	to a mapped region are visible with is
       undefined except	for the	effect of

       If an enforcement-mode file lock	is in effect for any range of a	 file,
       a  call	to  to map any range of	the file with access rights that would
       violate the lock	fails.	The and	semaphore interfaces can  be  used  to
       coordinate  shared access to a region created with the flag.  The advi-
       sory locks of the or interfaces have no effect on memory	mapped access,
       but  they  can be used to coordinate shared access to a mapped file re-
       gion.

       For a memory mapped file, the st_atime and st_mtime values returned  by
       are  updated  when  a  page in the memory mapped	region is read from or
       written to the file system.

       After a call to the child process inherits all mapped regions with  the
       same data and the same sharing and protection attributes	as in the par-
       ent process.  Each mapped file and anonymous memory region created with
       is  unmapped  upon process exit,	and by a successful call to any	of the
       functions.

       attribute is inherited across a call; at	the time of the	swap space for
       a  mapping is reserved in the child only	for dirtied private pages that
       currently exist in the parent; thereafter the child's mapping  reserva-
       tion policy is as described above.

       A  signal  is delivered to a process when a write reference to a	mapped
       file region would cause a file system error condition such as exceeding
       quota or	file system space limits.

       A  signal  is delivered to a process upon a write reference to a	region
       without protection, or any reference to a region	with protection.

       A call to with specified,  but  without	specified  for	a  mapping  is
       treated	by  the	 system	as the execution of the	underlying file.  This
       implies that such a call	fails if the file is currently open for	 writ-
       ing  or	mapped	with options by	any process, and that if the call suc-
       ceeds, the file cannot be opened	for  writing  or  subsequently	mapped
       with  options as	long as	such mappings are present.  A file's status as
       an active executable file is determined only at the time	of an or oper-
       ation.  operations on a mapping have no effect on the underlying	file's
       status as an active executable file.

       Specifying in a call to forces the allocation to	happen from the	global
       quadrant	 as  compared  to the private quadrants.  See setmemwindow(1M)
       for further details.

ERRORS
	      [EACCES]	     The file referred to by fildes is	not  open  for
			     read  access,  or	the file is not	open for write
			     access and	was set	for a  mapping	operation,  or
			     was  set for a mapping operation and the underly-
			     ing file does not have execute permission.

	      [EOVERFLOW]    The file is a  regular  file  and	the  value  of
			     off+len exceeds the offset	maximum	established in
			     the open file description associated with fildes.

	      [ETXTBSY]	     and are set, and is set and is not	set,  and  the
			     file being	mapped is currently open for writing.

	      [EINVAL]	     The  value	 of  off+len  exceeds the maximum sup-
			     ported offset for mapped files.

DEPENDENCIES
   Series 700/800
       Because the PA-RISC memory architecture utilizes	a globally shared vir-
       tual  address  space between processes and discourages multiple virtual
       address translations to the same	physical address, all concurrently ex-
       isting  mappings	 of  a	file range must	share the same virtual address
       offsets and hardware translations. PA-RISC-based	HP-UX systems allocate
       virtual address ranges for shared memory	and shared mapped files	in the
       range 0x80000000	through	0xefffffff for those applications compiled  as
       32-bit  executables  or for those 64-bit	applications which specify and
       in the flags argument of	the function.  For  applications  compiled  as
       64-bit  executables  which specify and do not specify the shared	mapped
       files are in the	range 0x00000011 00000000 through 0x000003ff  ffffffff
       and  0xc0000000	00000000  through  0xc00003ff ffffffff.	 These address
       ranges are used globally	for all	memory	objects	 shared	 between  pro-
       cesses.

       This implies the	following:

	      o	   Any	single	range of a file	cannot be mapped multiply into
		   different virtual address ranges.

	      o	   After the initial of	a file range, all subsequent calls  to
		   to  map  the	 same  range  of a file	must either specify in
		   flags and inherit the virtual address range the system  has
		   chosen  for this range, or specify with an addr that	corre-
		   sponds exactly to the address chosen	by the system for  the
		   initial  mapping.  Only after all mappings for a file range
		   have	been destroyed can that	range be mapped	to a different
		   virtual address.

	      o	   In most cases, two separate calls to	cannot map overlapping
		   ranges in a file.  The virtual address range	reserved for a
		   file	range is determined at the time	of the initial mapping
		   of the file range into a process address space.  The	system
		   allocates  only the virtual address range necessary to rep-
		   resent the initial mapping.	As long	as the initial mapping
		   exists,  subsequent	attempts to map	a different file range
		   that	includes any portion of	the  initial  range  may  fail
		   with	 an  ENOMEM  error  if	an extended contiguous address
		   range that preserves	the mappings of	the initial range can-
		   not be allocated.

	      o	   Separate calls to to	map contiguous ranges of a file	do not
		   necessarily return contiguous virtual address ranges.   The
		   system may allocate virtual addresses for each call to on a
		   first available basis.

	      o	   The use of is strongly discouraged because it is not	porta-
		   ble.	  Using	 is generally unsuccessful on this implementa-
		   tion, and when it is	successful, it may prevent the	system
		   from	optimally allocating virtual address space.

       is  discouraged,	 but  there are	some applications which	by design must
       fix pointer offsets into	file data.  The	application must map the  file
       at  a  specific	address	 in order for the file offsets embedded	in the
       file to make sense.

       Processes cannot	control	the usage of global virtual address space, but
       they  can control what happens within their private data	area.  The Se-
       ries 700/800 allows a single process to map a  file  into  its  private
       data  space.   When a process specifies and with	a private data address
       (i.e. second quadrant for 32-bit	executable, third quadrant for	64-bit
       executable),  the kernel	interprets this	as an exclusive	mapping	of the
       file.  The request will only succeed if no other	processes in the  sys-
       tem  currently  have  that  file	 mapped	through	If the file is already
       mapped the caller receives an EBUSY error.  If the call is  successful,
       the  calling process is the only	process	allowed	to map that file using
       until it	unmaps the file	using Because it is exclusive, the is not  in-
       herited	across When a file is exclusively mapped only mappings are al-
       lowed by	other processes.

       The following combinations of protection	modes are supported:

       If a mapping is created of a file for which a mapping exists,  a	 sepa-
       rate copy of a page for the mapping is created at the time of the first
       access to the page through the private mapping.

AUTHOR
       was developed by	HP, AT&T, and OSF.

SEE ALSO
       fcntl(2), fork(2), truncate(2), lockf(2), madvise(2), creat64(2), mpro-
       tect(2),	 msem_init(2),	msem_lock(2),  msem_unlock(2),	msync(2), mun-
       map(2), sysconf(2), mman(5), stat(5), zero(7).

STANDARDS CONFORMANCE
								       mmap(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | APPLICATION USAGE | SEE ALSO | NAME | SYNOPSIS | DESCRIPTION | ERRORS | DEPENDENCIES | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

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

home | help