mmap(2)mmap(2)NAMEmmap - Map a file system object into virtual memory
SYNOPSIS
#include <sys/mman.h>
void *mmap(
void *addr,
size_t len,
int prot,
int flags,
int filedes,
off_t off );
[Tru64 UNIX] The following definition of the mmap() function does not
conform to current standards and is supported only for backward compat‐
ibility: caddr_t mmap(
caddr_t addr,
size_t len,
int prot,
int flags,
int filedes,
off_t off );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
mmap(): XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
Standards: standards(5)PARAMETERS
Specifies the starting address of the new region (truncated to a page
boundary). Specifies the length in bytes of the new region (rounded up
to a page boundary). Specifies access permissions as either PROT_NONE
or the result of a logical OR operation on any combination of
PROT_READ, PROT_WRITE, and PROT_EXEC. Specifies attributes of the
mapped region as the results of a bitwise-inclusive OR operation on any
combination of MAP_FILE, MAP_ANONYMOUS, MAP_VARIABLE, MAP_FIXED,
MAP_SHARED, MAP_PRIVATE, MAP_INHERIT, or MAP_UNALIGNED. Specifies the
file to be mapped to the new mapped file region returned by open().
Specifies the offset into the file that gets mapped at address addr.
DESCRIPTION
The mmap() function creates a new mapped file region, a new private
region, or a new shared memory region.
The addr and len parameters specify the requested starting address and
length in bytes for the new region. The address is a multiple of the
page size returned by the sysconf(_SC_PAGE_SIZE) call.
If the len parameter is not a multiple of the page size returned by the
sysconf(_SC_PAGE_SIZE) call, then the result of any reference to an
address between the end of the region and the end of the page contain‐
ing the end of the region is undefined.
The flags parameter specifies attributes of the mapped region. Values
of the flags parameter are constructed by a bitwise-inclusive OR opera‐
tion on the flags from the following list of symbolic names, which are
defined in the <sys/mman.h> file: Create a mapped file region. Create
an unnamed memory region. Place region at the computed address. Place
region at a fixed address. Share changes. Changes are private.
Region is not unmapped by an exec call. Do not verify that the file
offset is page aligned.
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.
One of these flags must be selected.
If MAP_FILE is set in the flags parameter: A new mapped file region is
created, mapping the file associated with the filedes parameter. The
off parameter specifies the file byte offset at which the mapping
starts. This offset must be a multiple of the page size returned by the
sysconf(_SC_PAGE_SIZE) call. 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: A new memory region is
created and initialized to all zeros. This memory region can be shared
only with descendents of the current process. 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. 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 parameter: 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 parameter: 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 will be unmapped.) If the requested address is null and MAP_FIXED
is specified, the region is placed at the default exact mapping address
for the region. The call places the region at this value exactly,
replacing previous mappings if necessary. The exact mapping address is
determined from a combination of the flag and protection parameters
passed to the mmap() function.
The MAP_PRIVATE and MAP_SHARED flags control the visibility of modifi‐
cations to the mapped file or shared memory region. One of these flags
must be selected.
If MAP_SHARED is set in the flags parameter: If the region is a mapped
region, modifications to the region are visible to other processes that
have mapped the same region using MAP_SHARED. 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 modi‐
fications must be written to the file immediately, the msync() function
can be used to ensure that this is done.)
If MAP_PRIVATE is set in the flags parameter: Modifications to the
mapped region by the calling process are not visible to other processes
that have mapped the same region using either MAP_PRIVATE or
MAP_SHARED. Modifications to the mapped region by the calling process
are not written to the file.
It is unspecified whether modifications by processes that have mapped
the region using MAP_SHARED are visible to other processes that have
mapped the same region using MAP_PRIVATE.
If MAP_INHERIT is set in the flags parameter: The mapped region cannot
be removed from the address space of the calling process by an exec
system call.
If MAP_UNALIGNED is set in the flags parameter: The mmap() system call
is prevented from verifying that the file offset is page aligned.
The prot parameter specifies the mapped region's access permissions.
The <sys/mman.h> header file defines the following access options: The
mapped region can be read. The mapped region can be written. The
mapped region can be executed. The mapped region cannot be accessed.
The prot parameter can be either PROT_NONE or the results of a logical
OR operation on any combination of PROT_READ, PROT_WRITE, and
PROT_EXEC. 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 permission only if the file descriptor used to map the
file is open for writing. If the region is a mapped file that 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 that
was mapped with MAP_ANONYMOUS, the mmap() function grants all requested
access permissions.
After the successful completion of the mmap() function, the filedes
parameter can be closed without effect on the mapped region or on the
contents of the mapped file. Each mapped region creates a file refer‐
ence, similar to an open file descriptor, which prevents the file data
from being deallocated.
Modifications made to the file by using the write() function are visi‐
ble to mapped regions, and modifications to a mapped region are visible
with the read() function.
After a call to the fork() function, the child process inherits all
mapped regions with the same sharing and protection attributes as in
the parent process. Each mapped file and shared memory region created
with the mmap() function is unmapped by a successful call to any of the
exec functions, unless that region is made inheritable across the exec
call.
NOTES
The memory acquired with the mmap() function is not locked, regardless
of the previous use of the plock() function.
An mmap() call will fail on a file that has direct I/O enabled.
For AdvFS files, use the msync() function to write out modified file
data in a memory region established by mmap(). This is necessary to
ensure the integrity of the changes in the data being written.
RETURN VALUES
Upon successful completion, the mmap() function returns the address at
which the mapping was placed. Otherwise, mmap() returns the value of
MAP_FAILED. The MAP_FAILED symbol is defined in the <sys/mman.h> header
file.
ERRORS
If the mmap() function fails, errno is set to one of the following val‐
ues:
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. The filedes parameter is not a valid
file descriptor. The addr parameter is an invalid address. The flags
or prot parameter is invalid, or the addr parameter or off parameter is
not a multiple of the page size returned by the sysconf(_SC_PAGE_SIZE)
call. This error is also returned if the file is already open for
atomic write data logging or direct I/O. The file descriptor filedes
refers to an object that cannot be mapped, such as a terminal. There
is not enough address space to map len bytes. The addresses specified
by the range [off, off + len] are invalid for filedes.
SEE ALSO
Functions: exec(2), fcntl(2), fork(2), madvise(2), mprotect(2),
msync(2), munmap(2), plock(2), sysconf(3)
Standards: standards(5)mmap(2)
