mmap - Map a file system object into virtual memory
#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 compatibility: caddr_t mmap(
caddr_t addr,
size_t len,
int prot,
int flags,
int filedes,
off_t off );
Interfaces documented on this reference page conform to
industry standards 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)
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.
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 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 a
bitwise-inclusive OR operation 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 modifications 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 modifications 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 reference, 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 visible 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.
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.
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.
If the mmap() function fails, errno is set to one of the
following values:
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.
Functions: exec(2), fcntl(2), fork(2), madvise(2), mprotect(2), msync(2), munmap(2), plock(2), sysconf(3)
Standards: standards(5)
mmap(2)
[ Back ] |
