ra_mmap or ra_mmapv Subroutine

Edit online

Purpose

Maps a file or anonymous memory region into the process-address space and attaches the file or memory region to a given resource.

Library

Standard C Library (libc.a)

Syntax

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

void * ra_mmap( addr, len, prot, flags, fildes, off, rstype, rsid, policy )
void *addr;
off64_t len;
int prot;
int flags;
int fildes;
off64_t off;
rstype_t rstype;
rsid_t rsid;
unsigned int policy;

void * ra_mmapv( addr, len, prot, flags, fildes, off, rangecnt, rangevec )
void *addr;
off64_t len;
int prot;
int flags;
int fildes;
off64_t off;
int rangecnt;
subrange_t *rangevec;

Description

The ra_mmap subroutine maps the file or memory region, specified by mmap_params, into the process-address space and attaches it to the resource set specified by rstype and rsid. The resource set specified for attachment defines the resource allocation domains (RADs) from which the mapping's memory demands should be fulfilled. If the file or memory region is attached to a resource set specifying multiple RADs, its memory allocation is distributed among these RADs according to policy.

If a file is being mapped, the attachment for the new mapped region is reflected down to the portion of the file it maps and persists after the region is unmapped. The file's attachment persists until the last close of the file.

The ra_mmapv subroutine is similar to the ra_mmap subroutine, and allows multiple subranges of a file or memory region to be attached to different resource sets in a single ra_mmapv call.

The rangecnt argument specifies the number of subranges being mapped. The rangevec argument is a pointer to an array of subrange_t structures describing the attachments to be performed. Each subrange_t structure specifies a portion of the file or memory region and the resource set to which the portion should be attached. If overlapping subranges are specified, ra_mmapv does not fail, but its behavior is undefined.

Child processes inherit all mapped regions and their resource set attachments 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 unmaps all mapped regions created with the ra_mmap subroutine.

Attachments to a given RAD do not attach the process to the processors in that RAD. Attachments are only advisory; memory from a different RAD can be provided if the demand cannot be fulfilled from the RAD specified.

If overlapping subranges are mapped with attachments, the memory placement of the mapped regions is undefined.

The su_rsoffset and su_rslength fields of the subrange_t structures must be set to 0. Otherwise, ra_mmapv fails with EINVAL.

Parameters

Item Description
addr Specifies the starting address of the memory region to be mapped. When the MAP_FIXED flag is specified, this address must be a multiple of the page size returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter. A region is never placed at address 0, or at an address where it would overlap an existing region.
fildes Specifies the file descriptor of the file-system object or of the shared memory object to be mapped. If the MAP_ANONYMOUS flag is set, the fildes parameter must be -1. After the successful completion of the ra_mmap or ra_mmapv subroutine, the file or the shared memory object specified by the fildes parameter can be closed without affecting the mapped region or 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.
flags Specifies attributes of the mapped region. Values for the flags parameter are constructed by a bitwise-inclusive ORing of values from the following list of symbolic names defined in the sys/mman.h file:
MAP_FILE
Specifies the creation of a new mapped file region by mapping the file associated with the fildes file descriptor. The mapped region can extend beyond the end of the file, both at the time when the ra_mmap subroutine is called and while the mapping persists. This situation could occur if a file with no contents was created just before the call to the ra_mmap subroutine, or if a file was later truncated. However, references to whole pages following the end of the file result in the delivery of a SIGBUS signal. Only one of the MAP_FILE and MAP_ANONYMOUS flags must be specified with the ra_mmap or ra_mmapv subroutine.
MAP_ANONYMOUS
Specifies the creation of a new, anonymous memory region that is initialized to all zeros. This memory region can be shared only with the descendants of the current process. When using this flag, the fildes parameter must be -1. Only one of the MAP_FILE and MAP_ANONYMOUS flags must be specified with the ra_mmap or ra_mmapvsubroutine.
MAP_VARIABLE
Specifies that the system select an address for the new memory region if the new memory region cannot be mapped at the address specified by the addr parameter, or if the addr parameter is null. Only one of the MAP_VARIABLE and MAP_FIXED flags must be specified with the ra_mmap or ra_mmapv subroutine.
MAP_FIXED
Specifies that the mapped region be placed exactly at the address specified by the addr parameter. If the application has requested SPEC1170 complaint behavior and the ra_mmap or ra_mmapv request is successful, the mapping replaces any previous mappings for the process' pages in the specified range. If the application has not requested SPEC1170 compliant behavior and a previous mapping exists in the range, the request fails. Only one of the MAP_VARIABLE and MAP_FIXED flags must be specified with the ra_mmap or ra_mmapv subroutine.
MAP_SHARED
When the MAP_SHARED flag is set, modifications to the mapped memory region will be visible to other processes that have mapped the same region using this flag. If the region is a mapped file region, modifications to the region will be written to the file. You can specify only one of the MAP_SHARED or MAP_PRIVATE flags with the ra_mmap or ra_mmapv subroutine. MAP_PRIVATE is the default setting when neither flag is specified unless you request SPEC1170 compliant behavior. In this case, you must choose either MAP_SHARED or MAP_PRIVATE.
MAP_PRIVATE
When the MAP_PRIVATE flag is specified, modifications to the mapped region by the calling process are not visible to other processes that have mapped the same region. If the region is a mapped file region, modifications to the region are not written to the file. If this flag is specified, the initial write reference to an object page creates a private copy of that page and redirects the mapping to the copy. Until then, modifications to the page by processes that have mapped the same region with the MAP_SHARED flag are visible. You can specify only one of the MAP_SHARED or MAP_PRIVATE flags with the ra_mmap or ra_mmapv subroutine. MAP_PRIVATE is the default setting when neither flag is specified unless you request SPEC1170 compliant behavior. In this case, you must choose either MAP_SHARED or MAP_PRIVATE.
len Specifies the length, in bytes, of the memory region to be mapped. The system performs mapping operations over whole pages only. If the len parameter is not a multiple of the page size, the system will include in any mapping operation the address range between the end of the region and the end of the page containing the end of the region.
off Specifies the file byte offset at which the mapping starts. This offset must be a multiple of the page size returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter.
Item Description
policy Specifies an advisory memory allocation policy that is to be applied. This parameter must have one of the following values defined in sys/rset.h:
P_FIRST_TOUCH
First Access memory policy. Memory is allocated from the RAD of the processor on which it is accessed the first time if this RAD is in the attachment resource set. Otherwise, memory is allocated from any RAD with memory available to the processor.
P_BALANCED
Balanced memory policy. Memory is allocated in a round robin manner across the RADs contained in the attachment resource set.
P_DEFAULT
Default memory placement policy.
prot Specifies the access permissions for the mapped region. The sys/mman.h file defines the following access options:
PROT_READ
Region can be read.
PROT_WRITE
Region can be written.
PROT_EXEC
Region can be executed.
PROT_NONE
Region cannot be accessed.
The prot parameter can be the PROT_NONE flag, or any combination of the PROT_READ flag, PROT_WRITE flag, and PROT_EXEC flag logically ORed together. If the PROT_NONE flag is not specified, access permissions can be granted to the region in addition to those explicitly requested. However, write access will not be granted unless the PROT_WRITE flag is specified.
Note: The operating system generates a SIGSEGV signal if a program attempts an access that exceeds the access permission given to a memory region. For example, if the PROT_WRITE flag is not specified and a program attempts a write access, a SIGSEGV signal results.
If the region is a mapped file that was mapped with the MAP_SHARED flag, the ra_mmap or ra_mmapv subroutine grants read or execute access permission only if the file descriptor used to map the file was opened for reading. It grants write access permission only if the file descriptor was opened for writing. If the region is a mapped file that was mapped with the MAP_PRIVATE flag, the ra_mmap or ra_mmapv subroutine grants read, write, or execute access permission only if the file descriptor used to map the file was opened for reading. If the region is an anonymous memory region, the ra_mmap or ra_mmapv subroutine grants all requested access permissions.
rangecnt Specifies the number of subrange_t structures pointed to by rangevec.
rangevec Specifies a pointer to an array of subrange_t structures describing the desired subrange attachments.
rsid Identifies the resource to be attached to the file or memory region. All attachments are advisory. If memory cannot be allocated from the RADs identified by the resource, memory is allocated from any RAD in the system.
  • Resource set handle (for rstype R_RSET): set the rsid.at_rset field to the desired resource set.
  • SRADID (Scheduler Resource Allocation Domain Identifier for rstype R_SRADID): set the rsid.at_sradid field to the desired sradid.
