Maps file system object into virtual memory. This function is
reentrant.
Format
#include <types.h>
#include <mman.h>
void mmap (void *addr, size_t len, int prot, int flags, int
filedes, off_t off); (X/Open, POSIX-1)
void mmap (void *addr, size_t len, int prot, int flags, int
filedes, off_t off ...); (DEC C Extension)
1 – Function Variants
The mmap function has variants named _mmap32 and _mmap64 for use
with 32-bit and 64-bit pointer sizes, respectively.
2 – Arguments
addr
The starting address of the new region (must be the page
boundary).
len
The length, in bytes, of the new region.
prot
Access permission, as defined in the <mman.h> header file.
Specify either PROT_NONE, PROT_READ, or PROT_WRITE.
flags
Attributes of the mapped region as the results of a bitwise-
inclusive OR operation on any combination of the following:
o MAP_FILE or MAP_ANONYMOUS
o MAP_VARIABLE or MAP_FIXED
o MAP_SHARED or MAP_PRIVATE
filedes
The file that you want to map to the new mapped file region
returned by the open function.
off
The offset, specified in bytes. The off_t data type is either a
64-bit or 32-bit integer. The 64-bit interface allows for file
sizes greater than 2 GB, and can be selected at compile time by
defining the _LARGEFILE feature-test macro as follows:
CC/DEFINE=_LARGEFILE
. . .
An optional integer specifying additional flags for the
SYS$CRMPSC system service for MAP_SHARED. This optional argument
(VSI C Extension) of the mmap function was introduced in
OpenVMS Version 7.2.
3 – Description
The mmap function creates a new mapped file region, a new private
region, or a new shared memory region.
Your application must ensure correct synchronization when using
mmap in conjunction with any other file access method, such as
read and write, and standard input/output.
Before calling mmap, the calling application must also ensure
that all bytes in the range [off, off+len] are written to the
file (using the fsync function, for example). If this requirement
is not met, mmap fails with errno set to ENXIO (No such device or
address).
The addr and len arguments 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 argument 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 argument specifies attributes of the mapped region.
Values for flags are constructed by a bitwise-inclusive OR
operation on the flags from the following list of symbolic names
defined in the <mman.h> header 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.
The MAP_FILE and MAP_ANONYMOUS flags control whether the region
you want to map 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 argument:
o A new mapped file region is created, mapping the file
associated with the filedes argument.
o The off argument specifies the file byte offset where the
mapping starts. This offset must be a multiple of the page
size returned by sysconf(_SC_PAGE_SIZE).
o 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 argument:
o A new memory region is created and initialized to all zeros.
o The filedes argument is ignored.
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 placement of the region.
One of these flags must be selected.
If MAP_VARIABLE is set in the flags argument:
o If the requested address 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 MAP_FIXED is set in the flags argument:
o 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 is unmapped.)
o If the requested address is null and MAP_FIXED is specified,
the results are undefined.
The MAP_PRIVATE and MAP_SHARED flags control the visibility of
modifications to the mapped file or shared memory region. One of
these flags must be selected.
If MAP_SHARED is set in the flags argument:
o If the region is a mapped region, modifications to the region
are visible to other processes that mapped the same region
using MAP_SHARED.
o 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, use
the msync function to ensure that this is done.)
If MAP_PRIVATE is set in the flags argument:
o Modifications to the mapped region by the calling process are
not visible to other processes that mapped the same region
using either MAP_PRIVATE or MAP_SHARED.
o Modifications to the mapped region by the calling process are
not written to the file.
It is unspecified whether modifications by processes that mapped
the region using MAP_SHARED are visible to other processes that
mapped the same region using MAP_PRIVATE.
The prot argument specifies access permissions for the mapped
region. Specify one of the following:
PROT_NONE No access
PROT_READ Read-only
PROT_WRITE Read/Write access
After the successful completion of the mmap function, you can
close the filedes argument 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.
NOTE
The following rules apply to OpenVMS specific file
references:
o Because of the additional file reference, if filedes is
not opened for file sharing, mmap reopens it with file
sharing enabled.
o The additional file reference that remains for mapped
regions implies that a later open, fopen, or create call
to the file that is mapped must specify file sharing.
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.
NOTE
Beginning with OpenVMS Version 7.2, while processing a MAP_
SHARED request, the mmap function constructs the flags
argument of the SYS$CRMPSC service as a bitwise inclusive
OR of those bits it sets by itself to fulfill the MAP_
SHARED request and those bits specified by the caller in
the optional argument.
By default, for MAP_SHARED the mmap function creates a
temporary group global section. The optional mmap argument
provides the caller with direct access to the features of
the SYS$CRMPSC system service.
Using the optional argument, the caller can create, for
example, a system global section (SEC$M_SYSGBL bit) or
permanent global section (SEC$M_PERM bit). For example,
to create a system permanent global section, the caller
can specify (SEC$M_SYSGBL | SEC$M_PERM) in the optional
argument.
The mmap function does not check or set any privileges.
It is the responsibility of the caller to set appropriate
privileges, such as SYSGBL privilege for SEC$M_SYSGBL, and
PRMGBL for SEC$M_PERM, before calling mmap with the optional
argument.
See also read, write, open, fopen, creat, and sysconf.
4 – Return Values
x The address where the mapping is placed.
MAP_FAILED Indicates an error; errno is set to one of the
following values:
o 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.
o EBADF - The filedes argument is not a valid
file descriptor.
o EINVAL -The flags or prot argument is
invalid, or the addr argument or off
argument is not a multiple of the page
size returned by sysconf(_SC_PAGE_SIZE).
o ENODEV - The file descriptor filedes refers
to an object that cannot be mapped, such as
a terminal.
o ENOMEM - There is not enough address space
to map len bytes.
o ENXIO - The addresses specified by the
range [off, off + len] are invalid for
filedes.
o EFAULT - The addr argument is an invalid
address.