mmap(2)mmap(2)NAMEmmap() - map pages of memory
SYNOPSISDESCRIPTION
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‐
ified.
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.
Interpret
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
unmapped.
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
arguments.
· 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
region.
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 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‐
tion.
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‐
dent.
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.
RETURN VALUE
Upon successful completion, returns the address, (pa), at which the
mapping was placed. Otherwise, it returns (defined in and sets to
indicate the error.
ERRORS
The function will fail if:
The fildes argument is not a valid open file descrip‐
tor.
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‐
ping.
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-
dependent
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.
DEPENDENCIES
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.
APPLICATION USAGE
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:
becomes:
AUTHOR
was developed by HP, AT&T, and OSF.
SEE ALSOsetmemwindow(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).
in
STANDARDS CONFORMANCEmmap(2)
