mmap man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

mmap(2)								       mmap(2)

       mmap() - map pages of memory

       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
       address	ranges	covered	 by  [pa,  pa+len]  and [off, off+len] must be
       legitimate for the possible (not necessarily current) address space  of
       the 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.

       The  prot  argument can be or any combination of the bit-wise inclusive
       OR of the values of and If is not specified, the system may grant other
       access  permissions  to	the  region  in	 addition  to those explicitly
       requested, except that write access will not be granted unless is spec‐

       The following combinations of protection modes are supported:

       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.
		     Under Adaptive Address Space, 64-bit MPAS (Mostly Private
		     Address  Space)  processes cannot specify this flag.  See
		     the for details.

	      Changes are private.

		     addr exactly.

	      Create a mapped file region.

	      Create an unnamed memory region.

	      Place region at implementation-computed address.

	      Evaluate lazy swap space reservation.

	      Allocate physical memory from the global quadrant / octant.

	      Create a virtual mapping for a physical I/O address range.

	      Physical memory will be interleaved.

	      Allocate physical memory from the current locality domain.

	      Allocate physical memory from the locality domain of the first
		     processor to touch each address.

       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.  Mappings created using the flag do not currently	support	 usage
       of  the	flag.	Applications may use with 32-bit and 64-bit processes,
       but the pa returned to a 32-bit process may differ from the pa returned
       to a 64-bit process.

       On  platforms,  64-bit  MPAS  (Mostly  Private  Address Space) and MGAS
       (Mostly Global Address Space) processes can  share  between  themselves
       without	incurring  the cost of aliasing by specifying the flag without
       specifying the flag.  Such mappings are not accessible by  32-bit  pro‐
       cesses.	See the for details.

       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

       The  and	 flags control the placement of the region as described below.
       Exactly one of these flags must be selected, unless is set.  implicitly
       defaults to using and does not support

       If is set in flags, and the requested address addr is NULL, or if it is
       not possible for the system  to	place  the  region  at	the  requested
       address, 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.

       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].  If
       fails for reasons other than or some of the  mappings  in  the  address
       range  starting	at  addr  and  continuing  for len bytes may have been

       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 len  bytes  to
       the file.  All implementations interpret an addr value of 0 as granting
       the implementation complete freedom in selecting pa,  subject  to  con‐
       straints	 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 address 0, replaces any  extant  mapping,  or  maps
       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
       mapping operations over whole pages.  Thus, while the argument len need
       not  meet  a  size  or  alignment  constraint,  the implementation will
       include, in any unmapping operation, any partial page specified by  the
       range [pa, pa+len].

       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, a new mapped file region is created, mapping the
       file associated with fildes.  off specifies the	file  byte  offset  at
       which  the  mapping starts.  This offset must be a multiple of the page
       size returned by 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 cor‐
       responding 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 corresponding 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 the file's end are not written
       back to the file.

       If is set in flags, a new memory region is created and  initialized  to
       all  zeros.   This memory region can be shared only with descendants of
       the current process.  If the fildes argument is not  −1,	 an  error  is
       generated.   This  is  not enforced in the current release, but will be
       enforced in the next release.  The value of off is meaningless  because
       there is no underlying file object for the memory region.

       If is set in flags, no swap space is initially reserved for the private
       mapping.	 Without this flag, the creation of  a	region	reserves  swap
       space  equal to the size of the mapping.	 When a page in the mapping is
       first modified (written to), a private page is  created	and  the  swap
       space  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	 mapping  pro‐
       duces  results  which depend 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 as	described  above.   If
       not,  the write fails and a signal is posted to the writing process for
       the effective virtual address.  on a object  will  release  swap	 space
       reservations for relevant pages.

       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.

       If is set in flags:

	      ·	 The  mapping will cover a range of I/O memory instead of core
		 memory.  This allows direct access to memory on  I/O  devices
		 by the process.

	      ·	 Multiple  processes can concurrently map the same I/O address
		 range.	 It is the responsibility of the processes to synchro‐
		 nize  their  accesses to the I/O memory.  Successive calls to
		 to map the same I/O address range must be  identical  to  the
		 first	mapping.  Identical mappings pass the same off and len

	      ·	 Processes can additionally share access  to  an  I/O  address
		 range	with  a kernel driver.	However, this is only possible
		 if the driver maps the I/O address range with user read/write
		 access	 rights	 using the appropriate driver I/O mapping ser‐
		 vices.	 I/O address ranges  mapped  by	 drivers  with	kernel
		 read/write access rights can not be mapped by processes.

	      ·	 Read/write  access rights to the I/O address range are speci‐
		 fied by the prot argument: for read and write access, or  for
		 read-only access.

	      ·	 Calls with set will implicitly default to having set.	can be
		 selected in place of to map the I/O address range in the pri‐
		 vate  address space of the process.  can be selected in addi‐
		 tion to to map the I/O address range  in  the	shared	global
		 address space of the process.

	      ·	 The arguments passed to with set are:

		 · addr is set to NULL,
		 · fildes is set to -1, and
		 · off is set to the starting physical address of the I/O mem‐
		   ory to be mapped.  The physical address contains  64	 bits;
		   and use of by 32-bit processes is, therefore, done through

	      ·	 Use  of  functionality	 is  currently restricted to Real Time
		 processes or users with the privilege.

       Note that the flags and involve the placement of physical memory.  This
       is  important  only  on	Cache Coherent Non-Uniform Memory Architecture
       (ccNUMA) systems.  They will have no effect otherwise.  For more infor‐
       mation,	see  the  mpctl(2)  manual page.  These flags are hints to the
       system.	If memory of the desired type is not available, the next  most
       suitable memory is returned instead.

       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
       descriptor, that prevents the file data from being deallocated.

       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

       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

       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	reser‐
       vation 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, exceed‐
       ing quota or file system space limits.

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

       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 if  the  call  succeeds,
       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 opera‐
       tion.  operations on a mapping have no effect on the underlying	file's
       status as an active executable file.

       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
       reference 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, st_mtime, and st_atime fields of a file  that  is	mapped
       with  and  will	be  marked  for	 update	 at some point in the interval
       between a write reference to the mapped region and  the	next  call  to
       with  or	 for  that portion 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 underlying 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‐

   Security Restrictions
       Some or all of the actions associated with this system call require the
       privilege.  Processes owned by the superuser have this privilege.  Pro‐
       cesses  owned by other users may have this privilege, depending on sys‐
       tem configuration.  See privileges(5) for more information about privi‐
       leged access on systems that support fine-grained privileges.

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

       The function will fail if:

	      The	     fildes argument is not a valid open file descrip‐

	      The	     fildes argument is not open for read,  regardless
			     of	 the  protection  specified,  or fildes is not
			     open for write and was specified for a type  map‐

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

	      was specified in
			     flags  and	 the combination of addr, len, and off
			     is invalid for the object specified by fildes.

	      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.

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

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

	      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.

	      The value of   off+len  exceeds the maximum supported offset for
			     mapped files.

	      The mapping request used the
			     flag and the requested range is not a valid range
			     of	 I/O  memory,  the  requested range is already
			     mapped as restricted to kernel usage, or the map‐
			     ping  is  for an address range which overlaps but
			     is not equal to an existing mapping.

	      The number of mapped regions  would  exceed  an  implementation-
			     limit (per process or per system).

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

	      was specified, and the range
			     [addr, addr+len] exceeds  that  allowed  for  the
			     address  space  of a process.  Or, was not speci‐
			     fied  and	there  is  insufficient	 room  in  the
			     address space to effect the mapping.

	      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.

	      The mapping request used the
			     flag and the calling process does	not  have  the
			     privilege and is not a Real Time process.

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

   PA-RISC Architecture
       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
       existing	 mappings  of a file range must share the same virtual address
       offsets and hardware translations.  PA-RISC-based HP-UX	systems	 allo‐
       cate  virtual  address ranges for shared memory and shared mapped files
       in the range through for those applications compiled as 32-bit executa‐
       bles  or	 for  those 64-bit applications which specify and in the flags
       argument of the function.  For applications compiled as 64-bit executa‐
       bles  which  specify  and do not specify the shared mapped files are in
       the range through and through These address ranges  are	used  globally
       for all memory objects shared between processes.

       This implies the following:

	      ·	 Any  single  range  of a file cannot be mapped multiple times
		 into different virtual address ranges.

	      ·	 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 corresponds 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.

	      ·	 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	repre‐
		 sent  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 error if an extended contiguous address  range  that  pre‐
		 serves the mappings of the initial range cannot be allocated.

	      ·	 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.

	      ·	 The use of is strongly discouraged because it is  not	porta‐
		 ble.  Using is generally unsuccessful on this implementation,
		 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 PA-
       RISC version of HP-UX allows a single process to map a  file  into  its
       private	data  space.  When a process specifies and with a private data
       address (that is, second quadrant for 32-bit executable, third quadrant
       for 64-bit executable), the kernel interprets this as an exclusive map‐
       ping of the file.  The request will only succeed if no other  processes
       in  the	system	currently have that file mapped through If the file is
       already mapped the caller receives an error.  If the call  is  success‐
       ful,  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  inherited  across  When a file is exclusively mapped only mappings
       are allowed by other processes.

       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.

       Use of may reduce the amount of memory available to other memory	 allo‐
       cation functions.

       Use  of	may result in unspecified behavior later in the 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
       input/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
       access  it is use the data at the address to which the file was mapped.
       Using pseudo-code to illustrate the way an existing  program  might  be
       changed to use the following:


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

       setmemwindow(1M),  creat64(2),  exec(2),	 fcntl(2),  fork(2), lockf(2),
       madvise(2),   mpctl(2),	 mprotect(2),	msem_init(2),	 msem_lock(2),
       msem_unlock(2),	msync(2),  munmap(2),  open(2), pset_ctl(2), shmop(2),
       sysconf(2), truncate(2), mman(5), privileges(5), stat(5), zero(7).



List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net