inadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Starting and ending virtual addresses into which the section is to be
mapped. The inadr argument is the address of a
2-longword array containing, in order, the starting and ending process
virtual addresses. Only the virtual page number portion of each virtual
address is used to specify which pages are to be mapped; the low-order
byte-within-page bits are ignored for this purpose.
The interpretation of the inadr argument depends on
the setting of SEC$M_EXPREG in the flags argument and
on whether you are using an Alpha or a VAX system. The two system types
are discussed separately in this section.
Alpha System Usage
On Alpha systems, if you do not set the SEC$M_EXPREG flag, the
inadr argument specifies the starting and ending
virtual addresses of the region to be mapped. Addresses in system space
are not allowed. The addresses must be aligned on CPU-specific pages;
no rounding to CPU-specific pages occurs. The lower address of the
inadr argument must be on a CPU-specific page boundary
and the higher address of the inadr argument must be 1
less than a CPU-specific boundary, thus forming a range, from lowest to
highest, of address bytes. You can use the SYI$_PAGE_SIZE item code in
the $GETSYI system service to set the inadr argument
to the proper values. You do this to avoid programming errors that
might arise because of incorrect programming assumptions about page
sizes.
If, on the other hand, you do set the SEC$M_EXPREG flag,
indicating that the mapping should take place using the first available
space in a particular region, the inadr argument is
used only to indicate the desired region: the program region (P0) or
the control region (P1).
Caution
Mapping into the P1 region is generally discouraged, but, if done, must
be executed with extreme care. Since the user stack is mapped in P1, it
is possible that references to the user stack might inadvertently read
or write the pages mapped with $CRMPSC.
|
When the SEC$M_EXPREG flag is set, the second inadr
longword is ignored, while bit 30 (the second most significant bit) of
the first inadr longword is used to determine the
region of choice. If the bit is clear, P0 is chosen; if the bit is set,
P1 is chosen. On Alpha systems, bit 31 (the most significant bit) of
the first inadr longword must be 0. To ensure
compatibility between VAX and Alpha systems when you choose a region,
Compaq recommends that you specify, for the first
inadr longword, any virtual address in the desired
region.
VAX System Usage
On VAX systems, if you do not set the SEC$M_EXPREG flag, the
inadr argument specifies the starting and ending
virtual addresses of the region to be mapped. Addresses in system space
are not allowed. If the starting and ending virtual addresses are the
same, a single page is mapped.
Note
If the SEC$M_EXPREG flag is not set, Compaq recommends that the
inadr argument always specify the entire virtual
address range, from starting byte address to ending byte address. This
ensures compatibility between VAX and Alpha systems.
|
If, on the other hand, you do set the SEC$M_EXPREG flag,
indicating that the mapping should take place using the first available
space in a particular region, the inadr argument is
used only to indicate the desired region: the program region (P0) or
the control region (P1).
Caution
Mapping into the P1 region is generally discouraged, but, if done, must
be executed with extreme care. Since the user stack is mapped in P1, it
is possible that references to the user stack might inadvertently read
or write the pages mapped with $CRMPSC.
|
When the SEC$M_EXPREG flag is set, the second inadr
longword is ignored, while bit 30 (the second most significant bit) of
the first inadr longword is used to determine the
region of choice. If the bit is clear, P0 is chosen; if the bit is set,
P1 is chosen. On VAX systems, bit 31 (the most significant bit) of the
first inadr longword is ignored. To ensure
compatibility between VAX and Alpha systems when you choose a region,
Compaq recommends that you specify, for the first
inadr longword, any virtual address in the desired
region.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Starting and ending process virtual addresses into which the section
was actually mapped by $MGBLSC. The retadr argument is
the address of a 2-longword array containing, in order, the starting
and ending process virtual addresses.
On Alpha systems, the retadr argument returns the
starting and ending addresses of the usable range of
addresses. This might differ from the total amount mapped. The
retadr argument is required when the
relpag argument is specified. If the section being
mapped does not completely fill the last page used to map the section,
the retadr argument indicates the highest address that
actually maps the section. If the relpag argument is
used to specify an offset into the section, the retadr
argument reflects the offset.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be associated with the pages mapped into the process
virtual address space. The acmode argument is a
longword containing the access mode. The $PSLDEF macro defines symbols
for the four access modes.
The most privileged access mode used is the access mode of the caller.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying options for the operation. The
flags argument is a longword bit vector wherein a bit
when set specifies the corresponding option.
The $SECDEF macro defines symbolic names for the flag bits. You
construct the flags argument by specifying the
symbolic names of each desired option in a logical OR operation.
The following table describes each flag option:
| Flag Option |
Description |
|
SEC$M_WRT
|
Map the section with read/write access. By default, the section is
mapped with read-only access. If SEC$M_WRT is specified and the section
is not copy-on-reference, write access is required.
|
|
SEC$M_SYSGBL
|
Map a system global section. By default, the section is a group global
section.
|
|
SEC$M_EXPREG
|
Map the section into the first available virtual address range. By
default, the section is mapped into the range specified by the
inadr argument.
See the
inadr argument description for a complete explanation
of how to set the SEC$M_EXPREG flag.
|
gsdnam
| OpenVMS usage: |
section_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the global section. The gsdnam argument is the
address of a character string descriptor pointing to this name string.
For group global sections, the operating system interprets the group
UIC as part of the global section name; thus, the names of global
sections are unique to UIC groups. Further, all global section names
are implicitly qualified by their identification fields.
You can specify any name from 1 to 43 characters. All processes mapping
to the same global section must specify the same name. Note that the
name is case sensitive.
Use of characters valid in logical names is strongly encouraged. Valid
values include alphanumeric characters, the dollar sign ($), and the
underscore (_). If the name string begins with an underscore (_), the
underscore is stripped and the resultant string is considered to be the
actual name. Use of the colon (:) is not permitted.
Names are first subject to a logical name translation, after the
application of the prefix GBL$ to the name. If the result translates,
it is used as the name of the section. If the resulting name does not
translate, the name specified by the caller is used as the name of the
section.
Additional information on logical name translations and on section name
processing is available in the OpenVMS Programming Concepts Manual.
ident
| OpenVMS usage: |
section_id |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Identification value specifying the version number of a global section
and, for processes mapping to an existing global section, the criteria
for matching the identification. The ident argument is
the address of a quadword structure containing three fields.
The first longword specifies, in the low-order two bits, the matching
criteria. Their valid values, the symbolic names by which they can be
specified, and their meanings are as follows:
| Value/Name |
Match Criteria |
|
0 SEC$K_MATALL
|
Match all versions of the section.
|
|
1 SEC$K_MATEQU
|
Match only if major and minor identifications match.
|
|
2 SEC$K_MATLEQ
|
Match if the major identifications are equal and the minor
identification of the mapper is less than or equal to the minor
identification of the global section.
|
The version number is in the second longword and contains two fields: a
minor identification in the low-order 24 bits and a major
identification in the high-order 8 bits.
If you do not specify ident or specify it as the value
0 (the default), the version number and match control fields default to
the value 0.
relpag
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Relative page number within the section of the first page to be mapped.
The relpag argument is a longword containing this
number.
On Alpha systems, the relpag argument is interpreted
as an index into the section file, measured in pagelets for a
file-backed section or CPU-specific pages for a PFN-mapped section.
On Alpha and VAX systems, if you do not specify relpag
or specify it as the value 0 (the default), the global section is
mapped beginning with the first virtual block in a file-backed section
or the first CPU-specific page in a PFN-mapped section.
The Map Global Section service establishes a correspondence between
pages (maps) in the virtual address space of the process and physical
pages occupied by a global section. The protection mask specified at
the time the global section is created determines the type of access
(for example, read/write or read only) that a particular process has to
the section.
When $MGBLSC maps a global section, it adds pages to the virtual
address space of the process. The section is mapped from a low address
to a high address, whether the section is mapped in the program or
control region.
If an error occurs during the mapping of a global section, the return
address array, if specified, indicates the pages that were successfully
mapped when the error occurred. If no pages were mapped, both longwords
of the return address array contain the value --1.
Required Access or Privileges
Read access is required. If the SEC$M_WRT flag is specified, write
access is required.
Required Quota
The working set quota (WSQUOTA) of the process must be sufficient to
accommodate the increased size of the virtual address space when the
$MGBLSC service maps a section.
If the section pages are copy-on-reference, the process must also have
sufficient paging file quota (PGFLQUOTA).
This system service causes the working set of the calling process to be
adjusted to the size specified by the working set quota (WSQUOTA). If
the working set size of the process is less than quota, the working set
size is increased; if the working set size of the process is greater
than quota, the working set size is decreased.
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,
$LKWSET, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC,
$UPDSECW
For more information, refer to the chapter on memory management in the
OpenVMS Programming Concepts Manual.