rstype Specifies the type of resource the file or memory region is to be attached to. This parameter must have one of the following values:
  • R_RSET: Resource set attachment
  • R_SRADID: SRADID attachment
The MAP_ANONYMOUS flags field must be specified if rstype R_SRADID is specified.

Return Values

Upon successful completion, an address to the mapped file or memory region is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

Item Description
EACCES The file referred to by the fildes parameter is not open for read access, or the file is not open for write access and the PROT_WRITE flag was specified for a MAP_SHARED mapping operation. Or, the file to be mapped has enforced locking enabled and the file is currently locked.
EAGAIN The fildes parameter refers to a device that has already been mapped.
EBADF The fildes parameter is not a valid file descriptor, or the MAP_ANONYMOUS flag was set and the fildes parameter is not -1.
EFBIG The mapping requested extends beyond the maximum file size associated with fildes.
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 the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter.
EINVAL The application has requested SPEC1170 compliant behavior and the value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).
EINVAL The subrange_t structure specifies an invalid range.
EINVAL The su_rsoffset and su_rslength fields of a subrange_t do not have a value of 0.
EINVAL The resource type is invalid (is not of type R_RSET).
EINVAL The application has requested SPEC1170 compliant behavior and the value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).
EMFILE The application has requested SPEC1170 compliant behavior and the number of mapped regions would exceed an implementation-dependent limit (per process or per system).
ENODEV The fildes parameter refers to an object that cannot be mapped, such as a terminal.
ENODEV An invalid rsid SRADID is specified.
ENOMEM There is not enough address space to map len bytes, or the application has not requested Single UNIX Specification, Version 2 compliant behavior and the MAP_FIXED flag was set and part of the address-space range (addr, addr+len) is already allocated.
ENOSYS The ra_mmap subroutine is not supported on the system.
ENOSYS The file specified is of a type that does not support physical attachments.
ENOTSUP An attempt to map a memory region with an SRADID attachment is made and ENHANCED_AFFINITY is disabled.
ENOTSUP An attempt to map a file with an SRADID attachment was made.
ENXIO The addresses specified by the range (off, off+len) are invalid for the fildes parameter.
EOVERFLOW The mapping requested extends beyond the offset maximum for the file description associated with fildes.
EPERM The calling process does not have the necessary attachment privileges.