Maps file system object into virtual memory.
Format
#include <types.h>
#include <mman.h>
void mmap (void *addr, size_t len, int
prot, int flags, int filesdes,
off_t off);
Function Variants
This function also has variants named _mmap32 and _mmap64 for
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using
pointer-size-specific functions.
Arguments
- addr
- The starting address of the new region (truncated to a page
boundary).
- len
- The length in bytes of the new region (rounded up to a page
boundary).
- 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:
- MAP_FILE or MAP_ANONYMOUS
- MAP_VARIABLE or MAP_FIXED
- 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 into the file that gets mapped at address
addr.
Description
This function creates a new mapped file region, a new private
region, or a new shared memory region.
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:
- A new mapped file region is created, mapping the file
associated with the filedes argument.
- 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).
- 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:
- A new memory region is created and initialized to all
zeros.
- If the filedes argument 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 argument:
- 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:
- 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.)
- 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:
- If the region is a mapped region, modifications to the
region are visible to other processes that 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, use the msync function to ensure
that this is done.)
If MAP_PRIVATE is set in the flags argument:
- 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.
- 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:
- Because of the additional file reference, if
filedes is not opened for file sharing, mmap reopens
it with file sharing enabled.
- 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.
See also read, write, open, fopen, creat, and sysconf in this
section.
Return Values
x | The address where the mapping
is placed. |
(caddr_t) -1 |
Indicates an error; errno is set to one of the following values:
- 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 argument is not a valid file
descriptor.
- 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). Or MAP_ANONYMOUS was specified in flags
and filedes is not -1.
- 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.
- ENXIO - The addresses specified by the range [off, off
+ len] are invalid for filedes.
- EFAULT - The addr argument is an invalid
address.
|
Previous Page | Next Page | Table of Contents | Index