References for mmap services

This section includes the following subroutine references:

• “The mmap() subroutine” on page 461

• “The mprotect() subroutine” on page 467

• “The msync() subroutine” on page 469

• “The munmap() subroutine” on page 471

The mmap() subroutine

Maps a file-system object into virtual memory.

Library

Standard C library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/mman.h>
void *mmap(addr, len, prot, flags, filedes, offset)
void *      addr;
size_t      len;
int         prot, flags, filedes;
off_t       offset;

Description

The mmap() subroutine creates a new mapped file or anonymous memory region by establishing a mapping between a process-address space and a file-system object. Care needs to be taken when using the mmap() subroutine if the program attempts to map itself. If the page containing executing instructions is currently referenced as data through an mmap mapping, the program will hang. Use the -H4096 binder option, and that will put the executable text on page boundaries. Then reset the file that contains the executable material, and view via an mmap mapping.

A region created by the mmap() subroutine cannot be used as the buffer for read or write operations that involve a device. Similarly, an mmap region cannot be used as the buffer for operations that require either a pin or xmattach operation on the buffer.

Modifications to a file-system object are seen consistently, whether accessed from a mapped file region or from the read or write subroutine.

Child processes inherit all mapped regions from the parent process when the fork subroutine is called. The child process also inherits the same sharing and protection attributes for these mapped regions. A successful call to any exec subroutine will unmap all mapped regions created with the mmap() subroutine.

The mmap64() subroutine is identical to the mmap subroutine() except that the starting offset for the file mapping is specified as a 64-bit value. This permits file mappings which start beyond OFF_MAX.

In the large file enabled programming environment, mmap() is redefined to be mmap64().

If the application has requested SPEC1170 compliant behavior, then the st_atime field of the mapped file is marked for update upon successful completion of the mmap() call.

If the application has requested SPEC1170 compliant behavior, then the st_ctime and st_mtime fields of a file that is mapped with MAP_SHARED and PROT_WRITE are marked for update at the next call to msync() subroutine or munmap() subroutine if the file has been modified.

Parameters

Return values

If successful, the mmap() subroutine returns the address at which the mapping was placed. Otherwise, it returns -1 and sets the errno global variable to indicate the error.

Error codes

Under the following conditions, the mmap subroutine fails and sets the errno global variable to:

The mprotect() subroutine

Modifies access protections for memory mapping.

Library

Standard C library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/mman.h>

int mprotect ( addr,  len,  prot)
void *addr;
size_t len;
int prot;

Description

The mprotect() subroutine modifies the access protection of a mapped file region or anonymous memory region created by the mmap() subroutine. The behavior of this function is unspecified if the mapping was not established by a call to the mmap() subroutine.

Parameters

Return values

When successful, the mprotect() subroutine returns 0. Otherwise, it returns -1 and sets the errno global variable to indicate the error.

Error codes

If the mprotect() subroutine is unsuccessful, the errno global variable may be set to one of the following values:

The msync() subroutine

Synchronizes a mapped file.

Library

Standard C library (libc.a).

Syntax

#include <sys/types.h>
#include <sys/mman.h>
int msync ( addr,  len,  flags)
void *addr;
size_t len;
int flags;

Description

The msync() subroutine controls the caching operations of a mapped file region. Use the msync() subroutine to transfer modified pages in the region to the underlying file storage device.

If the application has requested Single UNIX Specification Version 2 compliant behavior then the st_ctime and st_mtime fields of the mapped file are marked for update upon successful completion of the msync() subroutine call if the file has been modified.

Parameters

Return values

When successful, the msync() subroutine returns 0. Otherwise, it returns -1 and sets the errno global variable to indicate the error.

Error codes

If the msync() subroutine is unsuccessful, the errno global variable is set to one of the following values:

The munmap() subroutine

Unmaps a mapped region.

Library

Standard C library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/mman.h>
int munmap ( addr,  len)
void *addr;
size_t len;

Description

The munmap() subroutine unmaps a mapped file region or anonymous memory region. The munmap() subroutine unmaps regions created from calls to the mmap() subroutine only.

If an address lies in a region that is unmapped by the munmap subroutine and that region is not subsequently mapped again, any reference to that address will result in the delivery of a SIGSEGV signal to the process.

Parameters

Return values

When successful, the munmap() subroutine returns 0. Otherwise, it returns -1 and sets the errno global variable to indicate the error.

Error codes

If the munmap() subroutine is unsuccessful, the errno global variable is set to the following value: