NAME
mmap - Maps file system object into virtual memory
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
caddr_t mmap (
caddr_t addr,
size_t len,
int prot,
int flags,
int filedes,
off_t off );
PARAMETERS
addr Specifies the starting address of the new region.
len Specifies the length in bytes of the new region.
prot Specifies access permissions as any combination of
PROT_READ, PROT_WRITE and PROT_EXEC ORed together,
or PROT_NONE.
flags Specifies attributes of the mapped region with any
combination of MAP_FILE, MAP_ANONYMOUS,
MAP_VARIABLE, MAP_FIXED, MAP_SHARED, or
MAP_PRIVATE, ORed together.
filedes Specifies the file to be mapped to the new mapped
file region.
off Specifies the offset for the address.
DESCRIPTION
The mmap() function creates a new mapped file or shared
memory region.
The addr and len parameters specify the requested starting
address and length in bytes for the new region. This
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
bitwise-inclusive ORing 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.
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. Exactly one of these flags must be
selected.
If MAP_FILE is set in the flags parameter:
o A new mapped file region is created, mapping the file
associated with the filedes parameter.
o The off parameter specifies the file byte offset at
which the mapping starts. This offset must be a multi-
ple 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 parameter:
o A new memory region is created and initialized to all
zeros. This memory region can be shared only with des-
cendents of the current process.
o 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. The MAP_VARIABLE and MAP_FIXED
flags control the placement of the region when the requested
address is null or the region cannot be placed at the
requested address. A region is never placed at address
zero, or at an address where it would overlap with an exist-
ing region. Exactly one of these flags must be selected.
If MAP_VARIABLE is set in the flags parameter:
o If the requested address is null, or if it is not pos-
sible 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 parameter:
o If the requested address is not null, and it is not
possible for the region to be placed at this address,
the mmap() function fails.
o If the requested address is null, the region is placed
at the default exact mapping address for the region.
If there is no default exact mapping address for the
region, the region is placed at an address selected by
the system, and this address becomes the default exact
mapping address for all subsequent attempts to map the
same region, until all mappings of the region are
unmapped. If it is not possible to place the region at
the default exact mapping address, the mmap() function
fails. Two mapped file regions are considered the same
region for the purpose of default exact mapping if they
map the same file and start at the same file offset.
The MAP_PRIVATE and MAP_SHARED flags control the visibility
of modifications to the mapped file or shared memory region.
Exactly one of these flags must be selected.
If MAP_SHARED is set in the flags parameter:
o If the region is a mapped file region, modifications to
the region are visible to other processes which have
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.
If MAP_PRIVATE is set in the flags parameter:
o Modifications to the mapped region by the calling pro-
cess are not visible to other processes which have
mapped the same region using either MAP_PRIVATE or
MAP_SHARED.
o Modifications to the mapped region by the calling pro-
cess are not written to the file.
It is unspecified whether modifications by processes which
have mapped the region using MAP_SHARED are visible to other
processes which have mapped the same region using
MAP_PRIVATE.
The prot parameter specifies the mapped region's access per-
missions. 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 PROT_NONE or any combination of
PROT_READ, PROT_WRITE, and PROT_EXEC ORed together. 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 descriptor 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 writing. If the region is a mapped file which 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 which was mapped with
MAP_ANONYMOUS, the mmap() function grants all requested
access permissions.
After the successful completion of the mmap() function, the
filedes parameter may 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.
Whether modifications made to the file using the write()
function are visible to mapped regions, and whether modifi-
cations to a mapped region are visible with the read() func-
tion, is undefined, except for the effect of the msync()
function.
After a call to the fork() function, the child process
inherits all mapped regions with the same sharing and pro-
tection attributes as in the parent process. Each mapped
file and shared memory region created with the mmap() func-
tion 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, regardless of the previous use of the plock() func-
tion.
AES Support Level:
Trial use
RETURN VALUES
Upon successful completion, the mmap() function returns the
address at which the mapping was placed. Otherwise, mmap()
returns (caddr_t)-1 and sets errno to indicate the error.
ERRORS
If the mmap() function fails, errno may be set to one of the
following values:
[EAGAIN] The mapping could not be locked in memory.
[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 descrip-
tor.
[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).
[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, or MAP_FIXED was set and part of the
address space range [addr, addr + len) is already
allocated.
[ENXIO] The addresses specified by the range [off, off +
len) are invalid for filedes.
[EINVAL] MAP_ANONYMOUS was specified in flags and filedes
is not -1.
[EFAULT] The addr parameter is an invalid address.
RELATED INFORMATION
Functions: fcntl(2), fork(2), madvise(2), mprotect(2),
msync(2), munmap(2), plock(2), sysconf(3)
Acknowledgement and Disclaimer