mmap

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:
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:

If MAP_ANONYMOUS is set in the flags argument:

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 MAP_FIXED is set in the flags argument:

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 MAP_PRIVATE is set in the flags argument:

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:

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
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