OSF

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

addrSpecifies the starting address of the new region. 

lenSpecifies the length in bytes of the new region. 

protSpecifies access permissions as any combination of PROT_READ, PROT_WRITE and PROT_EXEC ORed together, or PROT_NONE. 

flagsSpecifies attributes of the mapped region with any combination of MAP_FILE, MAP_ANONYMOUS, MAP_VARIABLE, MAP_FIXED, MAP_SHARED, or MAP_PRIVATE, ORed together. 

filedesSpecifies the file to be mapped to the new mapped file region. 

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

       •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 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 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.  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 existing region.  Exactly 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, and it is not possible for the region to be placed at this address, the mmap() function fails. 

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

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

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

       •Modifications to the mapped region by the calling process are not visible to other processes which 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 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 permissions.  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 permission 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 deallocated. 

Whether modifications made to the file using the write() function are visible to mapped regions, and whether modifications to a mapped region are visible with the read() function, 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 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 exec. 

NOTES

Note that memory acquired with the mmap() function is not locked, regardless of the previous use of the plock() function. 

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 the error. 

ERRORS

If the mmap() function fails, errno may be 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 parameter is not a valid file descriptor. 

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